Skip to content

Tax calculation callbacks

A tax calculation callback registers the HTTPS endpoint of your own tax engine and how Flint signs requests to it. Each callback has a tax_calculation_callback_id beginning with tcb_, and every configuration change publishes an immutable revision with an ID beginning with tcbr_. Tax calculation callbacks walks through creating, testing, and selecting one.

Each environment selects at most one callback with tax.calculation_callback_id in settings. Live and each sandbox keep their own callbacks and their own selection.

Read callbacks with settings.read or settings.write. Create, change, archive, test, and rotate with settings.write. Merchant API keys, CLI tokens, and Dashboard sessions can call these routes. Partner app tokens can't, as with the tax connection.

An order whose tax.calculation.components_source is callback asks the selected callback for its external tax components whenever its tax would change, and before a payment when its last evaluation is more than 24 hours old. Calculate order tax documents when Flint calls, the request and response bodies, and failures. Other orders, and checkout session, payment link, and subscription orders Flint creates, are taxed the same whether or not a callback is selected.

Fields#

FieldDescription
tax_calculation_callback_idThe callback's stable ID, beginning with tcb_. It is the aud claim of the JWT on every request.
current_tax_calculation_callback_revision_idThe current revision, beginning with tcbr_. It changes when configuration or signing_methods changes.
nameA label for you.
external_reference_idYour own ID for the callback, such as its ID in your system. Omitted when you haven't set one. Send null on PATCH to clear it.
statusinactive, active, or archived. See Status.
versionAdvances on every write. Send it as expected_version; see Versions.
configurationThe URL and request limits. See Configuration.
signing_methods["jwt"] by default; hmac adds a shared secret. See Signing.
secret, key_idThe HMAC shared secret and its signing key ID. Returned once, in the create response when signing_methods includes hmac. Reads, lists, and updates omit them, and a JWT-only callback never has them. rotate-secret returns a new pair.
circuit_state, circuit_failure_countThe circuit state of the current revision. See Circuit state.
created_at, updated_atWhen the callback was created and last changed.

Callbacks take no description or metadata.

Configuration#

configuration keyDefault
urlRequired. HTTPS, no username or password, and a public host.
request_timeout_seconds3, between 0.1 and 10
maximum_request_bytes, maximum_response_bytes262144, up to 1048576
redirect_policyreject, the only value: Flint never follows redirects

A malformed URL, or a private or internal host, returns 400 INVALID_REQUEST with detail code INVALID_VALUE and param configuration.url.

Status#

status on tax calculation callback
Final values do not change again
  • inactive
    Not selectable. New callbacks start here. Connection checks and test deliveries work.
  • active
    Can be selected in tax.calculation_callback_id.
  • archivedFinal
    Retired with DELETE. Still readable by ID, but it can't be changed, activated, or tested again. Create a new callback instead.

Send a status change in its own PATCH, with nothing but status and an optional expected_version. Combining it with other fields returns 400 INVALID_REQUEST with param status.

Select a callback#

Select a callback with PATCH /v1/settings:

JSON
{"tax": {"calculation_callback_id": "tcb_01ARZ3NDEKTSV4RRFFQ69G5FAV"}}

The callback must be active. Selecting a different callback replaces the previous selection in the same write, so switching never leaves the environment with no callback or with two. The settings response, and GET /v1/settings, return the selected ID in tax.calculation_callback_id.

Flint refuses to deactivate or archive a selected callback with 409 RESOURCE_IN_USE. details[0].blocking_resources names your merchant account, with resource_type merchant and a mer_ resource_id, because the selection lives in your settings. Select another callback or clear the selection, then retry.

Versions#

Every callback has a version that advances on each write. Send it as expected_version when a PATCH changes anything a request depends on:

Changeexpected_version
configuration or signing_methodsRequired
name or statusOptional

DELETE takes an optional expected_version query parameter, such as ?expected_version=3.

Leaving out a required fence returns 400 INVALID_REQUEST with param expected_version. A stale value returns 409 VERSION_CONFLICT with param expected_version and the current version in details[0].current_version. After a stale expected_version, read the callback again, rebuild the change, and send it with a new Idempotency-Key. A write without a fence that loses a race to another write returns 409 CONCURRENT_MODIFICATION with no param, including when part of the write had already started. Send the same request again with the same Idempotency-Key.

How configuration updates#

