Tax

The TaxService class (accessed via client.tax) estimates the tax for a shipping destination and a cart before an order is placed, so your storefront can show and charge the final, tax-inclusive total. When a store has automatic tax enabled, the estimate is calculated for the destination and itemized per jurisdiction; otherwise the store’s own rate applies. The endpoint is publishable-key accessible, so you can call it directly from the browser during checkout. The estimate is a quote only — it is never recorded for tax filing. For the full picture (how tax flows from preview → order → returns), see the Tax guide.

Methods

`previewTax`

Estimate the tax for a cart at a shipping destination, without creating an order.

const tax = await client.tax.previewTax({
  requestBody: {
    ship_to: {
      line1: '350 Fifth Avenue',
      city: 'New York',
      region: 'NY',        // state / province / region code
      country: 'US',       // ISO 3166-1 alpha-2
      postal_code: '10118'
    },
    lines: [
      {
        quantity: 2,
        amount: 598,              // the line total (unit price × quantity)
        item_code: 'SAM-WATCH-6',
        category_name: 'Wearables' // lets the right tax code apply
      }
    ],
    currency: 'USD'
  }
});

Response

{
  "tax_amount": 53.08,
  "taxable": 598,
  "currency": "USD",
  "tax_source": "automatic",
  "breakdown": [
    { "country": "US", "region": "NY", "jurisName": "NEW YORK", "taxName": "NY STATE TAX", "rate": 0.04, "taxable": 598, "tax": 23.92 },
    { "country": "US", "region": "NY", "jurisName": "NEW YORK CITY", "taxName": "NY CITY TAX", "rate": 0.045, "taxable": 598, "tax": 26.91 },
    { "country": "US", "region": "NY", "jurisName": "METROPOLITAN COMMUTER TRANSPORTATION DISTRICT", "taxName": "NY SPECIAL TAX", "rate": 0.00375, "taxable": 598, "tax": 2.25 }
  ]
}

Parameters (requestBody)

Field	Required	Description
`ship_to`	yes	The destination. `country` is required; include `region`, `city`, and `postal_code` for accuracy.
`lines`	yes	The cart lines. Each needs `amount` (the line total); include `quantity`, `item_code`, and `category_name` where you have them.
`currency`	no	ISO 4217 code; defaults to the store currency.
`shipping_amount`	no	The delivery charge. Rated as its own line by automatic tax (the destination decides whether shipping is taxable); at the store’s own rate it is taxed when the store charges tax on shipping. A number of 0 or more.
`discount_amount`	no	The order’s discount. Used by the store’s own rate when prices include tax, where the tax is taken from what the shopper pays. A number of 0 or more.
`ship_from`	no	The origin the goods ship from. Which jurisdictions may tax a sale depends on where it ships from as well as where it ships to, so send this when fulfilling from somewhere other than the store’s own address. Defaults to the store’s address.
`customer_code`	no	Your identifier for the buyer. Send it when the buyer holds a tax exemption, so the estimate reflects it; otherwise the cart is priced as an ordinary retail sale.
`doc_code`	no	Your own reference for this estimate, echoed back so you can tie it to a cart or quote in your system.

Response

Field	Description
`tax_amount`	Total tax for the cart at this destination.
`taxable`	The taxable base.
`tax_source`	`automatic` (calculated for the destination) or `fallback` (automatic tax isn’t configured; the figures are the store’s own rate).
`rate`	With `fallback`: the store’s rate, as a fraction (`0.08` = 8%).
`prices_include_tax`	With `fallback`: whether the store’s prices already include tax.
`shipping_taxed`	With `fallback`: whether the delivery charge was part of the taxable base.
`breakdown`	Per-jurisdiction detail (state, county, city, special district…), each with its `rate` and `tax`. Present when `tax_source` is `automatic`.

A line without category_name is taxed as standard tangible goods. Categories such as food, clothing, books, and digital goods are taxed differently from general merchandise, so the field changes the result wherever a jurisdiction treats them separately.

Using the estimate at checkout

Compute the order total from the estimate, then submit that same tax-inclusive total to createOrder — the order endpoint recalculates the tax server-side and confirms the total matches.

const subtotal = 598, shipping = 5.99, discount = 0;
const total_amount = subtotal + (tax.tax_amount ?? 0) + shipping - discount;
// pass total_amount to client.orders.createOrder — omit tax_amount so the server records it

Send the same shipping_amount and discount_amount to previewTax that the order will carry, so the estimate covers the delivery charge. When tax_source is fallback, tax_amount is the store’s own rate, computed by the same rules the order endpoint applies, so the figures agree. When prices_include_tax is true the tax is already inside the prices: the total is subtotal + shipping − discount, and tax_amount is the part of it that is tax.

Get Started

Core Commerce

Discovery

Checkout & Logistics

Agents

Marketplace

B2B (Wholesale)

Account & Support

System & Store

Integrations

Methods

`previewTax`

Using the estimate at checkout

​Methods

​previewTax

​Using the estimate at checkout

Methods

`previewTax`

Using the estimate at checkout