Calculation batches · POST

Create a sales tax calculation batch

Saves and queues 1 to 100 sales tax calculations for background processing. The response includes a batch ID.

POST/v1/calculation-batches

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.

Request body

Required JSON body.

Name	Type	Required	Description
`reference`	`string`	No	See the request example for the full field shape.
`calculations`	`array<object>`	Yes	Array of objects with the fields listed below.

calculations[]51 fields

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.
`seller.country`	`string`	Yes	See the request example for the full field shape.
`seller.channel_role`	`string`	Yes	Values: direct_legal_supplier, marketplace_operator, marketplace_seller, merchant_of_record, disclosed_agent, reseller_principal.
`seller.registrations`	`array`	Yes	See the request example for the full field shape.
`seller.registrations[].country`	`string`	Yes	See the request example for the full field shape.
`seller.registrations[].state`	`string`	No	See the request example for the full field shape.
`seller.registrations[].type`	`string`	Yes	See the request example for the full field shape.
`seller.registrations[].effective_from`	`string`	Yes	See the request example for the full field shape.
`seller.registrations[].effective_to`	`string`	No	See the request example for the full field shape.
`customer`	`object`	Yes	Object with the fields listed below.
`customer.type`	`string`	No	Values: consumer, business, government, nonprofit.
`customer.address`	`object`	Yes	Object with the fields listed below.
`customer.address.line1`	`string`	No	See the request example for the full field shape.
`customer.address.line2`	`string`	No	See the request example for the full field shape.
`customer.address.city`	`string`	No	See the request example for the full field shape.
`customer.address.state`	`string`	No	See the request example for the full field shape.
`customer.address.postal_code`	`string`	No	See the request example for the full field shape.
`customer.address.country`	`string`	Yes	See the request example for the full field shape.
`customer.tax_ids`	`array`	No	See the request example for the full field shape.
`customer.tax_ids[].type`	`string`	Yes	Values: eu_vat, gb_vat, gst, business_tax_id, other.
`customer.tax_ids[].country`	`string`	Yes	See the request example for the full field shape.
`customer.tax_ids[].value`	`string`	Yes	See the request example for the full field shape.
`customer.location_evidence`	`array`	No	See the request example for the full field shape.
`customer.location_evidence[].kind`	`string`	Yes	Values: billing_address, ip_address, payment_method, self_declaration.
`customer.location_evidence[].country`	`string`	Yes	See the request example for the full field shape.
`customer.location_evidence[].state`	`string`	No	See the request example for the full field shape.
`ship_from`	`object`	No	Object with the fields listed below.
`ship_from.line1`	`string`	No	See the request example for the full field shape.
`ship_from.line2`	`string`	No	See the request example for the full field shape.
`ship_from.city`	`string`	No	See the request example for the full field shape.
`ship_from.state`	`string`	No	See the request example for the full field shape.
`ship_from.postal_code`	`string`	No	See the request example for the full field shape.
`ship_from.country`	`string`	Yes	See the request example for the full field shape.
`ship_to`	`object`	No	Object with the fields listed below.
`ship_to.line1`	`string`	No	See the request example for the full field shape.
`ship_to.line2`	`string`	No	See the request example for the full field shape.
`ship_to.city`	`string`	No	See the request example for the full field shape.
`ship_to.state`	`string`	No	See the request example for the full field shape.
`ship_to.postal_code`	`string`	No	See the request example for the full field shape.
`ship_to.country`	`string`	Yes	See the request example for the full field shape.
`lines`	`array`	Yes	See the request example for the full field shape.
`lines[].reference`	`string`	Yes	See the request example for the full field shape.
`lines[].amount`	`string`	Yes	Non-negative decimal amount in the currency's ordinary unit. Currency-specific scale is enforced.
`lines[].quantity`	`string`	No	Positive decimal quantity. Defaults to 1 when omitted.
`lines[].tax_code`	`string`	Yes	See the request example for the full field shape.
`lines[].tax_behavior`	`string`	No	Values: exclusive, inclusive.

Responses

202

The batch was saved and queued for processing.

Headers: Request-Id, Idempotent-Replayed, Location

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 key

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/calculation-batches" \
  --header "Authorization: Bearer $SALESTAX_API_KEY"
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: erp-import-2026-08" \
  --data '{"reference":"erp-import-2026-08","calculations":[{"reference":"invoice-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"}]}]}'