Sending configuration changes only the keys you send. Each key replaces that part whole, and the rest keep their values. The merged result must be a configuration you could create, and an empty configuration is invalid. On PATCH, an optional key set to null restores its default: 3 seconds for request_timeout_seconds, 262144 bytes for maximum_request_bytes and maximum_response_bytes, and reject for redirect_policy. url can't be null, and no key accepts null on create.

Each change to configuration or signing_methods publishes a new revision with its own circuit. Sending a field that doesn't belong to a callback, such as description or metadata, returns 400 INVALID_REQUEST with param naming it.

Signing#

New callbacks default to signing_methods: ["jwt"]. Flint sends Authorization: Bearer <token>, a JWT signed with a key from Flint's public JWKS. Its aud claim is the callback's tcb_ ID, iat equals the webhook-timestamp header, exp is iat + 300, and body_sha256 binds the exact request bytes. jti is unique to each HTTP request. The tax_calculation_evaluation_id (tce_...) is also the webhook-id header. Verification code is available in Node, Python, and Go.

Add hmac on create to also receive a shared secret, returned once with its key_id. PATCH replaces the whole set and requires expected_version. An empty array, an unknown value, or a duplicate returns 400 INVALID_REQUEST with an INVALID_VALUE detail for signing_methods. Removing hmac deletes the current and previous secrets.

POST /v1/tax-calculation-callbacks/{tax_calculation_callback_id}/rotate-secret issues the first secret and adds hmac, or rotates an existing secret with a one-hour overlap during which requests carry both signatures. Rotating again during the overlap returns 409 ACTION_NOT_ALLOWED with reason in_progress, and details[0].previous_key_expires_at says when you can rotate again. Adding hmac through PATCH when no secret exists returns 409 ACTION_NOT_ALLOWED with reason secret_not_issued.

If Flint can't sign a JWT, it sends no request, including for a hybrid callback with hmac. Connection checks and test deliveries then return 503 SERVICE_UNAVAILABLE.

Connection checks and test deliveries#

POST .../check-connection sends {"type":"connection_check"}. POST .../test-deliveries sends a signed sample request with "test": true, a tax_calculation_evaluation_id beginning with tce_, and empty line_items and charges. A test delivery passes when the response echoes that ID and returns empty line_item_calculations and charge_calculations; a mismatched ID, or a non-empty array, fails with failure_category invalid_response. Both run on any inactive or active callback. Each runs once per Idempotency-Key: repeating a key returns the stored result without contacting your endpoint. An archived callback returns 409 ACTION_NOT_ALLOWED with reason archived.

A connection check returns 200 and a test delivery returns 201. Both return status succeeded or failed, the http_status_code, latency_milliseconds, and, on failure, a failure_category: dns_error, tls_error, connection_error, blocked_target, timeout, authentication_or_http_error, invalid_response, or request_error. The test step says what to check for each category.

Circuit state#

circuit_state and circuit_failure_count describe the callback's current revision, and each revision has its own circuit. An order evaluation that fails after its one retry, or whose answer Flint rejects, counts as a failure; 30 in a row open the circuit for 30 seconds, and a valid answer closes it. Connection checks and test deliveries send one request, don't retry, and never change either field.

Archive a callback#

DELETE archives a callback permanently. It stays readable by ID, and lists leave it out unless status names archived, such as status=active,inactive,archived. A DELETE without expected_version on a callback that is already archived returns 200 with the callback and changes nothing, so a retry is safe. Archiving advances version, so retry a fenced DELETE with the same Idempotency-Key; the same fence without that key returns 409 VERSION_CONFLICT. Any other write to an archived callback returns 409 ACTION_NOT_ALLOWED with reason archived. A selected callback can't be archived; see Select a callback.

Webhook#

Each change sends an event whose data is the callback:

EventSent when
tax_calculation_callback.createdYou create a callback.
tax_calculation_callback.activatedA callback becomes active.
tax_calculation_callback.deactivatedAn active callback becomes inactive.
tax_calculation_callback.updatedconfiguration, name, external_reference_id, or signing_methods change, or the first HMAC secret is issued. Rotating a secret that already exists changes how requests are signed but sends no event and doesn't advance version.
tax_calculation_callback.archivedYou archive a callback.

