Tax and Shipping Estimation

The SimpleCheckout API provides real-time tax and shipping estimates for checkouts, helping you calculate total costs before completing a purchase.

⚠️ Beta Feature: Tax and shipping estimation is currently in beta. We're continuously improving accuracy and store coverage. Need support for a new store? Reach out to us.

Endpoint

POST /v0/fees/estimate

Request Format

The estimation endpoint accepts cart items grouped by store along with a shipping address:

{
  "address": {
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  },
  "carts": [
    {
      "store_domain": "example-store.com",
      "items": [
        {
          "id": "item-001",
          "base_price": 29.99,
          "url": "https://example-store.com/product/shirt",
          "category": "clothing",
          "info": {"size": "M", "color": "blue", "sku": "SHIRT-001"}
        },
        {
          "id": "item-002",
          "base_price": 49.99,
          "url": "https://example-store.com/product/shoes",
          "info": {"size": "10", "sku": "SHOES-002"}
        }
      ]
    }
  ]
}

Address Fields

Using Stripe-like address format for standardization:

• line1 (required): Primary address line
• line2 (optional): Secondary address line (apartment, suite, etc.)
• city (required): City name
• state (optional): State or province code
• postal_code (required): ZIP or postal code
• country (required): Country code (currently only "US" supported)

Item Fields

Each item in a cart can include:

• id (required): Unique identifier for the item provided by the user.
• base_price (required): Item price as a number
• url (optional): Product URL
• category (optional): Product category (e.g., "clothing", "food") - helps with tax exemptions
• info (optional): Any additional information as JSON object - passed through unchanged

Response Format

Returns calculated costs for each cart:

{
  "carts": [
    {
      "store_domain": "example-store.com",
      "items": [
        {
          "id": "item-001",
          "base_price": "29.99",
          "url": "https://example-store.com/product/shirt",
          "category": "clothing",
          "info": {"size": "M", "color": "blue", "sku": "SHIRT-001"}
        },
        {
          "id": "item-002", 
          "base_price": "49.99",
          "url": "https://example-store.com/product/shoes",
          "info": {"size": "10", "sku": "SHOES-002"}
        }
      ],
      "base_price": "79.98",
      "shipping": "8.99",
      "tax": "7.02",
      "expected_price": "95.99"
    }
  ]
}

Response Fields:

• id: Item identifier (exactly as provided in request)
• base_price: String with 2 decimal places (e.g., "79.90")
• shipping: Estimated shipping cost as string
• tax: Calculated tax amount as string
• expected_price: Total estimated cost (base + shipping + tax)
• info: Additional item information (exactly as provided in request)

Supported Stores

Get the list of currently supported stores for tax and shipping estimation:

curl https://api.simplecheckout.ai/v0/fees/stores

Response:

{
  "stores": [
    "revolve.com",
    "nordstrom.com", 
    "tomfordfashion.com",
    "gucci.com",
    "zara.com",
    "gymshark.com",
    ...
  ]
}

Example Request

curl -X POST https://api.simplecheckout.ai/v0/fees/estimate \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "line1": "850 Hartford Tpke",
      "line2": "Ste 12",
      "city": "Waterford",
      "state": "CT",
      "postal_code": "06385",
      "country": "US"
    },
    "carts": [
      {
        "store_domain": "zara.com",
        "items": [
          {
            "id": "item-123",
            "base_price": 79.90,
            "url": "https://www.zara.com/us/en/regular-fit-denim-shorts-p09942340.html",
            "category": "clothing",
            "info": {"size": "M", "color": "blue", "sku": "ZR-123"}
          }
        ]
      }
    ]
  }'

Response:

{
  "carts": [
    {
      "store_domain": "zara.com",
      "items": [
        {
          "id": "item-123",
          "base_price": "79.90", 
          "url": "https://www.zara.com/us/en/regular-fit-denim-shorts-p09942340.html",
          "info": {"size": "M", "color": "blue", "sku": "ZR-123"},
          "category": "clothing"
        }
      ],
      "base_price": "79.90",
      "shipping": "4.95", 
      "tax": "5.39",
      "expected_price": "90.24"
    }
  ]
}

Notes

• Currently supports US addresses only
• Tax rates are calculated based on the shipping address
• Shipping costs may vary by store and item category
• The category field is optional but can improve estimation accuracy