Docs / API Reference / v1

API v1Current

Sales Tax Calculator API

Create an immutable sales tax calculation from seller, customer, item-classification, location, currency, and billing facts. Each response gives your application a stable outcome and the amounts it may use.

Base URLhttps://api.salestaxcalculatorapi.com

Call the API from trusted server code. Never put a secret API key in browser or mobile code.

POST/v1/calculations

Create one immutable sales tax calculation.

Create API key

Quickstart

Send JSON with a bearer key and an idempotency key tied to the business operation. The examples set connection and response timeouts and stop when the API returns a non-determinate outcome.

RequestPOST/v1/calculations

curl \
  --request POST \
  --url "https://api.salestaxcalculatorapi.com/v1/calculations" \
  --connect-timeout 5 \
  --max-time 15 \
  --header "Authorization: Bearer $STCA_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: checkout-order-1001" \
  --data '{
30 collapsed lines
    "reference": "order-1001",
    "transaction_date": "2026-08-29",
    "currency": "CAD",
    "tax_behavior": "exclusive",
    "billing_event": "subscription_start",
    "seller": {
      "country": "CA",
      "channel_role": "direct_legal_supplier",
      "registrations": [
        {
          "country": "CA",
          "state": "ON",
          "type": "gst_hst",
          "effective_from": "2026-01-01"
        }
      ]
    },
    "customer": {
      "type": "consumer",
      "address": {
        "country": "CA",
        "state": "ON",
        "postal_code": "M5V 2T6"
      }
    },
    "lines": [
      {
        "reference": "subscription",
        "amount": "100.00",
        "quantity": "1",
        "tax_code": "saas"
      }
    ]
  }'

201 Created

{
  "id": "calc_01J6A3S8Z6K4M6T2Y2W9M5X8Q0",
  "object": "calculation",
  "reference": "order-1001",
  "outcome": "calculated",
  "currency": "CAD",
  "subtotal": "100.00",
  "taxable_amount": "100.00",
  "tax": "13.00",
  "total": "113.00",
  "lines": [
13 collapsed lines
    {
      "id": "line_01J6A3T26X8BS4Y8XJKZ0H8F3P",
      "reference": "subscription",
      "outcome": "calculated",
      "subtotal": "100.00",
      "taxable_amount": "100.00",
      "tax": "13.00",
      "total": "113.00",
      "explanation": "Tax was calculated for this sale."
    }
  ],
  "explanation": "Tax was calculated for this sale.",
  "request_id": "req_01J6A3RZ1HT2K3W2X8R7P1J4C9",
  "created_at": "2026-08-29T12:00:00Z"
}

Example sales tax calculation

This example is a CAD 100.00 tax-exclusive SaaS subscription sold directly to a consumer in Ontario by a seller with an effective Ontario GST/HST registration. The response applies 13% HST: CAD 100.00 subtotal + CAD 13.00 tax = CAD 113.00 total.

The example rate matches the Canada Revenue Agency GST/HST rate table. It demonstrates the request and response shape. Another transaction can return a different amount or outcome.

Sales tax calculation request fields

Unknown fields and JSON numbers for money are rejected. Use uppercase country, subdivision, and currency codes. Use lowercase API enum and tax-code values.

Field	Use	Meaning
`reference`	Recommended	Your order, invoice, or cart reference. Returned with the sales tax calculation.
`transaction_date`	Recommended	Commercial date in YYYY-MM-DD form. It defaults to the current UTC date, so send it explicitly when results must be reproducible.
`currency`	Required	Three-letter uppercase ISO 4217 code. All money values are decimal strings in this currency.
`tax_behavior`	Required	Use exclusive when line amounts exclude tax. Use inclusive when line amounts already include tax.
`billing_event`	Required	The commercial event, such as one_time_charge, subscription_start, subscription_renewal, or metered_usage.
`seller`	Required	Seller country, channel role, and effective-dated tax registrations that apply to this sale.
`customer`	Required	Customer type and location. Add tax IDs or independent location evidence only when they apply.
`ship_from / ship_to`	Conditional	Supply-chain locations when shipping facts affect the transaction.
`lines`	Required	Between 1 and 100 lines. Each line needs a unique reference, total line amount, and tax code. Quantity defaults to 1.