202 responseJSON

{
  "id": "batch_01J6A6X3DWHGCY7G2XXE5MPA2R",
  "object": "calculation_batch",
  "reference": "erp-import-2026-08",
  "status": "queued",
  "total_count": 1,
  "succeeded_count": 0,
  "failed_count": 0,
  "items": [
    {
      "index": 0,
      "status": "queued"
    }
  ],
  "request_id": "req_01J6A3RZ1HT2K3W2X8R7P1J4C9",
  "created_at": "2026-08-29T12:01: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.

Name

Type

Required

Description

reference

string

See the request example for the full field shape.

calculations

array<object>

Yes

Array of objects with the fields listed below.

Name

Type

Required

Description

reference

string

See the request example for the full field shape.

transaction_date

string

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.

seller.country

string

Yes

See the request example for the full field shape.

seller.channel_role

string

Yes

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

seller.registrations

array

Yes

See the request example for the full field shape.

seller.registrations[].country

string

Yes

See the request example for the full field shape.

seller.registrations[].state

string

See the request example for the full field shape.

seller.registrations[].type

string

Yes

See the request example for the full field shape.

seller.registrations[].effective_from

string

Yes

See the request example for the full field shape.

seller.registrations[].effective_to

string

See the request example for the full field shape.

customer

object

Yes

Object with the fields listed below.

customer.type

string

Values: consumer, business, government, nonprofit.

customer.address

object

Yes

Object with the fields listed below.

customer.address.line1

string

See the request example for the full field shape.

customer.address.line2

string

See the request example for the full field shape.

customer.address.city

string

See the request example for the full field shape.

customer.address.state

string

See the request example for the full field shape.

customer.address.postal_code

string

See the request example for the full field shape.

customer.address.country

string

Yes

See the request example for the full field shape.

customer.tax_ids

array

See the request example for the full field shape.

customer.tax_ids[].type

string

Yes

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

customer.tax_ids[].country

string

Yes

See the request example for the full field shape.

customer.tax_ids[].value

string

Yes

See the request example for the full field shape.

customer.location_evidence

array

See the request example for the full field shape.

customer.location_evidence[].kind

string

Yes

Values: billing_address, ip_address, payment_method, self_declaration.

customer.location_evidence[].country

string

Yes

See the request example for the full field shape.

customer.location_evidence[].state

string

See the request example for the full field shape.

ship_from

object

Object with the fields listed below.

ship_from.line1

string

See the request example for the full field shape.

ship_from.line2

string

See the request example for the full field shape.

ship_from.city

string

See the request example for the full field shape.

ship_from.state

string

See the request example for the full field shape.

ship_from.postal_code

string

See the request example for the full field shape.

ship_from.country

string

Yes

See the request example for the full field shape.

ship_to

object

Object with the fields listed below.

ship_to.line1

string

See the request example for the full field shape.

ship_to.line2

string

See the request example for the full field shape.

ship_to.city

string

See the request example for the full field shape.

ship_to.state

string

See the request example for the full field shape.

ship_to.postal_code

string

See the request example for the full field shape.

ship_to.country

string

Yes

See the request example for the full field shape.

lines

array

Yes

See the request example for the full field shape.

lines[].reference

string

Yes

See the request example for the full field shape.

lines[].amount

string

Yes

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

lines[].quantity

string

Positive decimal quantity. Defaults to 1 when omitted.

lines[].tax_code

string

Yes

See the request example for the full field shape.

lines[].tax_behavior

string

Values: exclusive, inclusive.

Responses

202

The batch was saved and queued for processing.

Headers: Request-Id, Idempotent-Replayed, Location

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/calculation-batches" \ --header "Authorization: Bearer $SALESTAX_API_KEY" --header "Content-Type: application/json" \ --header "Idempotency-Key: erp-import-2026-08" \ --data '{"reference":"erp-import-2026-08","calculations":[{"reference":"invoice-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": "batch_01J6A6X3DWHGCY7G2XXE5MPA2R", "object": "calculation_batch", "reference": "erp-import-2026-08", "status": "queued", "total_count": 1, "succeeded_count": 0, "failed_count": 0, "items": [ { "index": 0, "status": "queued" } ], "request_id": "req_01J6A3RZ1HT2K3W2X8R7P1J4C9", "created_at": "2026-08-29T12:01: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 }