Errors#

  • HTTP 400
    param names the field. A configuration value failed validation, such as a private host in configuration.url. A required expected_version is missing. A status change was combined with other fields, or signing_methods is empty, unknown, or duplicated.
  • HTTP 404
    The callback doesn't exist in this environment. details[0].resource_type and details[0].resource_id name it.
  • HTTP 409
    VERSION_CONFLICTRefresh, then retry
    The callback changed after you read it. details[0].current_version has its version. Read it again, rebuild the change, and retry.
  • HTTP 409
    CONCURRENT_MODIFICATIONRetry the same request
    Another write changed the callback at the same time, and your request sent no expected_version. Send the same request again with the same Idempotency-Key.
  • HTTP 409
    Your settings select the callback, and details[0].blocking_resources names your merchant account. Select another callback or clear the selection, then retry.
  • HTTP 409
    With reason archived, the callback is archived and can't change. secret_not_issued means hmac was added before a secret exists, so call rotate-secret. in_progress means a rotation's one-hour overlap hasn't ended.
  • HTTP 503
    SERVICE_UNAVAILABLERetry the same request
    Flint couldn't sign a request, so a connection check or test delivery wasn't sent.
Tax calculation callbacksRegister, verify, test, and select a callback.Sales taxAutomatic tax and external tax components.SettingsSelect the callback with tax.calculation_callback_id.

The Tax calculation callback object#

An endpoint that supplies tax calculations.

Returned by GET /v1/tax-calculation-callbacks/{tax_calculation_callback_id} and carried by the endpoints below.

Attributes

circuit_failure_countintegerRequired

Consecutive failed requests to the endpoint for the current revision. A valid response resets it.

circuit_stateenumRequired

Whether Flint is calling the endpoint, for the current revision. - `closed`: Flint calls the endpoint. - `open`: Flint stopped calling the endpoint after 30 consecutive failed requests. - `half_open`: 30 seconds after opening, the next request is a probe: a valid response closes the circuit, and a failure opens it again.

  • closed
  • open
  • half_open
configurationobjectRequired

The endpoint URL and request limits.

created_atstringRequired

RFC3339 timestamp.

current_tax_calculation_callback_revision_idstringRequired

ID of the callback's current revision, beginning with `tcbr_`. It changes whenever `configuration` or `signing_methods` changes, and each revision has its own circuit.

external_reference_idstring

Caller-owned identifier for this resource in an external system.

key_idstring

ID of the HMAC signing key that goes with `secret`. Returned only in the response that returns `secret`, so it is omitted on reads, lists, and updates, and for a JWT-only callback.

namestringRequired

Your label for the callback.

secretstring

Initial HMAC shared secret, returned once when hmac is included in signing_methods.

signing_methodsarray of enumRequired

How Flint signs requests to your endpoint: `jwt` for a bearer JWT you verify with Flint's public keys, `hmac` for a shared secret, or both.

  • jwt
  • hmac
statusenumRequired

Whether the callback can be selected in `tax.calculation_callback_id`. - `inactive`: Not selectable in settings. New callbacks start here. Connection checks and test deliveries still run. - `active`: Can be selected in `tax.calculation_callback_id`. - `archived`: Retired with `DELETE`. Still readable by ID, but it can't be changed, activated, or tested again.

  • inactive
  • active
  • archived
tax_calculation_callback_idstringRequired

Unique identifier for this tax calculation callback, prefixed `tcb_`.

updated_atstringRequired

RFC3339 timestamp.

versionintegerRequired

Advances on every write. Send it as `expected_version` when you update `configuration` or `signing_methods`.

JSON
{
  "circuit_failure_count": 0,
  "circuit_state": "closed",
  "configuration": {
    "maximum_request_bytes": 262144,
    "maximum_response_bytes": 262144,
    "redirect_policy": "reject",
    "request_timeout_seconds": 3,
    "url": "https://example.com/tax"
  },
  "created_at": "2026-11-01T12:00:00Z",
  "current_tax_calculation_callback_revision_id": "tcbr_01J00000000000000000000000",
  "name": "Merchant tax engine",
  "signing_methods": [
    "jwt"
  ],
  "status": "inactive",
  "tax_calculation_callback_id": "tcb_01J00000000000000000000000",
  "updated_at": "2026-11-01T12:00:00Z",
  "version": 1
}

List tax calculation callbacks#

GET/v1/tax-calculation-callbacks

Requires scope settings.read or settings.write

Rate limit: read