Line amount and quantity: amount is the total monetary amount for the line, not a unit price. quantity records how many units that total represents and supports proportional quantity adjustments later.

Sales tax calculation response fields

A created sales tax calculation returns HTTP 201 even when its tax outcome is review_required or unsupported. Check outcome before using tax or total.

Field	How to use it
`outcome`	The decision for the complete sales tax calculation. Branch on this before using any amount.
`subtotal`	Tax-exclusive amount represented by the response.
`taxable_amount`	Amount to which tax was applied.
`tax`	Calculated tax amount. This is 0.00 for non-determinate and valid zero-tax outcomes.
`total`	Subtotal plus tax for exclusive pricing, or the submitted gross amount for inclusive pricing.
`lines`	Per-line outcome and final amounts. Keep these with the order for later adjustments.
`explanation`	Customer-readable reason for the returned outcome.
`id / request_id`	Stable identifiers for retrieval, logs, and support.
`created_at`	UTC timestamp at which the immutable sales tax calculation was created.

For tax-exclusive pricing, the submitted line amount is the subtotal and tax is added. For tax-inclusive pricing, the submitted line amount is the total and the response separates its subtotal and tax. Use the returned decimal strings instead of recalculating from a displayed rate.

Sales tax calculation outcomes

HTTP 201

The HTTP status says the resource was created. The outcome says whether the returned amounts are a final tax decision.

Outcome	Meaning	Application action
`calculated`	Tax was calculated from the supplied seller and transaction facts.	Use the returned tax and total.
`not_taxable`	The supplied item is not taxable for this transaction.	Use the returned zero-tax result.
`not_obligated`	The seller is not the party required to collect tax.	Use the returned zero-tax result.
`reverse_charge_or_self_assess`	The customer is responsible for the tax treatment.	Use the returned result and preserve the explanation.
`exempt`	Accepted evidence supports an exemption.	Use the returned zero-tax result.
`no_general_tax`	The jurisdiction has no general transaction tax for this sale.	Use the returned zero-tax result.
`review_required`	The supplied facts cannot support a final answer.	Stop automatic tax handling and review the transaction.
`unsupported`	This exact combination is not currently supported.	Do not infer a rate or treat 0.00 as a tax decision.

Production handling

Keep credentials server-side. Send the bearer key only from infrastructure you control.
Make the request reproducible. Send the commercial transaction date, a stable reference, effective seller registrations, and the location and item-classification facts available at checkout.
Tie idempotency to the operation. Reuse the same key and body when retrying the same order. Create a new key for a new operation.
Branch on the top-level outcome. Treat review_required and unsupported as non-determinate even when individual lines contain amounts.
Store the response. Keep the sales tax calculation ID, request ID, line IDs, outcome, amounts, and explanation with the order.
Use returned amounts. Use the returned decimal strings to charge, display, finalize, and adjust amounts. Do not rebuild tax from rounded display values.
Retry deliberately. Retry only retryable failures, honor the supplied delay, and preserve the original idempotency key and request body.

Errors and retries

Errors use RFC 9457 application/problem+json. Branch on the stable lowercase code, retain request_id, and inspect retryable. Field errors include a JSON Pointer.

