Preview tax calculation for a checkout session before creating the order. This endpoint is called from the hosted checkout page when the buyer enters or updates their billing details.
POST /v1/actions/checkout/preview-tax
Request Body
| Field | Type | Required | Description |
|---|
checkoutSessionId | string | Yes | Checkout session ID (cs_ + UUID format) |
billingDetail | object | Yes | Billing details for tax calculation |
Billing Detail Object
| Field | Type | Required | Description |
|---|
country | string | Yes | ISO 3166-1 alpha-2 country code |
isBusiness | boolean | Yes | Whether this is a business purchase |
state | string | Conditional | Required for US and CA |
Example Request
curl -X POST https://waffo-pancake-auth-service.vercel.app/v1/actions/checkout/preview-tax \
-H "Content-Type: application/json" \
-H "X-Store-Slug: my-store-abc123" \
-H "X-Environment: test" \
-d '{
"checkoutSessionId": "cs_550e8400-e29b-41d4-a716-446655440000",
"billingDetail": {
"country": "US",
"isBusiness": false,
"state": "CA"
}
}'
Success Response
{
"data": {
"subtotal": 2900,
"taxAmount": 261,
"total": 3161,
"taxRate": 0.09
}
}
Response Fields
| Field | Type | Description |
|---|
subtotal | integer | Product price in smallest currency unit (e.g. 2900 = $29.00) |
taxAmount | integer | Calculated tax amount in smallest currency unit |
total | integer | subtotal + taxAmount |
taxRate | number | Applied tax rate as a decimal (e.g. 0.09 = 9%) |
Errors
| Status | Message | Description |
|---|
| 400 | Missing required fields | checkoutSessionId or billingDetail is missing |
| 400 | Missing state for US/CA | state is required when country is US or CA |
| 404 | Session not found | No checkout session matches the given ID |
| 404 | Session expired | The checkout session has expired |
All amounts are in the smallest currency unit (cents for USD, yen for JPY). For example, 2900 in USD means $29.00.