Tax calculation callback configuration is scoped to the selected environment. Partner installation tokens are unsupported. Default order: created_at descending, then tax_calculation_callback_id descending.

Query parameters

page_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, signed next_page_token from the previous response, bound to the list and caller. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An altered, invalid, expired, or mismatched token returns a validation error.

querystring

Search tax_calculation_callback_id, name, and external_reference_id.

external_reference_idstring

Match the external reference ID.

statusarray of enum

Filter by status. Omitted, the list leaves out archived rows; name archived to include them. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.

  • active
  • inactive
  • archived

Response · 200

The tax calculation callback result.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl https://api.withflintpay.com/v1/tax-calculation-callbacks \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

The tax calculation callback result.

JSON
{
  "data": [
    {
      "circuit_failure_count": 0,
      "circuit_state": "closed",
      "configuration": {
        "maximum_request_bytes": 262144,
        "maximum_response_bytes": 262144,
        "redirect_policy": "reject",
        "request_timeout_seconds": 3,
        "url": "https://example.com/tax"
      },
      "created_at": "2026-11-01T12:00:00Z",
      "current_tax_calculation_callback_revision_id": "tcbr_01J00000000000000000000000",
      "name": "Merchant tax engine",
      "signing_methods": [
        "jwt"
      ],
      "status": "inactive",
      "tax_calculation_callback_id": "tcb_01J00000000000000000000000",
      "updated_at": "2026-11-01T12:00:00Z",
      "version": 1
    }
  ],
  "meta": {
    "api_version": "2026-09-07"
  },
  "next_page_token": "",
  "request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}

Create a tax calculation callback#

POST/v1/tax-calculation-callbacksIdempotent

Requires scope settings.write

Rate limit: sensitive_write

Tax calculation callback configuration is scoped to the selected environment. Partner installation tokens are unsupported. Creates an inactive callback and immutable revision 1. signing_methods defaults to ["jwt"]. Verify the JWT with Flint's public JWKS, aud equal to tax_calculation_callback_id, and body_sha256 over the exact request bytes. HMAC secrets are returned only once when hmac is selected.

Request body

configurationobjectRequired

The endpoint URL and request limits. Only `url` is required.

external_reference_idstring

Caller-owned identifier for this resource in an external system.

namestringRequired

Your label for the callback, from 1 to 255 characters. Surrounding whitespace is trimmed before length validation. A supplied value cannot be blank; use null where clearing is supported.

signing_methodsarray of enum

How Flint signs requests to your endpoint: `jwt` for a bearer JWT you verify with Flint's public keys, `hmac` for a shared secret, or both. Defaults to `jwt`.

  • jwt
  • hmac

Response · 201

The tax calculation callback result.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl -X POST https://api.withflintpay.com/v1/tax-calculation-callbacks \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "configuration": {
      "url": "https://example.com/tax"
    },
    "name": "Merchant tax engine"
  }'

Get a tax calculation callback#

GET/v1/tax-calculation-callbacks/{tax_calculation_callback_id}

Requires scope settings.read or settings.write

Rate limit: read

Tax calculation callback configuration is scoped to the selected environment. Partner installation tokens are unsupported.

Path parameters

tax_calculation_callback_idstringRequired

Tax calculation callback ID. Must be a valid ID with prefix tcb_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Response · 200

The tax calculation callback result.

Same response as Create a tax calculation callback.

curl https://api.withflintpay.com/v1/tax-calculation-callbacks/tcb_01KEZF7C00N7SER74Y2E6D1ZGT \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

The tax calculation callback result.

