Calculations · POST

Create a sales tax calculation

Creates and saves a sales tax calculation from seller, customer, item, and transaction details. Check the outcome to see whether the result is final, needs review, or is unsupported.

POST/v1/calculations

Parameters

Send these headers and path or query values with the request.

Name	Type	Required	Description
`Authorization`	`string`	Yes	Send your API key as a bearer token.
`Content-Type`	`string`	Yes	Use application/json.
`Idempotency-Key`	`string`	Yes	A caller-generated key. Reusing it with the same canonical request returns the original effect. Reusing it with different content returns a conflict.
`expand`	`string`	No	Set to audit for an authorized customer-safe audit expansion.

Request body

Required JSON body.

Name	Type	Required	Description
`reference`	`string`	No	See the request example for the full field shape.
`transaction_date`	`string`	No	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`	Yes	ISO 4217 currency code.
`tax_behavior`	`string`	Yes	Values: exclusive, inclusive.
`billing_event`	`string`	Yes	Values: one_time_charge, subscription_start, subscription_renewal, metered_usage, free_trial, paid_trial, discount, proration, supported_bundle.
`seller`	`object`	Yes	Object with the fields listed below.
`customer`	`object`	Yes	Object with the fields listed below.
`ship_from`	`object`	No	Object with the fields listed below.
`ship_to`	`object`	No	Object with the fields listed below.
`lines`	`array<object>`	Yes	Array of objects with the fields listed below.

seller8 fields

Name	Type	Required	Description
`country`	`string`	Yes	See the request example for the full field shape.
`channel_role`	`string`	Yes	Values: direct_legal_supplier, marketplace_operator, marketplace_seller, merchant_of_record, disclosed_agent, reseller_principal.
`registrations`	`array`	Yes	See the request example for the full field shape.
`registrations[].country`	`string`	Yes	See the request example for the full field shape.
`registrations[].state`	`string`	No	See the request example for the full field shape.
`registrations[].type`	`string`	Yes	See the request example for the full field shape.
`registrations[].effective_from`	`string`	Yes	See the request example for the full field shape.
`registrations[].effective_to`	`string`	No	See the request example for the full field shape.

customer16 fields

Name	Type	Required	Description
`type`	`string`	No	Values: consumer, business, government, nonprofit.
`address`	`object`	Yes	Object with the fields listed below.
`address.line1`	`string`	No	See the request example for the full field shape.
`address.line2`	`string`	No	See the request example for the full field shape.
`address.city`	`string`	No	See the request example for the full field shape.
`address.state`	`string`	No	See the request example for the full field shape.
`address.postal_code`	`string`	No	See the request example for the full field shape.
`address.country`	`string`	Yes	See the request example for the full field shape.
`tax_ids`	`array`	No	See the request example for the full field shape.
`tax_ids[].type`	`string`	Yes	Values: eu_vat, gb_vat, gst, business_tax_id, other.
`tax_ids[].country`	`string`	Yes	See the request example for the full field shape.
`tax_ids[].value`	`string`	Yes	See the request example for the full field shape.
`location_evidence`	`array`	No	See the request example for the full field shape.
`location_evidence[].kind`	`string`	Yes	Values: billing_address, ip_address, payment_method, self_declaration.
`location_evidence[].country`	`string`	Yes	See the request example for the full field shape.
`location_evidence[].state`	`string`	No	See the request example for the full field shape.

ship_from6 fields

Name	Type	Required	Description
`line1`	`string`	No	See the request example for the full field shape.
`line2`	`string`	No	See the request example for the full field shape.
`city`	`string`	No	See the request example for the full field shape.
`state`	`string`	No	See the request example for the full field shape.
`postal_code`	`string`	No	See the request example for the full field shape.
`country`	`string`	Yes	See the request example for the full field shape.

ship_to6 fields

Name	Type	Required	Description
`line1`	`string`	No	See the request example for the full field shape.
`line2`	`string`	No	See the request example for the full field shape.
`city`	`string`	No	See the request example for the full field shape.
`state`	`string`	No	See the request example for the full field shape.
`postal_code`	`string`	No	See the request example for the full field shape.
`country`	`string`	Yes	See the request example for the full field shape.

lines[]5 fields

Name	Type	Required	Description
`reference`	`string`	Yes	See the request example for the full field shape.
`amount`	`string`	Yes	Non-negative decimal amount in the currency's ordinary unit. Currency-specific scale is enforced.
`quantity`	`string`	No	Positive decimal quantity. Defaults to 1 when omitted.
`tax_code`	`string`	Yes	See the request example for the full field shape.
`tax_behavior`	`string`	No	Values: exclusive, inclusive.

Responses

201

The sales tax calculation was saved.

Headers: Request-Id, Idempotent-Replayed, RateLimit-Limit, RateLimit-Remaining

400

The request shape, parameter, or header is invalid.

401

A valid API key is required.

Headers: WWW-Authenticate

403

The authenticated key cannot perform this operation.

409

The request conflicts with an existing idempotency key or the current state of a saved record.

422

The request is valid, but the API cannot complete it. For example, the facts may not qualify or an adjustment may exceed the amounts left to reverse.

429

The request exceeded an API safety limit. It did not count toward API usage.

Headers: Retry-After

503

A required service is unavailable, so the API could not process the request.

Headers: Retry-After

Live request

Try this endpoint

api.salestaxcalculatorapi.com

The browser sends the request straight to the API. Your API key never passes through this website's server.

API keyexpand

Idempotency key

Request body · JSON

POST requests can create records and use your API quota. Check the request body before sending.

Request

Shell

curl --request POST \
  --url "https://api.salestaxcalculatorapi.com/v1/calculations" \
  --header "Authorization: Bearer $SALESTAX_API_KEY"
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-1001-calc" \
  --data '{"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 responseJSON

{
  "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": [
    {
      "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"
}

400 errorapplication/problem+json

{
  "type": "https://api.salestaxcalculatorapi.com/problems/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The request body must be valid JSON.",
  "instance": "/v1/calculations",
  "code": "invalid_request",
  "request_id": "req_01J6A3RZ1HT2K3W2X8R7P1J4C9",
  "retryable": false
}

Parameters

Send these headers and path or query values with the request.

Name	Type	Required	Description
`Authorization`	`string`	Yes	Send your API key as a bearer token.
`Content-Type`	`string`	Yes	Use application/json.
`Idempotency-Key`	`string`	Yes	A caller-generated key. Reusing it with the same canonical request returns the original effect. Reusing it with different content returns a conflict.
`expand`	`string`	No	Set to audit for an authorized customer-safe audit expansion.

Request body

Required JSON body.

Name	Type	Required	Description
`reference`	`string`	No	See the request example for the full field shape.
`transaction_date`	`string`	No	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`	Yes	ISO 4217 currency code.
`tax_behavior`	`string`	Yes	Values: exclusive, inclusive.
`billing_event`	`string`	Yes	Values: one_time_charge, subscription_start, subscription_renewal, metered_usage, free_trial, paid_trial, discount, proration, supported_bundle.
`seller`	`object`	Yes	Object with the fields listed below.
`customer`	`object`	Yes	Object with the fields listed below.
`ship_from`	`object`	No	Object with the fields listed below.
`ship_to`	`object`	No	Object with the fields listed below.
`lines`	`array<object>`	Yes	Array of objects with the fields listed below.