HTTP	Typical code	Client action
400	`invalid_request / unknown_field / invalid_idempotency_key`	Correct the listed request fields or header.
401	`invalid_api_key`	Use an active account API key.
403	`forbidden`	Check the account entitlement and API-key permissions.
404	`resource_not_found`	Check the resource ID and account access.
409	`idempotency_conflict / request_in_progress`	Reuse the original request or retry after the indicated delay.
413	`request_too_large`	Reduce the request or batch size.
422	`unsupported_currency / calculation_not_finalizable`	Change the unsupported value or resolve the resource state.
429	`rate_limit_exceeded`	Wait for Retry-After, then retry. This response does not consume an API call.
429	`usage_cap_reached`	Review or change the account usage limit before retrying.
503	`tax_data_ambiguous`	Retry only when retryable is true.

When a retry is allowed, wait for Retry-After or retry_after_seconds when present and resend the identical body with the same idempotency key. A different body with that key returns 409 idempotency_conflict.

Authentication

Send an stca_ API key, shown only once when created, as a bearer token. Your API key continues to work when you move from evaluation to a paid plan.

Authorization: Bearer stca_••••••••

Send every request to the base URL shown above. You do not need tenant, mode, or environment headers.

Idempotency

Every create request needs an Idempotency-Key containing 8 to 255 safe ASCII characters and matching [A-Za-z0-9][A-Za-z0-9_.:-]{7,254}.

Repeating the same canonical request with the same key returns the original resource and Idempotent-Replayed: true. JSON whitespace or property order does not create a conflict.

Sales tax calculation audit details

Add ?expand=audit when your application needs the dated coverage basis, effective period, jurisdiction components, rates, taxable amounts, tax amounts, and evidence status returned for the sales tax calculation.

POST /v1/calculations?expand=audit

The expansion contains customer-facing sales tax calculation evidence. Store it with the result when your invoice, support, or reconciliation workflow needs those details.

API endpoints

All customer resources are scoped to the account authenticated by the bearer key.

POST/v1/calculationsCreate a sales tax calculation

Creates one immutable sales tax calculation from seller, customer, product, and billing facts supplied in the request. Determinate tax is returned only for a qualified combination.

Headers and URL parameters

Name	Location	Requirement	Type	Details
`Authorization`	header	Required	`string`	Bearer API key in the form Bearer stca_••••••••.
`Content-Type`	header	Required	`string`	Send application/json.
`Idempotency-Key`	header	Required	`string`	A caller-generated key. Reusing it with the same canonical request returns the original effect. Reusing it with different content returns a conflict.
`expand`	query	Optional	`string`	Set to audit for an authorized customer-safe audit expansion.

JSON body parameters

Required and optional status is evaluated within each containing object. Unknown JSON fields are rejected.

Top-level JSON fields

JSON field	Type	Requirement	Details
`reference`	`string`	Optional	Your stable business reference for this resource. 1–200 characters.
`transaction_date`	`string (date)`	Optional	The commercial transaction date in YYYY-MM-DD form. It defaults to the current UTC date when omitted. Send it explicitly for reproducible sales tax calculations.
`currency`	`string`	Required	ISO 4217 currency code.
`tax_behavior`	`string (enum)`	Required	Allowed values: exclusive, inclusive.
`billing_event`	`string (enum)`	Required	Allowed values: one_time_charge, subscription_start, subscription_renewal, metered_usage, free_trial, paid_trial, discount, proration, supported_bundle.
`seller`	`object`	Required	See the seller fields below.
`customer`	`object`	Required	See the customer fields below.
`ship_from`	`object`	Optional	See the ship_from fields below.
`ship_to`	`object`	Optional	See the ship_to fields below.
`lines`	`object[]`	Required	1–100 items. See the lines[] fields below.

seller object

JSON field	Type	Requirement	Details
`seller.country`	`string`	Required	Two-letter uppercase ISO 3166-1 country code.
`seller.channel_role`	`string (enum)`	Required	Allowed values: direct_legal_supplier, marketplace_operator, marketplace_seller, merchant_of_record, disclosed_agent, reseller_principal.
`seller.registrations`	`object[]`	Required	Up to 100 items. See the seller.registrations[] fields below.

seller.registrations[] object