JSON
{
  "data": {
    "circuit_failure_count": 0,
    "circuit_state": "closed",
    "configuration": {
      "maximum_request_bytes": 262144,
      "maximum_response_bytes": 262144,
      "redirect_policy": "reject",
      "request_timeout_seconds": 3,
      "url": "https://example.com/tax"
    },
    "created_at": "2026-11-01T12:00:00Z",
    "current_tax_calculation_callback_revision_id": "tcbr_01J00000000000000000000000",
    "name": "Merchant tax engine",
    "signing_methods": [
      "jwt"
    ],
    "status": "inactive",
    "tax_calculation_callback_id": "tcb_01J00000000000000000000000",
    "updated_at": "2026-11-01T12:00:00Z",
    "version": 1
  },
  "meta": {
    "api_version": "2026-09-07"
  },
  "request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}

Update a tax calculation callback#

PATCH/v1/tax-calculation-callbacks/{tax_calculation_callback_id}Idempotent

Requires scope settings.write

Rate limit: sensitive_write

Tax calculation callback configuration is scoped to the selected environment. Partner installation tokens are unsupported. Configuration and signing-method changes require expected_version and publish an immutable revision. Configuration fields are patched individually. Change status on its own. A callback selected by tax.calculation_callback_id cannot be deactivated.

Path parameters

tax_calculation_callback_idstringRequired

Tax calculation callback ID. Must be a valid ID with prefix tcb_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

Send at least one of these

expected_versioninteger

The `version` you last read. A stale value is refused with a version conflict. Required with `configuration` and `signing_methods`.

Response · 200

The tax calculation callback result.

Same response as Create a tax calculation callback.

curl -X PATCH https://api.withflintpay.com/v1/tax-calculation-callbacks/tcb_01KEZF7C00N7SER74Y2E6D1ZGT \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_version": 1,
    "status": "active"
  }'

Archive a tax calculation callback#

DELETE/v1/tax-calculation-callbacks/{tax_calculation_callback_id}Idempotent

Requires scope settings.write

Rate limit: sensitive_write

Tax calculation callback configuration is scoped to the selected environment. Partner installation tokens are unsupported. Archives the callback. Select another callback or clear tax.calculation_callback_id before archiving the selected callback.

Path parameters

tax_calculation_callback_idstringRequired

Tax calculation callback ID. Must be a valid ID with prefix tcb_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Query parameters

expected_versioninteger

Current callback version.

Response · 200

The tax calculation callback result.

Same response as Create a tax calculation callback.

curl -X DELETE https://api.withflintpay.com/v1/tax-calculation-callbacks/tcb_01KEZF7C00N7SER74Y2E6D1ZGT \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Check the callback connection#

POST/v1/tax-calculation-callbacks/{tax_calculation_callback_id}/check-connectionIdempotent

Requires scope settings.write

Rate limit: external_provider_action

Tax calculation callback configuration is scoped to the selected environment. Partner installation tokens are unsupported. Sends a signed connection_check request. A 2xx response succeeds unless it sets a Content-Type other than application/json or its body is larger than maximum_response_bytes. Runs for inactive and active callbacks without changing the circuit breaker.

Path parameters

tax_calculation_callback_idstringRequired

Tax calculation callback ID. Must be a valid ID with prefix tcb_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Response · 200

The tax calculation callback result.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl -X POST https://api.withflintpay.com/v1/tax-calculation-callbacks/tcb_01KEZF7C00N7SER74Y2E6D1ZGT/check-connection \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Rotate the callback signing secret#

POST/v1/tax-calculation-callbacks/{tax_calculation_callback_id}/rotate-secretIdempotent

Requires scope settings.write

Rate limit: sensitive_write

Tax calculation callback configuration is scoped to the selected environment. Partner installation tokens are unsupported. Issues an HMAC secret and adds hmac when needed. Returns the new secret once. The previous secret remains valid during the same overlap as delivery callbacks.

Path parameters

tax_calculation_callback_idstringRequired

Tax calculation callback ID. Must be a valid ID with prefix tcb_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Response · 200

The tax calculation callback result.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl -X POST https://api.withflintpay.com/v1/tax-calculation-callbacks/tcb_01KEZF7C00N7SER74Y2E6D1ZGT/rotate-secret \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Send a tax callback test delivery#

POST/v1/tax-calculation-callbacks/{tax_calculation_callback_id}/test-deliveriesIdempotent

Requires scope settings.write

Rate limit: external_provider_action

Tax calculation callback configuration is scoped to the selected environment. Partner installation tokens are unsupported. Sends a signed synthetic tax_calculation request with test true and empty line_items and charges. The response must echo tax_calculation_evaluation_id and return empty line_item_calculations and charge_calculations. Runs for inactive and active callbacks without changing the circuit breaker.

Path parameters

tax_calculation_callback_idstringRequired

Tax calculation callback ID. Must be a valid ID with prefix tcb_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Response · 201

The tax calculation callback result.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl -X POST https://api.withflintpay.com/v1/tax-calculation-callbacks/tcb_01KEZF7C00N7SER74Y2E6D1ZGT/test-deliveries \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Was this helpful?