Name

Type

Required

Description

country

string

Yes

See the request example for the full field shape.

channel_role

string

Yes

Values: direct_legal_supplier, marketplace_operator, marketplace_seller, merchant_of_record, disclosed_agent, reseller_principal.

registrations

array

Yes

See the request example for the full field shape.

registrations[].country

string

Yes

See the request example for the full field shape.

registrations[].state

string

See the request example for the full field shape.

registrations[].type

string

Yes

See the request example for the full field shape.

registrations[].effective_from

string

Yes

See the request example for the full field shape.

registrations[].effective_to

string

See the request example for the full field shape.

Name

Type

Required

Description

type

string

Values: consumer, business, government, nonprofit.

address

object

Yes

Object with the fields listed below.

address.line1

string

See the request example for the full field shape.

address.line2

string

See the request example for the full field shape.

address.city

string

See the request example for the full field shape.

address.state

string

See the request example for the full field shape.

address.postal_code

string

See the request example for the full field shape.

address.country

string

Yes

See the request example for the full field shape.

tax_ids

array

See the request example for the full field shape.

tax_ids[].type

string

Yes

Values: eu_vat, gb_vat, gst, business_tax_id, other.

tax_ids[].country

string

Yes

See the request example for the full field shape.

tax_ids[].value

string

Yes

See the request example for the full field shape.

location_evidence

array

See the request example for the full field shape.

location_evidence[].kind

string

Yes

Values: billing_address, ip_address, payment_method, self_declaration.

location_evidence[].country

string

Yes

See the request example for the full field shape.

location_evidence[].state

string

See the request example for the full field shape.

Name

Type

Required

Description

line1

string

See the request example for the full field shape.

line2

string

See the request example for the full field shape.

city

string

See the request example for the full field shape.

state

string

See the request example for the full field shape.

postal_code

string

See the request example for the full field shape.

country

string

Yes

See the request example for the full field shape.

Name

Type

Required

Description

line1

string

See the request example for the full field shape.

line2

string

See the request example for the full field shape.

city

string

See the request example for the full field shape.

state

string

See the request example for the full field shape.

postal_code

string

See the request example for the full field shape.

country

string

Yes

See the request example for the full field shape.

Name

Type

Required

Description

reference

string

Yes

See the request example for the full field shape.

amount

string

Yes

Non-negative decimal amount in the currency's ordinary unit. Currency-specific scale is enforced.

quantity

string

Positive decimal quantity. Defaults to 1 when omitted.

tax_code

string

Yes

See the request example for the full field shape.

tax_behavior

string

Values: exclusive, inclusive.

Responses

201

The sales tax calculation was saved.

Headers: Request-Id, Idempotent-Replayed, RateLimit-Limit, RateLimit-Remaining

400

The request shape, parameter, or header is invalid.

401

A valid API key is required.

Headers: WWW-Authenticate

403

The authenticated key cannot perform this operation.

409

The request conflicts with an existing idempotency key or the current state of a saved record.

422

The request is valid, but the API cannot complete it. For example, the facts may not qualify or an adjustment may exceed the amounts left to reverse.

429

The request exceeded an API safety limit. It did not count toward API usage.

Headers: Retry-After

503

A required service is unavailable, so the API could not process the request.

Headers: Retry-After

curl --request POST \ --url "https://api.salestaxcalculatorapi.com/v1/calculations" \ --header "Authorization: Bearer $SALESTAX_API_KEY" --header "Content-Type: application/json" \ --header "Idempotency-Key: order-1001-calc" \ --data '{"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"}]}'

{ "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": [ { "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" }

{ "type": "https://api.salestaxcalculatorapi.com/problems/invalid_request", "title": "Invalid request", "status": 400, "detail": "The request body must be valid JSON.", "instance": "/v1/calculations", "code": "invalid_request", "request_id": "req_01J6A3RZ1HT2K3W2X8R7P1J4C9", "retryable": false }