JSON field	Type	Requirement	Details
`seller.registrations[].country`	`string`	Required	Two-letter uppercase ISO 3166-1 country code.
`seller.registrations[].state`	`string`	Optional	Uppercase subdivision code, such as a state or province. 1–16 characters.
`seller.registrations[].type`	`string`	Required	1–64 characters.
`seller.registrations[].effective_from`	`string (date)`	Required	Defined by the public OpenAPI schema.
`seller.registrations[].effective_to`	`string (date)`	Optional	Defined by the public OpenAPI schema.

customer object

JSON field	Type	Requirement	Details
`customer.type`	`string (enum)`	Optional	Allowed values: consumer, business, government, nonprofit.
`customer.address`	`object`	Required	See the customer.address fields below.
`customer.tax_ids`	`object[]`	Optional	Up to 10 items. See the customer.tax_ids[] fields below.
`customer.location_evidence`	`object[]`	Optional	Up to 5 items. See the customer.location_evidence[] fields below.

customer.address object

JSON field	Type	Requirement	Details
`customer.address.line1`	`string`	Optional	1–200 characters.
`customer.address.line2`	`string`	Optional	1–200 characters.
`customer.address.city`	`string`	Optional	1–120 characters.
`customer.address.state`	`string`	Optional	Uppercase subdivision code, such as a state or province. 1–16 characters.
`customer.address.postal_code`	`string`	Optional	1–32 characters.
`customer.address.country`	`string`	Required	Two-letter uppercase ISO 3166-1 country code.

customer.tax_ids[] object

JSON field	Type	Requirement	Details
`customer.tax_ids[].type`	`string (enum)`	Required	Allowed values: eu_vat, gb_vat, gst, business_tax_id, other.
`customer.tax_ids[].country`	`string`	Required	Two-letter uppercase ISO 3166-1 country code.
`customer.tax_ids[].value`	`string`	Required	2–64 characters.

customer.location_evidence[] object

JSON field	Type	Requirement	Details
`customer.location_evidence[].kind`	`string (enum)`	Required	Allowed values: billing_address, ip_address, payment_method, self_declaration.
`customer.location_evidence[].country`	`string`	Required	Two-letter uppercase ISO 3166-1 country code.
`customer.location_evidence[].state`	`string`	Optional	Uppercase subdivision code, such as a state or province. 1–16 characters.

ship_from object

JSON field	Type	Requirement	Details
`ship_from.line1`	`string`	Optional	1–200 characters.
`ship_from.line2`	`string`	Optional	1–200 characters.
`ship_from.city`	`string`	Optional	1–120 characters.
`ship_from.state`	`string`	Optional	Uppercase subdivision code, such as a state or province. 1–16 characters.
`ship_from.postal_code`	`string`	Optional	1–32 characters.
`ship_from.country`	`string`	Required	Two-letter uppercase ISO 3166-1 country code.

ship_to object

JSON field	Type	Requirement	Details
`ship_to.line1`	`string`	Optional	1–200 characters.
`ship_to.line2`	`string`	Optional	1–200 characters.
`ship_to.city`	`string`	Optional	1–120 characters.
`ship_to.state`	`string`	Optional	Uppercase subdivision code, such as a state or province. 1–16 characters.
`ship_to.postal_code`	`string`	Optional	1–32 characters.
`ship_to.country`	`string`	Required	Two-letter uppercase ISO 3166-1 country code.

lines[] object

One separately classified line. Amount is the total line amount, not a per-unit price. Quantity is retained for proportional adjustments.

JSON field	Type	Requirement	Details
`lines[].reference`	`string`	Required	Your stable business reference for this resource. 1–200 characters.
`lines[].amount`	`string`	Required	Non-negative decimal amount in the currency's ordinary unit. Currency-specific scale is enforced.
`lines[].quantity`	`string`	Optional	Positive decimal quantity. Defaults to 1 when omitted.
`lines[].tax_code`	`string`	Required	Lowercase tax code used to classify the line item. 2–64 characters.
`lines[].tax_behavior`	`string (enum)`	Optional	Allowed values: exclusive, inclusive.

