Preview tax for a cart before checkout
Estimates the tax for a shipping destination and a set of cart lines without creating an order, so a storefront can show the shopper the final, tax-inclusive total before they pay.
When the store has automatic tax enabled, the response is calculated for the ship_to
address and includes a per-jurisdiction breakdown. A positive shipping_amount is rated as
its own shipping line, so the destination’s rules decide whether shipping is taxed.
When automatic tax is not configured, tax_source is fallback and the response carries the
tax the order endpoint charges at the store’s own rate: tax_amount, the rate, whether the
store’s prices already include tax (prices_include_tax), and whether the shipping charge was
taxed (shipping_taxed, which follows the store’s “Charge tax on shipping” setting). A store
with no rate returns a tax_amount of 0.
The estimate is never recorded for filing — it is a quote only. Publishable keys are accepted, so the call can be made directly from the browser during checkout.
Building the order total from the estimate. Send the same shipping_amount (and, for a
store whose prices include tax, the same discount_amount) that the order will carry, so the
estimate matches the order to the cent.
- Prices exclude tax (
prices_include_taxfalse, or anyautomaticresponse):total_amount = subtotal + tax_amount + shipping − discount, wheresubtotalis the sum of the line totals. - Prices include tax (
prices_include_taxtrue): the tax is already inside the line totals, sototal_amount = line totals + shipping − discountandsubtotal = line totals − tax_amount.
Pass that total_amount to createOrder; tax_amount may be omitted there, and the order
records the same figure.
curl --request POST \
--url https://api.tybritelabs.com/v1/tax/preview \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"ship_to": {
"line1": "350 Fifth Avenue",
"city": "New York",
"region": "NY",
"country": "US",
"postal_code": "10118"
},
"lines": [
{
"quantity": 2,
"amount": 598,
"item_code": "SAM-WATCH-6",
"category_name": "Wearables"
}
],
"currency": "USD"
}
'{
"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
}
]
}Authorizations
API Key Authentication
Use your API key in the Authorization header:
Authorization: Bearer tybrite_sk_live_YOUR_KEY
Key Types:
Secret Keys (Server-Side Only):
- Format:
tybrite_sk_live_*(production) ortybrite_sk_test_*(sandbox) - Full read/write access to all endpoints
- ⚠️ NEVER expose in client-side code or public repositories
- Required for: every write a shopper does not make for themselves, authentication, payment verification, AI recommendations
Publishable Keys (Client-Safe):
- Format:
tybrite_pk_live_*(production) ortybrite_pk_test_*(sandbox) - Catalogue reads, plus the actions a shopper takes for themselves
- ✅ Safe for client-side JavaScript, mobile apps, and public code
- Allowed for: browsing products, search, CMS content, pricing queries, cart and wishlist, reviews, storefront events, and the Agent API's quotes, cart drafts and checkout intents
Endpoint-Specific Requirements:
- Authentication endpoints (
/v1/auth/*): Secret key required - Payment verification (
POST /v1/payments/verify): Secret key required - AI Recommendations (
POST /v1/recommendations): Secret key required - Semantic Search (
POST /v1/search): Both key types allowed (read-only operation) - Shopper actions (cart, wishlist, reviews, storefront events, Agent API quotes, cart drafts and checkout intents): Both key types allowed
- All other write operations: Secret key required
- All read operations: Both key types allowed
Using a publishable key for restricted operations returns 403 Forbidden.
Body
The shipping destination the tax is calculated for.
Show child attributes
Show child attributes
The cart lines to estimate tax for.
Show child attributes
Show child attributes
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 a location other than the store's own address. Defaults to the store's address.
Show child attributes
Show child attributes
Your identifier for the buyer. Send it when the buyer holds a tax exemption, so the estimate reflects it. Omitted, the cart is priced as an ordinary retail sale.
"CUST-10432"
Your own reference for this estimate, echoed back so you can tie it to a cart or quote in your system.
"QUOTE-10432"
ISO 4217 currency code. Defaults to the store currency.
"USD"
The shipping charge the order will carry. With automatic tax it is rated as its own shipping line; at the store's own rate it is taxed when the store charges tax on shipping. Defaults to 0.
x >= 012.5
The discount the order will carry. Only affects the estimate for a store whose prices include tax, where the tax is taken from what the shopper pays after the discount. Defaults to 0.
x >= 00
Response
The tax estimate. tax_source is fallback when automatic tax is not configured.
53.08
598
"USD"
automatic when the tax was calculated for the destination; fallback when automatic tax is not configured and the store's own rate applies.
automatic, fallback "automatic"
The store's own tax rate as a fraction (fallback responses only).
0.1
Whether the store's prices already include tax (fallback responses only). When true, tax_amount is the tax contained in the line totals, not an amount to add.
false
Whether the shipping charge is part of the taxed amount (fallback responses only).
true
Per-jurisdiction detail (present when tax_source is automatic).
Show child attributes
Show child attributes
curl --request POST \
--url https://api.tybritelabs.com/v1/tax/preview \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"ship_to": {
"line1": "350 Fifth Avenue",
"city": "New York",
"region": "NY",
"country": "US",
"postal_code": "10118"
},
"lines": [
{
"quantity": 2,
"amount": 598,
"item_code": "SAM-WATCH-6",
"category_name": "Wearables"
}
],
"currency": "USD"
}
'{
"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
}
]
}