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#
| Field | Description |
|---|---|
tax_calculation_callback_id | The callback's stable ID, beginning with tcb_. It is the aud claim of the JWT on every request. |
current_tax_calculation_callback_revision_id | The current revision, beginning with tcbr_. It changes when configuration or signing_methods changes. |
name | A label for you. |
external_reference_id | Your 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. |
status | inactive, active, or archived. See Status. |
version | Advances on every write. Send it as expected_version; see Versions. |
configuration | The URL and request limits. See Configuration. |
signing_methods | ["jwt"] by default; hmac adds a shared secret. See Signing. |
secret, key_id | The 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_count | The circuit state of the current revision. See Circuit state. |
created_at, updated_at | When the callback was created and last changed. |
Callbacks take no description or metadata.
Configuration#
configuration key | Default |
|---|---|
url | Required. HTTPS, no username or password, and a public host. |
request_timeout_seconds | 3, between 0.1 and 10 |
maximum_request_bytes, maximum_response_bytes | 262144, up to 1048576 |
redirect_policy | reject, 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 callbackinactiveNot selectable. New callbacks start here. Connection checks and test deliveries work.activeCan be selected intax.calculation_callback_id.archivedFinalRetired withDELETE. 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:
{"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:
| Change | expected_version |
|---|---|
configuration or signing_methods | Required |
name or status | Optional |
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:
| Event | Sent when |
|---|---|
tax_calculation_callback.created | You create a callback. |
tax_calculation_callback.activated | A callback becomes active. |
tax_calculation_callback.deactivated | An active callback becomes inactive. |
tax_calculation_callback.updated | configuration, 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.archived | You archive a callback. |
Errors#
- StatusHTTP 400CodeINVALID_
REQUEST What to doparamnames the field. A configuration value failed validation, such as a private host inconfiguration.url. A requiredexpected_versionis missing. Astatuschange was combined with other fields, orsigning_methodsis empty, unknown, or duplicated. - StatusHTTP 404What to doThe callback doesn't exist in this environment.
details[0].resource_typeanddetails[0].resource_idname it. - StatusHTTP 409What to doThe callback changed after you read it.
details[0].current_versionhas its version. Read it again, rebuild the change, and retry. - StatusHTTP 409What to doAnother write changed the callback at the same time, and your request sent no
expected_version. Send the same request again with the sameIdempotency-Key. - StatusHTTP 409CodeRESOURCE_
IN_ USE What to doYour settings select the callback, anddetails[0].blocking_resourcesnames your merchant account. Select another callback or clear the selection, then retry. - StatusHTTP 409What to doWith
reasonarchived, the callback is archived and can't change.secret_not_issuedmeanshmacwas added before a secret exists, so callrotate-secret.in_progressmeans a rotation's one-hour overlap hasn't ended. - StatusHTTP 503What to doFlint couldn't sign a request, so a connection check or test delivery wasn't sent.
Related#
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_countintegerRequiredConsecutive failed requests to the endpoint for the current revision. A valid response resets it.
circuit_stateenumRequiredWhether 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.
closedopenhalf_open
configurationobjectRequiredThe endpoint URL and request limits.
maximum_request_bytesintegerLargest request body Flint sends to your endpoint, in bytes, from 1 to 1048576. Defaults to 262144.
maximum_response_bytesintegerLargest response body Flint accepts from your endpoint, in bytes, from 1 to 1048576. Defaults to 262144.
redirect_policyenumHow Flint treats a redirect from your endpoint. Flint never follows redirects, so `reject` is the only value.
reject
request_timeout_secondsnumberHow long Flint waits for each request to your endpoint, in seconds, from 0.1 to 10. Defaults to 3.
urlstringRequiredHTTPS endpoint that receives signed callback requests.
created_atstringRequiredRFC3339 timestamp.
current_tax_calculation_callback_revision_idstringRequiredID 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_idstringCaller-owned identifier for this resource in an external system.
key_idstringID 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.
namestringRequiredYour label for the callback.
secretstringInitial HMAC shared secret, returned once when hmac is included in signing_methods.
signing_methodsarray of enumRequiredHow 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.
jwthmac
statusenumRequiredWhether 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.
inactiveactivearchived
tax_calculation_callback_idstringRequiredUnique identifier for this tax calculation callback, prefixed `tcb_`.
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredAdvances on every write. Send it as `expected_version` when you update `configuration` or `signing_methods`.
{
"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#
/v1/tax-calculation-callbacksRequires 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_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque, 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.
querystringSearch tax_calculation_callback_id, name, and external_reference_id.
external_reference_idstringMatch the external reference ID.
statusarray of enumFilter 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.
activeinactivearchived
Response · 200
The tax calculation callback result.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
circuit_failure_countintegerRequiredConsecutive failed requests to the endpoint for the current revision. A valid response resets it.
circuit_stateenumRequiredWhether 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.
closedopenhalf_open
configurationobjectRequiredThe endpoint URL and request limits.
created_atstringRequiredRFC3339 timestamp.
current_tax_calculation_callback_revision_idstringRequiredID 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_idstringCaller-owned identifier for this resource in an external system.
key_idstringID 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.
namestringRequiredYour label for the callback.
secretstringInitial HMAC shared secret, returned once when hmac is included in signing_methods.
signing_methodsarray of enumRequiredHow 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.
jwthmac
statusenumRequiredWhether 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.
inactiveactivearchived
tax_calculation_callback_idstringRequiredUnique identifier for this tax calculation callback, prefixed `tcb_`.
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredAdvances on every write. Send it as `expected_version` when you update `configuration` or `signing_methods`.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier 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.
{
"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#
/v1/tax-calculation-callbacksIdempotentRequires 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
configurationobjectRequiredThe endpoint URL and request limits. Only `url` is required.
maximum_request_bytesintegerLargest request body Flint sends to your endpoint, in bytes, from 1 to 1048576. Defaults to 262144.
maximum_response_bytesintegerLargest response body Flint accepts from your endpoint, in bytes, from 1 to 1048576. Defaults to 262144.
redirect_policyenumHow Flint treats a redirect from your endpoint. Flint never follows redirects, so `reject` is the only value.
reject
request_timeout_secondsnumberHow long Flint waits for each request to your endpoint, in seconds, from 0.1 to 10. Defaults to 3.
urlstringRequiredHTTPS endpoint that receives signed callback requests.
external_reference_idstringCaller-owned identifier for this resource in an external system.
namestringRequiredYour 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 enumHow 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`.
jwthmac
Response · 201
The tax calculation callback result.
dataobjectRequiredResource, collection, or operation result returned by this request.
circuit_failure_countintegerRequiredConsecutive failed requests to the endpoint for the current revision. A valid response resets it.
circuit_stateenumRequiredWhether 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.
closedopenhalf_open
configurationobjectRequiredThe endpoint URL and request limits.
created_atstringRequiredRFC3339 timestamp.
current_tax_calculation_callback_revision_idstringRequiredID 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_idstringCaller-owned identifier for this resource in an external system.
key_idstringID 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.
namestringRequiredYour label for the callback.
secretstringInitial HMAC shared secret, returned once when hmac is included in signing_methods.
signing_methodsarray of enumRequiredHow 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.
jwthmac
statusenumRequiredWhether 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.
inactiveactivearchived
tax_calculation_callback_idstringRequiredUnique identifier for this tax calculation callback, prefixed `tcb_`.
updated_atstringRequiredRFC3339 timestamp.
versionintegerRequiredAdvances on every write. Send it as `expected_version` when you update `configuration` or `signing_methods`.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier 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#
/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_idstringRequiredTax 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.
{
"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#
/v1/tax-calculation-callbacks/{tax_calculation_callback_id}IdempotentRequires 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_idstringRequiredTax 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_versionintegerThe `version` you last read. A stale value is refused with a version conflict. Required with `configuration` and `signing_methods`.
expected_versionintegerThe `version` you last read. A stale value is refused with a version conflict. Required with `configuration` and `signing_methods`.
expected_versionintegerThe `version` you last read. A stale value is refused with a version conflict. Required with `configuration` and `signing_methods`.
expected_versionintegerThe `version` you last read. A stale value is refused with a version conflict. Required with `configuration` and `signing_methods`.
expected_versionintegerThe `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#
/v1/tax-calculation-callbacks/{tax_calculation_callback_id}IdempotentRequires 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_idstringRequiredTax 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_versionintegerCurrent 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#
/v1/tax-calculation-callbacks/{tax_calculation_callback_id}/check-connectionIdempotentRequires 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_idstringRequiredTax 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.
dataobjectRequiredResource, collection, or operation result returned by this request.
checked_atstringRequiredWhen Flint sent the connection check.
failure_categoryenumWhy the callback request failed and the action that can make the next one succeed. - `authentication_or_http_error`: Return a 2xx status after verifying the enabled signing methods. For a 401, check JWT verification with Flint's JWKS, issuer, tax_calculation_callback_id audience, expiration, and body_sha256 of the exact request bytes. For HMAC, check the shared secret and verify the raw body before parsing it. - `blocked_target`: Use a public HTTPS callback target allowed by Flint's outbound network policy. - `connection_error`: Restore network connectivity to the callback host, then test again. - `dns_error`: Fix the callback hostname or its DNS records, then test again. - `invalid_response`: Return a 2xx application/json response within maximum_response_bytes. For a test delivery, the body must also echo tax_calculation_evaluation_id with empty line_item_calculations and charge_calculations. Then test again. - `request_error`: Flint couldn't complete the request for another reason. Check the URL and your server logs, then test again. - `timeout`: Acknowledge the callback within its configured timeout, then test again. - `tls_error`: Fix the callback certificate and TLS configuration, then test again.
authentication_or_http_errorblocked_targetconnection_errordns_errorinvalid_responserequest_errortimeouttls_error
http_status_codeintegerHTTP status code your endpoint returned. Omitted when it returned no response.
key_idstringRequiredID of the HMAC signing key that signed this request, as sent in the Flint-Signing-Key-Ids header. Empty for a JWT-only callback, which has no shared secret.
latency_millisecondsintegerRequiredHow long your endpoint took to answer, in milliseconds.
statusenumRequiredWhether your endpoint answered as the callback requires. - `succeeded`: Your endpoint answered as the request requires. - `failed`: The request failed. See `failure_category`.
succeededfailed
tax_calculation_callback_idstringRequiredID of the callback that was called, beginning with `tcb_`.
tax_calculation_callback_revision_idstringRequiredID of the callback revision that was called, beginning with `tcbr_`.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier 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#
/v1/tax-calculation-callbacks/{tax_calculation_callback_id}/rotate-secretIdempotentRequires 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_idstringRequiredTax 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.
dataobjectRequiredResource, collection, or operation result returned by this request.
key_idstringRequiredID of the new HMAC signing key.
secretstringNew HMAC shared secret. Returned only by this response. Returned only to the credential that created it, and omitted when another credential replays the request.
tax_calculation_callback_idstringRequiredID of the callback whose secret was issued or rotated, beginning with `tcb_`.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier 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#
/v1/tax-calculation-callbacks/{tax_calculation_callback_id}/test-deliveriesIdempotentRequires 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_idstringRequiredTax 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.
dataobjectRequiredResource, collection, or operation result returned by this request.
failure_categoryenumWhy the callback request failed and the action that can make the next one succeed. - `authentication_or_http_error`: Return a 2xx status after verifying the enabled signing methods. For a 401, check JWT verification with Flint's JWKS, issuer, tax_calculation_callback_id audience, expiration, and body_sha256 of the exact request bytes. For HMAC, check the shared secret and verify the raw body before parsing it. - `blocked_target`: Use a public HTTPS callback target allowed by Flint's outbound network policy. - `connection_error`: Restore network connectivity to the callback host, then test again. - `dns_error`: Fix the callback hostname or its DNS records, then test again. - `invalid_response`: Return a 2xx application/json response within maximum_response_bytes. For a test delivery, the body must also echo tax_calculation_evaluation_id with empty line_item_calculations and charge_calculations. Then test again. - `request_error`: Flint couldn't complete the request for another reason. Check the URL and your server logs, then test again. - `timeout`: Acknowledge the callback within its configured timeout, then test again. - `tls_error`: Fix the callback certificate and TLS configuration, then test again.
authentication_or_http_errorblocked_targetconnection_errordns_errorinvalid_responserequest_errortimeouttls_error
http_status_codeintegerHTTP status code your endpoint returned. Omitted when it returned no response.
key_idstringRequiredID of the HMAC signing key that signed this request, as sent in the Flint-Signing-Key-Ids header. Empty for a JWT-only callback, which has no shared secret.
latency_millisecondsintegerRequiredHow long your endpoint took to answer, in milliseconds.
statusenumRequiredWhether your endpoint answered as the callback requires. - `succeeded`: Your endpoint answered as the request requires. - `failed`: The request failed. See `failure_category`.
succeededfailed
tax_calculation_callback_idstringRequiredID of the callback that was called, beginning with `tcb_`.
tax_calculation_callback_revision_idstringRequiredID of the callback revision that was called, beginning with `tcbr_`.
tested_atstringRequiredWhen Flint sent the test delivery.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier 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?