Success response

201 Created. The outcome, line results, subtotal, tax, total, explanation, and request ID.

GET/v1/calculations/{calculation_id}Retrieve a sales tax calculation

Retrieves one sales tax calculation owned by the authenticated workspace.

Headers and URL parameters

Name	Location	Requirement	Type	Details
`Authorization`	header	Required	`string`	Bearer API key in the form Bearer stca_••••••••.
`calculation_id`	path	Required	`string`	Sales tax calculation ID returned by the API.
`expand`	query	Optional	`string`	Set to audit for an authorized customer-safe audit expansion.

JSON request body

None. This endpoint does not accept a JSON request body.

Success response

200 OK. The stored sales tax calculation, including its outcome, amounts, line results, explanation, and request ID.

POST/v1/transactionsCreate a transaction

Finalizes a completed sales tax calculation as an immutable commercial transaction and stores its exact line and tax-component snapshot.

Headers and URL parameters

Name	Location	Requirement	Type	Details
`Authorization`	header	Required	`string`	Bearer API key in the form Bearer stca_••••••••.
`Content-Type`	header	Required	`string`	Send application/json.
`Idempotency-Key`	header	Required	`string`	A caller-generated key. Reusing it with the same canonical request returns the original effect. Reusing it with different content returns a conflict.
`expand`	query	Optional	`string`	Set to audit for an authorized customer-safe audit expansion.

JSON body parameters

Required and optional status is evaluated within each containing object. Unknown JSON fields are rejected.

Top-level JSON fields

JSON field	Type	Requirement	Details
`calculation_id`	`string`	Required	Sales tax calculation ID returned by the API.
`reference`	`string`	Required	Your stable business reference for this resource. 1–200 characters.
`occurred_at`	`string (date-time)`	Optional	Defined by the public OpenAPI schema.

Success response

201 Created. The transaction ID, linked sales tax calculation ID, currency, totals, adjusted amounts, and request ID.

GET/v1/transactions/{transaction_id}Retrieve a transaction

Retrieves one finalized transaction owned by the authenticated workspace.

Headers and URL parameters

Name	Location	Requirement	Type	Details
`Authorization`	header	Required	`string`	Bearer API key in the form Bearer stca_••••••••.
`transaction_id`	path	Required	`string`	Transaction ID returned by the API.
`expand`	query	Optional	`string`	Set to audit for an authorized customer-safe audit expansion.

JSON request body

None. This endpoint does not accept a JSON request body.

Success response

200 OK. The immutable transaction, linked sales tax calculation ID, original amounts, adjusted amounts, and request ID.

POST/v1/transactions/{transaction_id}/adjustmentsCreate an adjustment

Creates an immutable adjustment by reversing exact stored original line components. Cumulative adjustments cannot exceed the reversible original.

Headers and URL parameters

Name	Location	Requirement	Type	Details
`Authorization`	header	Required	`string`	Bearer API key in the form Bearer stca_••••••••.
`Content-Type`	header	Required	`string`	Send application/json.
`transaction_id`	path	Required	`string`	Transaction ID returned by the API.
`Idempotency-Key`	header	Required	`string`	A caller-generated key. Reusing it with the same canonical request returns the original effect. Reusing it with different content returns a conflict.
`expand`	query	Optional	`string`	Set to audit for an authorized customer-safe audit expansion.

JSON body parameters

Required and optional status is evaluated within each containing object. Unknown JSON fields are rejected.

Top-level JSON fields

JSON field	Type	Requirement	Details
`reference`	`string`	Required	Your stable business reference for this resource. 1–200 characters.
`reason`	`string (enum)`	Required	Allowed values: refund, credit, correction.
`lines`	`object (one of)[]`	Required	1–100 items. See the lines[] fields below.

