Get Checkout Estimates

Time	Status	User Agent
Retrieving recent requests…

Compute a pre-checkout cost estimate for a given merchant, destination, and list of items — including subtotal, shipping, and tax — without initiating a full checkout. Works across CartAI's merchant network including Shopify stores and major retailers.

When to Use This Endpoint

Use /checkout-estimates to show users an accurate order total before they commit to a purchase. It is a read-only operation — no cart is created and no order is placed.

Use case	Recommended approach
Show order total before checkout	Call `/checkout-estimates` and display `total` to the user
Surface itemised tax and shipping	Break down `tax`, `shipping`, and `subtotal` from the response
Compare shipping costs across destinations	Call with different `destination.zip` values
Validate pricing before calling `POST /checkout`	Confirm `subtotal` matches expected `unitPrice × quantity`

Authentication

Every request must include your API key in the request header.

x-api-key: YOUR_API_KEY_HERE

Never embed your API key in client-side code. Always call this endpoint from your backend.

Request Body

Field	Type	Required	Description
`merchant`	string	✅ Yes	Name of the merchant (e.g. `"Natori"`).
`destination`	object	✅ Yes	Delivery destination. See `destination` below.
`items`	array	✅ Yes	List of items to estimate. See `items[]` below.

`destination`

Field	Type	Required	Description
`zip`	string	✅ Yes	Destination ZIP code.

`items[]`

Field	Type	Required	Description
`url`	string	✅ Yes	Product page URL on the merchant's site.
`quantity`	integer	✅ Yes	Number of units.
`unitPrice`	number	✅ Yes	Price per unit, used to compute `lineSubtotal`.
`category`	string	✅ Yes	Product category (e.g. `"clothing"`). Used for tax calculation.

Example Request

curl --location 'https://api.cartai.ai/checkout-estimates' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <your-api-key>' \
--data '{
  "merchant": "Natori",
  "destination": {
    "zip": "75001"
  },
  "items": [
    {
      "url": "https://www.natori.com/products/feathers-plunge-t-shirt-bra-black",
      "quantity": 1,
      "unitPrice": 72,
      "category": "clothing"
    }
  ]
}'

Response Schema

A successful 200 response returns a JSON object with the following structure.

Top-level fields

Field	Type	Description
`status`	string	`"success"` when the estimate was computed.
`message`	string	Human-readable summary (e.g. `"Estimate computed"`).
`data`	object	Contains the full cost breakdown. See `data` below.

`data`

Field	Type	Description
`currency`	string	ISO 4217 currency code (e.g. `"USD"`).
`merchant`	string	Merchant name echoed from the request.
`destination`	object	Resolved destination including state. See `destination` below.
`subtotal`	number	Sum of all `lineSubtotal` values before tax and shipping.
`shipping`	number	Estimated shipping cost. `0.0` when free shipping applies.
`shippingKnown`	boolean	`true` if shipping cost was successfully determined. `false` if CartAI could not resolve it.
`tax`	number	Estimated tax for the order, calculated based on destination and item categories.
`total`	number	Final estimated order total: `subtotal + shipping + tax`.
`items`	array of objects	Per-item cost breakdown. See `items[]` below.

`destination` (response)

Field	Type	Description
`zip`	string	ZIP code echoed from the request.
`state`	string	State resolved from the ZIP code (e.g. `"TX"`).

`items[]` (response)

Field	Type	Description
`category`	string	Product category echoed from the request.
`unitPrice`	number	Price per unit echoed from the request.
`quantity`	integer	Quantity echoed from the request.
`lineSubtotal`	number	`unitPrice × quantity` for this line item.
`tax`	number	Tax estimated for this line item.

Example Response

{
  "status": "success",
  "message": "Estimate computed",
  "data": {
    "currency": "USD",
    "merchant": "Natori",
    "destination": {
      "zip": "75001",
      "state": "TX"
    },
    "subtotal": 72.0,
    "shipping": 0.0,
    "shippingKnown": true,
    "tax": 5.94,
    "total": 77.94,
    "items": [
      {
        "category": "clothing",
        "unitPrice": 72.0,
        "quantity": 1,
        "lineSubtotal": 72.0,
        "tax": 5.94
      }
    ]
  }
}

Notes

When shippingKnown is false, shipping will be 0.0 — treat the estimate as incomplete and avoid displaying it as the final total.
tax is estimated based on destination ZIP and item category. The actual tax charged at checkout may differ slightly depending on the merchant's tax configuration.
unitPrice in the request is used as-is for the estimate. Pass the price from /product/details to ensure accuracy.

When to Use This Endpoint

Authentication

Request Body

destination

items[]