lines[] — adjustment amount line

JSON field	Type	Requirement	Details
`lines[].line_id`	`string`	Required	Sales tax calculation line ID returned by the API.
`lines[].amount`	`string`	Required	Non-negative decimal amount in the currency's ordinary unit. Currency-specific scale is enforced.

lines[] — adjustment quantity line

Success response

201 Created. The adjustment ID, reason, currency, subtotal, tax, total, reversed line components, and request ID.

GET/v1/transactions/{transaction_id}/adjustmentsList transaction adjustments

Lists adjustments for one transaction, newest first, using an opaque cursor.

Headers and URL parameters

Name	Location	Requirement	Type	Details
`Authorization`	header	Required	`string`	Bearer API key in the form Bearer stca_••••••••.
`transaction_id`	path	Required	`string`	Transaction ID returned by the API.
`limit`	query	Optional	`integer`	Default: 20. Accepted range: 1–100.
`starting_after`	query	Optional	`string`	Opaque cursor from the previous page.
`expand`	query	Optional	`string`	Set to audit for an authorized customer-safe audit expansion.

JSON request body

None. This endpoint does not accept a JSON request body.

Success response

200 OK. The adjustment items, has_more flag, and next_cursor when another page is available.

GET/v1/transactions/{transaction_id}/adjustments/{adjustment_id}Retrieve an adjustment

Retrieves one adjustment belonging to the specified transaction.

Headers and URL parameters

Name	Location	Requirement	Type	Details
`Authorization`	header	Required	`string`	Bearer API key in the form Bearer stca_••••••••.
`transaction_id`	path	Required	`string`	Transaction ID returned by the API.
`adjustment_id`	path	Required	`string`	Adjustment ID returned by the API.
`expand`	query	Optional	`string`	Set to audit for an authorized customer-safe audit expansion.

JSON request body

None. This endpoint does not accept a JSON request body.

Success response

200 OK. The adjustment, reversed line components, amounts, reason, and request ID.

POST/v1/calculation-batchesCreate a sales tax calculation batch

Durably accepts between 1 and 100 independent sales tax calculations for asynchronous processing.

Headers and URL parameters

Name	Location	Requirement	Type	Details
`Authorization`	header	Required	`string`	Bearer API key in the form Bearer stca_••••••••.
`Content-Type`	header	Required	`string`	Send application/json.
`Idempotency-Key`	header	Required	`string`	A caller-generated key. Reusing it with the same canonical request returns the original effect. Reusing it with different content returns a conflict.

JSON body parameters

Required and optional status is evaluated within each containing object. Unknown JSON fields are rejected.

Top-level JSON fields

JSON field	Type	Requirement	Details
`reference`	`string`	Optional	Your stable business reference for this resource. 1–200 characters.
`calculations`	`object[]`	Required	1–100 items. See the calculations[] fields below.

calculations[] object

JSON field	Type	Requirement	Details
`calculations[].reference`	`string`	Optional	Your stable business reference for this resource. 1–200 characters.
`calculations[].transaction_date`	`string (date)`	Optional	The commercial transaction date in YYYY-MM-DD form. It defaults to the current UTC date when omitted. Send it explicitly for reproducible sales tax calculations.
`calculations[].currency`	`string`	Required	ISO 4217 currency code.
`calculations[].tax_behavior`	`string (enum)`	Required	Allowed values: exclusive, inclusive.
`calculations[].billing_event`	`string (enum)`	Required	Allowed values: one_time_charge, subscription_start, subscription_renewal, metered_usage, free_trial, paid_trial, discount, proration, supported_bundle.
`calculations[].seller`	`object`	Required	See the calculations[].seller fields below.
`calculations[].customer`	`object`	Required	See the calculations[].customer fields below.
`calculations[].ship_from`	`object`	Optional	See the calculations[].ship_from fields below.
`calculations[].ship_to`	`object`	Optional	See the calculations[].ship_to fields below.
`calculations[].lines`	`object[]`	Required	1–100 items. See the calculations[].lines[] fields below.

calculations[].seller object

JSON field	Type	Requirement	Details
`calculations[].seller.country`	`string`	Required	Two-letter uppercase ISO 3166-1 country code.
`calculations[].seller.channel_role`	`string (enum)`	Required	Allowed values: direct_legal_supplier, marketplace_operator, marketplace_seller, merchant_of_record, disclosed_agent, reseller_principal.
`calculations[].seller.registrations`	`object[]`	Required	Up to 100 items. See the calculations[].seller.registrations[] fields below.

calculations[].seller.registrations[] object

JSON field	Type	Requirement	Details
`calculations[].seller.registrations[].country`	`string`	Required	Two-letter uppercase ISO 3166-1 country code.
`calculations[].seller.registrations[].state`	`string`	Optional	Uppercase subdivision code, such as a state or province. 1–16 characters.
`calculations[].seller.registrations[].type`	`string`	Required	1–64 characters.
`calculations[].seller.registrations[].effective_from`	`string (date)`	Required	Defined by the public OpenAPI schema.
`calculations[].seller.registrations[].effective_to`	`string (date)`	Optional	Defined by the public OpenAPI schema.

calculations[].customer object

JSON field	Type	Requirement	Details
`calculations[].customer.type`	`string (enum)`	Optional	Allowed values: consumer, business, government, nonprofit.
`calculations[].customer.address`	`object`	Required	See the calculations[].customer.address fields below.
`calculations[].customer.tax_ids`	`object[]`	Optional	Up to 10 items. See the calculations[].customer.tax_ids[] fields below.
`calculations[].customer.location_evidence`	`object[]`	Optional	Up to 5 items. See the calculations[].customer.location_evidence[] fields below.

calculations[].customer.address object

JSON field	Type	Requirement	Details
`calculations[].customer.address.line1`	`string`	Optional	1–200 characters.
`calculations[].customer.address.line2`	`string`	Optional	1–200 characters.
`calculations[].customer.address.city`	`string`	Optional	1–120 characters.
`calculations[].customer.address.state`	`string`	Optional	Uppercase subdivision code, such as a state or province. 1–16 characters.
`calculations[].customer.address.postal_code`	`string`	Optional	1–32 characters.
`calculations[].customer.address.country`	`string`	Required	Two-letter uppercase ISO 3166-1 country code.

calculations[].customer.tax_ids[] object

JSON field	Type	Requirement	Details
`calculations[].customer.tax_ids[].type`	`string (enum)`	Required	Allowed values: eu_vat, gb_vat, gst, business_tax_id, other.
`calculations[].customer.tax_ids[].country`	`string`	Required	Two-letter uppercase ISO 3166-1 country code.
`calculations[].customer.tax_ids[].value`	`string`	Required	2–64 characters.

calculations[].customer.location_evidence[] object

JSON field	Type	Requirement	Details
`calculations[].customer.location_evidence[].kind`	`string (enum)`	Required	Allowed values: billing_address, ip_address, payment_method, self_declaration.
`calculations[].customer.location_evidence[].country`	`string`	Required	Two-letter uppercase ISO 3166-1 country code.
`calculations[].customer.location_evidence[].state`	`string`	Optional	Uppercase subdivision code, such as a state or province. 1–16 characters.

calculations[].ship_from object

JSON field	Type	Requirement	Details
`calculations[].ship_from.line1`	`string`	Optional	1–200 characters.
`calculations[].ship_from.line2`	`string`	Optional	1–200 characters.
`calculations[].ship_from.city`	`string`	Optional	1–120 characters.
`calculations[].ship_from.state`	`string`	Optional	Uppercase subdivision code, such as a state or province. 1–16 characters.
`calculations[].ship_from.postal_code`	`string`	Optional	1–32 characters.
`calculations[].ship_from.country`	`string`	Required	Two-letter uppercase ISO 3166-1 country code.

calculations[].ship_to object

JSON field	Type	Requirement	Details
`calculations[].ship_to.line1`	`string`	Optional	1–200 characters.
`calculations[].ship_to.line2`	`string`	Optional	1–200 characters.
`calculations[].ship_to.city`	`string`	Optional	1–120 characters.
`calculations[].ship_to.state`	`string`	Optional	Uppercase subdivision code, such as a state or province. 1–16 characters.
`calculations[].ship_to.postal_code`	`string`	Optional	1–32 characters.
`calculations[].ship_to.country`	`string`	Required	Two-letter uppercase ISO 3166-1 country code.

calculations[].lines[] object

One separately classified line. Amount is the total line amount, not a per-unit price. Quantity is retained for proportional adjustments.

JSON field	Type	Requirement	Details
`calculations[].lines[].reference`	`string`	Required	Your stable business reference for this resource. 1–200 characters.
`calculations[].lines[].amount`	`string`	Required	Non-negative decimal amount in the currency's ordinary unit. Currency-specific scale is enforced.
`calculations[].lines[].quantity`	`string`	Optional	Positive decimal quantity. Defaults to 1 when omitted.
`calculations[].lines[].tax_code`	`string`	Required	Lowercase tax code used to classify the line item. 2–64 characters.
`calculations[].lines[].tax_behavior`	`string (enum)`	Optional	Allowed values: exclusive, inclusive.

Success response

202 Accepted. The durable batch ID, processing status, item counts, and request ID.

GET/v1/calculation-batches/{batch_id}Retrieve a sales tax calculation batch

Returns durable batch status and per-item results when available.

Headers and URL parameters

Name	Location	Requirement	Type	Details
`Authorization`	header	Required	`string`	Bearer API key in the form Bearer stca_••••••••.
`batch_id`	path	Required	`string`	Batch ID returned by the API.
`expand`	query	Optional	`string`	Set to audit for an authorized customer-safe audit expansion.

JSON request body

None. This endpoint does not accept a JSON request body.

Success response

200 OK. The processing status, item counts, per-item results, and completion time when finished.

GET/v1/coverageCheck qualified coverage

Checks the dated qualification state for one jurisdiction, product, transaction type, customer type, and date. A country list alone is not a coverage guarantee.

Headers and URL parameters

Name	Location	Requirement	Type	Details
`Authorization`	header	Required	`string`	Bearer API key in the form Bearer stca_••••••••.
`country`	query	Required	`string`	ISO 3166-1 alpha-2 country code.
`state`	query	Optional	`string`	Subdivision code when applicable.
`tax_code`	query	Required	`string`	Lowercase tax code used to classify the line item. 2–64 characters.
`transaction_type`	query	Required	`string (enum)`	Allowed values: sale, refund, credit.
`customer_type`	query	Optional	`string (enum)`	Allowed values: consumer, business, government, nonprofit.
`date`	query	Optional	`string (date)`	ISO date to evaluate. Defaults to the server's current UTC date.

JSON request body

None. This endpoint does not accept a JSON request body.

Success response

200 OK. The qualification status, source basis, effective dates, evidence requirements, and request ID.

Coverage

Use GET /v1/coverage to check a specific country, region, tax code, transaction type, customer type, and date without creating a sales tax calculation. A sales tax calculation request does not require a preceding coverage request and always returns its own outcome.

Service scope

The API calculates and records supported indirect-tax results. It does not file returns, remit tax, register businesses, or provide legal advice. Unsupported or incomplete combinations fail closed without inventing a tax amount.

OpenAPI specification

The OpenAPI 3.1.2 document defines request schemas, responses, errors, examples, and compatibility behavior for the public API.

Download OpenAPI JSON View contract