Tax connection
The tax connection is your environment's link to the Quaderno account that calculates automatic sales tax. Each environment has one, with a tax_connection_id beginning with tcn_, and each sandbox keeps its own. A connection becomes active when the seller agrees to Flint's disclosure and you send POST /v1/tax-connection/connect. Until then, orders with automatic tax fail with 409 ACTION_NOT_ALLOWED and reason configuration_required instead of calculating zero tax. The error's details[0].resource_type is tax_connection.
GET /v1/tax-connection always returns 200, even before anything exists, so one read tells you whether automatic tax works, why not, and what connecting needs. Read it with settings.read; connect and disconnect with settings.write. Merchant API keys, CLI tokens, and Dashboard sessions can call these routes. Partner app install tokens can't. Live and sandbox environments are separate: a sandbox connection and its registrations never carry over to live, and the seller agrees to the disclosure again for live.
To turn on automatic tax:
- Set
tax.default_line_item_tax_categorythroughPATCH /v1/settingsto a category automatic tax supports, such asgeneralorphysical_goods. - Add a tax registration for each state where the seller collects tax.
- Read
GET /v1/tax-connection. Show the seller every statement indisclosure.statements. - After the seller agrees, send
POST /v1/tax-connection/connectwithdisclosure.version.
The Sales tax guide walks through the same flow with the order requests that follow. To turn automatic tax off later, send POST /v1/tax-connection/disconnect; see Disconnect.
Fields#
| Field | Description |
|---|---|
tax_connection_id | Present once a record exists, which happens at the first registration or the first connect. |
status | Whether automatic tax works. See Status. |
status_reason | Why a not_connected or attention_required connection is in that state, or null. See Status reasons. |
supported_actions | The actions you can take now: connect when POST /v1/tax-connection/connect can complete setup, disconnect when POST /v1/tax-connection/disconnect can turn automatic tax off, otherwise []. See Supported actions. |
business_name | The verified legal business name. Before connect it shows what connect will use. Once connected, it is what the tax account uses. Omitted when Flint has no verified business details. |
business_address | The verified business address, which is the tax origin. Same rule as business_name. |
disclosure | What the seller agrees to when you connect. See Disclosure and seller attestation. |
seller_attestation | {disclosure_version, attested_at} once a connect has recorded the seller's agreement, otherwise null. |
version | Present once a record exists. Increases whenever the connection or one of its registrations changes. |
created_at, updated_at | Present once a record exists. |
Status#
status is a closed set. Branch on it to decide whether automatic tax works.
status | Meaning |
|---|---|
not_connected | Automatic tax is off: it was never connected, or you turned it off. Registrations you add are saved as pending. |
provisioning | A connect is running now. Read again in a few seconds. |
active | Automatic tax calculates for every active registration. |
attention_required | Setup didn't finish, or the connection stopped working. Automatic tax fails with ACTION_NOT_ALLOWED and reason configuration_required until the status is active again. |
disabled | Flint support turned the connection off. Contact support to reconnect. |
A connection never stays in provisioning after a connect stops. If a connect is interrupted, the next read shows attention_required.
Status reasons#
status_reason explains not_connected and attention_required, and is null for the other statuses. It can gain values, so treat one you don't recognize as needing attention and read the connection again later. For not_connected, the reasons below are listed in the order you fix them, and null means connect can succeed.
status | status_reason | What to do |
|---|---|---|
not_connected | not_offered | Automatic tax isn't offered for this account or sandbox. Use external tax, or contact Flint support. |
not_connected | onboarding_required | The merchant has no verified business details yet. Finish onboarding, then read the connection again. |
not_connected | tax_category_required | tax.default_line_item_tax_category in settings isn't a category automatic tax supports. Update it with PATCH /v1/settings. |
not_connected | registration_required | Add at least one tax registration that is pending, scheduled, active, or rejected. ended registrations don't count. |
not_connected | disconnected | You turned automatic tax off with disconnect, and nothing else blocks connecting. Show the disclosure to the seller, then connect again. |
not_connected | null | Show the disclosure to the seller, then connect. |
not_connected, attention_required | temporarily_unavailable | Flint has paused automatic tax for every merchant. Retry later. Connect and registration writes return 503 SERVICE_UNAVAILABLE. |
attention_required | setup_incomplete | A connect didn't finish. Send POST /v1/tax-connection/connect again. |
attention_required | registration_rejected | The tax account rejected a registration. Fix or delete the rejected registration, then connect again. |
attention_required | business_details_changed | The verified business name, email, address, or currency changed after you connected. Contact Flint support to reconnect. Connect, disconnect, and registration writes return 409 ACTION_NOT_ALLOWED with reason reconciliation_required. This also applies after you disconnect. |
attention_required | support_required | Flint couldn't confirm the tax account was created. Contact Flint support with the request_id of the connect. Connect, disconnect, and registration writes return 409 ACTION_NOT_ALLOWED with reason reconciliation_required. |
active, provisioning | null | Nothing to fix. |
disabled | null | Contact Flint support to reconnect. |
Setting or clearing end_date on a scheduled or active registration works in every status, including those that refuse other registration writes.
After a disconnect, status_reason shows the first reason in the order above that still blocks connecting: not_offered, then onboarding_required, then tax_category_required, then registration_required. It shows disconnected only when none of them apply, so disconnected and null both mean connect can succeed.
business_details_changed and temporarily_unavailable are read-time states. Flint works them out when you read the connection and when it calculates tax, and it changes nothing it has stored. They don't advance version and send no webhook. When an order fails with ACTION_NOT_ALLOWED, reason configuration_required, and resource_type tax_connection, read the connection again instead of relying on your mirror of it.
status_reason and supported_actions can also change with the clock. A registration that reaches its end_date stops counting toward registration_required, so a connection that isn't connected can move to registration_required and lose connect from supported_actions without any write. Like the read-time states, this changes no version and sends no webhook. Read the connection before you show a connect control.
Supported actions#
supported_actions lists the actions that can succeed now. It can gain values, so ignore one you don't recognize.
| Action | Listed when |
|---|---|
connect | Connecting can complete setup: the status is not_connected with a null or disconnected reason, or attention_required with setup_incomplete or registration_rejected. |
disconnect | Disconnecting can turn automatic tax off: the status is active, or attention_required with setup_incomplete or registration_rejected. |
A connection in attention_required with setup_incomplete or registration_rejected lists both. In every other state supported_actions is [], including provisioning and disabled. It is also [] for a credential without settings.write, which can read the connection but not change it. Use it to decide which controls to show, and still handle the errors the routes return.
Disclosure and seller attestation#
disclosure holds the text the seller agrees to and its version:
{
"version": "2026-10-26.5f3a9c1e",
"statements": [
{"text": "I confirm this Flint merchant represents one independently liable legal seller and taxpayer. It does not share registrations with another seller, switch sellers by transaction, or use Flint as Merchant of Record."},
{"text": "I authorize Flint to create and configure a Quaderno account for automatic tax calculations. Flint does not file returns or remit tax through this connection."},
{"text": "Automatic tax costs 0.50% of each payment where Flint calculates tax above zero. Payments with tax you supply, or with no tax, have no automatic tax fee."}
]
}
Show every statement, in order, to the seller. Get their agreement to all of them before you send the version. Connecting turns on a billed service and creates a tax account that only Flint support can remove, so the agreement has to come from the seller or someone acting for them. Flint can't check that you showed the text, so sending the version is your statement that you did.
The third statement carries the merchant's own automatic tax rate, so the example rate above is illustrative. version is opaque: don't parse it. It changes whenever the text changes, including a rate change, so read the connection again shortly before you show the disclosure.
Send the version you showed in seller_attestation:
{"seller_attestation": {"disclosure_version": "2026-10-26.5f3a9c1e"}}
If the disclosure changed since you read it, the connect returns 409 ACTION_NOT_ALLOWED with details[0].reason disclosure_changed. details[0].resource_type is tax_connection, and details[0].current_disclosure_version is the version to show next. Read GET /v1/tax-connection, show the seller the current statements, get their agreement, and send the new version. The refusal changes nothing, and remediation.retry is none: the same request fails again until the seller has agreed to the new text.
Once a connect succeeds, seller_attestation holds the version agreed to and attested_at. Registration writes don't ask for the attestation again.
Connect#
POST /v1/tax-connection/connect creates or finishes the tax account from the merchant's verified business details, using tax.default_line_item_tax_category from settings as the account default. It then syncs every pending registration and returns the connection. The body takes seller_attestation (required) and expected_version (optional, the connection's version; a stale value returns 409 VERSION_CONFLICT with details[0].current_version). Send an Idempotency-Key so a retry resumes the same setup instead of starting another.
A connect the seller can fix returns 200 with the result in the connection's state, not an error:
status: "active"means automatic tax is on.status: "attention_required"withstatus_reason: "registration_rejected"means the tax account exists but rejected a registration. List the registrations, fix or delete eachrejectedone, then connect again. Connect takes no registrations in its body. An initial connect with a rejected registration doesn't goactive, because collecting tax without a state the seller says they're registered in would under-collect.
Connecting marks every open order that uses automatic tax, has calculated tax, and has no issued invoice as tax incomplete. The registrations decide where tax applies, so Flint recalculates those orders instead of keeping tax calculated under the old set. Update an order to recalculate it before taking payment.
Connect also turns automatic tax back on after a disconnect. Send a new seller_attestation for the current disclosure: the earlier agreement doesn't carry over. Connecting needs at least one registration that hasn't ended. It doesn't turn tax.default_enabled back on, so update settings if new orders should calculate tax again.
If the response is lost or the request times out, read GET /v1/tax-connection. status: "active" means it worked. provisioning means the connect is still running. attention_required with setup_incomplete means you can send it again. If a connect returns 502 EXTERNAL_SERVICE_ERROR, retry with the same Idempotency-Key; Flint resumes setup and never creates a second tax account. If Flint can't confirm that a tax account was created, the connect returns 503 SERVICE_UNAVAILABLE, the connection reads support_required, and Flint never retries the creation on its own. Contact support with the request_id.
curl -X POST https://api.withflintpay.com/v1/tax-connection/connect \
-H "Authorization: Bearer $FLINT_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: connect-tax-cedar-and-stone" \
-d '{
"seller_attestation": {"disclosure_version": "2026-10-26.5f3a9c1e"}
}'
{
"data": {
"tax_connection_id": "tcn_01KYB4W8M2R6T9XQ3N5HPZ7C0D",
"status": "active",
"status_reason": null,
"supported_actions": [],
"business_name": "Cedar & Stone LLC",
"business_address": {
"line1": "200 Spectrum Center Drive",
"city": "Irvine",
"state": "CA",
"postal_code": "92618",
"country": "US"
},
"disclosure": {
"version": "2026-10-26.5f3a9c1e",
"statements": [
{"text": "I confirm this Flint merchant represents one independently liable legal seller and taxpayer. It does not share registrations with another seller, switch sellers by transaction, or use Flint as Merchant of Record."},
{"text": "I authorize Flint to create and configure a Quaderno account for automatic tax calculations. Flint does not file returns or remit tax through this connection."},
{"text": "Automatic tax costs 0.50% of each payment where Flint calculates tax above zero. Payments with tax you supply, or with no tax, have no automatic tax fee."}
]
},
"seller_attestation": {
"disclosure_version": "2026-10-26.5f3a9c1e",
"attested_at": "2026-11-01T16:42:09Z"
},
"version": 1793551329,
"created_at": "2026-11-01T16:30:41Z",
"updated_at": "2026-11-01T16:42:09Z"
}
}
Disconnect#
POST /v1/tax-connection/disconnect turns automatic tax off. It needs settings.write. The body takes:
tax_default_behavior(required):keeporturn_off. It decides what happens to the Calculate tax on new orders setting,tax.default_enabled. A request without it returns400 INVALID_REQUESTwithREQUIRED.expected_version(optional): the connection'sversion. A stale value returns409 VERSION_CONFLICTwithdetails[0].current_version.
Send an Idempotency-Key. If the request fails partway, retrying with the same key finishes it.
tax_default_behavior never turns tax on. When tax.default_enabled is already false, both values leave settings alone. When it is true:
tax_default_behavior | What happens to tax.default_enabled | New orders, checkout sessions, and subscription renewals that inherit tax |
|---|---|---|
turn_off | Set to false. | Created without tax. Subscription renewals bill with no tax until you turn tax back on. |
keep | Stays true. | Refused with 409 ACTION_NOT_ALLOWED and reason configuration_required until you reconnect, set tax on each order yourself, or turn the default off. Subscription renewals are held and retried; the buyer isn't charged and dunning doesn't start. |
Choose turn_off to keep selling without tax. Choose keep when orders should wait for automatic tax to come back instead of going out untaxed.
What disconnecting does#
- The connection reads
statusnot_connectedwithstatus_reasondisconnected.supported_actionslistsconnectonce nothing else blocks it.versionadvances and Flint sendstax_connection.updated. - Open orders that use automatic tax, have calculated tax, and have no issued invoice become tax
incomplete. Fix them by turning tax off on the order, switching it to external tax, or reconnecting and updating the order. - Invoices with issued tax still collect. Their frozen tax doesn't change.
- Payments in flight for orders with automatic tax are refused, because those orders no longer have calculated tax.
- Payment links and checkout sessions that turn tax on explicitly with
tax.enabled: trueare refused when the checkout session is created, with either value oftax_default_behavior. - Registrations stay as they are, and the seller's tax account isn't closed, so you can reconnect later. While disconnected, registration writes are saved in Flint only.
Which states allow it#
| Connection | Result |
|---|---|
active | Disconnects. |
attention_required with setup_incomplete or registration_rejected | Disconnects. |
not_connected, including after a disconnect | 409 ACTION_NOT_ALLOWED with reason already_applied, or not_offered when automatic tax isn't offered for this account or sandbox. |
provisioning | 409 OPERATION_IN_PROGRESS. Retry after Retry-After. |
attention_required with business_details_changed or support_required | 409 ACTION_NOT_ALLOWED with reason reconciliation_required. Flint support has to act. |
disabled | 409 ACTION_NOT_ALLOWED with reason unsupported_state. |
When Flint has paused automatic tax for every merchant, the request returns 503 SERVICE_UNAVAILABLE. If another settings write is running, it returns 409 CONCURRENT_MODIFICATION; retry with the same Idempotency-Key.
Response#
The response is a DisconnectTaxConnectionResult with two members: tax_connection, the connection after the change, and settings, the merchant settings as GET /v1/settings returns them. Read settings.tax.default_enabled to see whether the request turned the default off.
curl -X POST https://api.withflintpay.com/v1/tax-connection/disconnect \
-H "Authorization: Bearer $FLINT_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: disconnect-tax-cedar-and-stone" \
-d '{
"tax_default_behavior": "turn_off",
"expected_version": 1793555700
}'
The example shows only some sections of settings.
{
"data": {
"tax_connection": {
"tax_connection_id": "tcn_01KYB4W8M2R6T9XQ3N5HPZ7C0D",
"status": "not_connected",
"status_reason": "disconnected",
"supported_actions": ["connect"],
"business_name": "Cedar & Stone LLC",
"business_address": {
"line1": "200 Spectrum Center Drive",
"city": "Irvine",
"state": "CA",
"postal_code": "92618",
"country": "US"
},
"disclosure": {
"version": "2026-10-26.5f3a9c1e",
"statements": [
{"text": "I confirm this Flint merchant represents one independently liable legal seller and taxpayer. It does not share registrations with another seller, switch sellers by transaction, or use Flint as Merchant of Record."},
{"text": "I authorize Flint to create and configure a Quaderno account for automatic tax calculations. Flint does not file returns or remit tax through this connection."},
{"text": "Automatic tax costs 0.50% of each payment where Flint calculates tax above zero. Payments with tax you supply, or with no tax, have no automatic tax fee."}
]
},
"seller_attestation": {
"disclosure_version": "2026-10-26.5f3a9c1e",
"attested_at": "2026-11-01T16:42:09Z"
},
"version": 1793556600,
"created_at": "2026-11-01T16:30:41Z",
"updated_at": "2026-11-01T18:10:00Z"
},
"settings": {
"settings_id": "set_01KEZF7C00J81795CYBW13GTQH",
"merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
"tax": {
"default_enabled": false,
"default_line_item_tax_category": "physical_goods"
},
"version": 4,
"created_at": "2026-03-17T14:30:00Z",
"updated_at": "2026-11-01T18:10:00Z"
}
}
}
Turn automatic tax back on#
Reconnect with POST /v1/tax-connection/connect and a new seller_attestation. Read GET /v1/tax-connection first: the disclosure may have changed, and status_reason says whether anything else blocks connecting. Connect checks the business details, syncs the registrations again, and returns active. It doesn't turn tax.default_enabled back on.
If the response is lost, read GET /v1/tax-connection. status: "not_connected" with status_reason: "disconnected" means the disconnect finished. If it still reads active, send the request again with the same Idempotency-Key; without a key, send the same body again. The settings change may already have happened, which is safe: orders that inherit tax are then created without it, as turn_off asks.
Read the connection#
curl https://api.withflintpay.com/v1/tax-connection \
-H "Authorization: Bearer $FLINT_SECRET_KEY"
This example is a sandbox that has one saved registration and hasn't connected. The connection record exists because the registration created it. Before any registration or connect, tax_connection_id, version, created_at, and updated_at are absent and status_reason is registration_required.
{
"data": {
"tax_connection_id": "tcn_01KYB4W8M2R6T9XQ3N5HPZ7C0D",
"status": "not_connected",
"status_reason": null,
"supported_actions": ["connect"],
"business_name": "Cedar & Stone LLC",
"business_address": {
"line1": "200 Spectrum Center Drive",
"city": "Irvine",
"state": "CA",
"postal_code": "92618",
"country": "US"
},
"disclosure": {
"version": "2026-10-26.5f3a9c1e",
"statements": [
{"text": "I confirm this Flint merchant represents one independently liable legal seller and taxpayer. It does not share registrations with another seller, switch sellers by transaction, or use Flint as Merchant of Record."},
{"text": "I authorize Flint to create and configure a Quaderno account for automatic tax calculations. Flint does not file returns or remit tax through this connection."},
{"text": "Automatic tax costs 0.50% of each payment where Flint calculates tax above zero. Payments with tax you supply, or with no tax, have no automatic tax fee."}
]
},
"seller_attestation": null,
"version": 1793550641,
"created_at": "2026-11-01T16:30:41Z",
"updated_at": "2026-11-01T16:30:41Z"
}
}
Registrations and an active connection#
While the connection isn't active, registration writes are saved in Flint only, as pending, and never create the billed tax account. Connect is the one route that completes setup. Once the connection is active, creating a registration syncs it in the request. See Tax registrations for the rules.
Webhook#
tax_connection.updated sends the connection, the same object GET /v1/tax-connection returns. It fires on every committed change to the connection or its registrations: when the record starts, on every registration create, edit, delete, or sync, when a connect finishes or fails, when a disconnect finishes, and when Flint support disables the connection. Compare version with the connection you stored and keep the higher one. The read-time states business_details_changed and temporarily_unavailable send nothing. A registration's status changing because a start or end date passed sends nothing either. Registrations have no events of their own: list them again after this event.
Errors#
- StatusHTTP 400CodeINVALID_
REQUEST What to doREQUIRED:seller_attestationorseller_attestation.disclosure_versionis missing on connect, ortax_default_behavioris missing on disconnect.paramnames the field. - StatusHTTP 409What to doBranch on
details[0].reason.disclosure_changed: the disclosure changed since you read it;details[0].current_disclosure_versionis the current version. Show the seller the current statements, get their agreement, and send that version.not_offered: automatic tax isn't offered for this account or sandbox.configuration_required: the connection has no registration that hasn't ended.already_applied: connect found the connection alreadyactive, or disconnect found it alreadynot_connected.reconciliation_required: the status reason isbusiness_details_changedorsupport_required, and Flint support must act.unsupported_state: the connection isdisabled, andsupported_actionsis[].details[0].resource_typeistax_connection, andcurrent_statusis present when the reason depends on status. - StatusHTTP 409What to do
expected_versionis stale.details[0].current_versionis the connection's currentversion. - StatusHTTP 409What to do
onboarding_required: the merchant has no verified business details.tax_category_required:tax.default_line_item_tax_categoryisn't a supported category. - StatusHTTP 409What to doA connect is running now. Retry with the same
Idempotency-KeyafterRetry-After. - StatusHTTP 409What to doDisconnect lost a race with another settings write. Retry the same request with the same
Idempotency-Key. - StatusHTTP 502What to doThe tax service was unreachable, or the outcome is unknown. Retry the same request with the same
Idempotency-Key. - StatusHTTP 504What to doThe tax service didn't respond in time, so the outcome is unknown. Retry the same request with the same
Idempotency-Key. - StatusHTTP 503What to doAutomatic tax is paused for every merchant, so retry later. With reason
repair_required, Flint couldn't confirm the tax account was created: the connection readssupport_required, and retrying doesn't help. Contact Flint support with therequest_id.
Get the automatic tax connection#
/v1/tax-connectionRequires scope settings.read or settings.write
Rate limit: read
Returns the environment's automatic sales tax connection, including before a record exists. Read the disclosure and status_reason to learn what connect needs. Business-detail changes, temporary provider pauses and registration date boundaries are computed at read time and do not advance version or send webhooks.
Response · 200
The automatic tax resource.
dataobjectRequiredResource, collection, or operation result returned by this request.
business_addressobjectVerified business address that connect will use as the tax origin, or the address copied to the connected account.
business_namestringVerified legal business name that connect will use, or the name copied to the connected account.
created_atstringWhen the connection record was created.
disclosureobjectRequiredCurrent statements the seller must agree to before connecting.
seller_attestationobject or nullRequiredThe seller's recorded agreement to the disclosure. `null` when no connect has recorded one.
statusenumRequiredWhether automatic tax is connected and can calculate tax.
not_connectedprovisioningactiveattention_requireddisabled
status_reasonenum or nullRequiredMachine-readable detail for `not_connected` or `attention_required`. `null` when no reason applies. Unknown reasons normalize to `other`.
not_offeredonboarding_requiredtax_category_requiredregistration_requiredtemporarily_unavailablesetup_incompleteregistration_rejectedbusiness_details_changedsupport_requireddisconnectedothernull
supported_actionsarray of enumRequiredLists connect when setup can complete and disconnect when automatic tax can be turned off, based on the connection state for every credential. An empty array means neither action is available. Performing either action requires settings.write.
connectdisconnect
tax_connection_idstringFlint tax connection ID. Present once the first registration or connection creates a record.
updated_atstringWhen the connection record's public state last changed.
versionintegerCurrent resource version. Send as expected_version to reject a write based on an older version.
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 https://api.withflintpay.com/v1/tax-connection \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The automatic tax resource.
{
"data": {
"business_address": {
"city": "Austin",
"country": "US",
"line1": "123 Main St",
"postal_code": "78701",
"state": "TX"
},
"business_name": "Example Shop LLC",
"created_at": "2026-10-26T12:00:00Z",
"disclosure": {
"statements": [
{
"text": "I confirm this Flint merchant represents one independently liable legal seller and taxpayer. It does not share registrations with another seller, switch sellers by transaction, or use Flint as Merchant of Record."
},
{
"text": "I authorize Flint to create and configure a Quaderno account for automatic tax calculations. Flint does not file returns or remit tax through this connection."
},
{
"text": "Automatic tax costs 0.5% of each payment where Flint calculates tax above zero. Payments with tax you supply, or with no tax, have no automatic tax fee."
}
],
"version": "2026-11-01.5f3a9c1e"
},
"seller_attestation": {
"attested_at": "2026-10-26T12:00:00Z",
"disclosure_version": "2026-11-01.5f3a9c1e"
},
"status": "active",
"status_reason": null,
"supported_actions": [
"disconnect"
],
"tax_connection_id": "tcn_01J00000000000000000000000",
"updated_at": "2026-10-26T12:00:00Z",
"version": 1793016000
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Connect automatic tax#
/v1/tax-connection/connectIdempotentRequires scope settings.write
Rate limit: external_provider_action
Records the seller's attestation and creates or completes the tax account from verified business details and the default line-item tax category in settings. Syncs registrations and removes tax-account copies of deleted registrations. Reconnect retains the tax account and does not turn the default tax setting back on. A rejected stored registration returns attention_required with registration_rejected. Successful configuration marks open calculated automatic-tax orders without an issued invoice incomplete and advances their versions. A same-key retry resumes setup without creating another account; unconfirmed account creation requires support. Retrieve the connection after a lost response.
Request body
expected_versionintegerResource version last read by the caller. Omit to apply the change to the current resource.
seller_attestationobjectRequiredPresence records the seller's agreement to the named disclosure version.
disclosure_versionstringRequiredCurrent disclosure version from GET /v1/tax-connection. Send only after the seller agrees to every rendered statement.
curl -X POST https://api.withflintpay.com/v1/tax-connection/connect \
-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": 1793016000,
"seller_attestation": {
"disclosure_version": "2026-11-01.5f3a9c1e"
}
}'Disconnect automatic tax#
/v1/tax-connection/disconnectIdempotentRequires scope settings.write
Rate limit: sensitive_write
Turns automatic tax off while retaining the tax account and registrations for reconnecting. Choose tax_default_behavior explicitly: turn_off stops adding tax to new orders, checkout sessions and renewals that inherit the default; keep leaves the default unchanged, refuses those orders and holds renewals for retry without charging buyers or starting dunning. Payment links that explicitly enable automatic tax are refused when creating a checkout session with either choice. Settings are updated first when needed, then the connection is disconnected and open calculated automatic-tax orders without an issued invoice snapshot become incomplete. Issued invoice snapshots are unchanged. A same-key retry resumes after settings were changed; after a lost response, retrieve the connection and disconnect again if needed.
Request body
expected_versionintegerResource version last read by the caller. Omit to apply the change to the current resource.
tax_default_behaviorenumRequiredChoose turn_off to stop adding tax to new orders that inherit the default, or keep to leave the default unchanged. Keep refuses those orders and holds subscription renewals until automatic tax is reconnected or the default is turned off. Neither choice turns tax on.
turn_offkeep
Response · 200
The automatic tax resource.
dataobjectRequiredResource, collection, or operation result returned by this request.
settingsobjectRequiredMerchant settings, as returned by GET /v1/settings.
tax_connectionobjectRequiredThe connection changed by this operation. Its version is the expected_version target.
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-connection/disconnect \
-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": 1793016000,
"tax_default_behavior": "turn_off"
}'Was this helpful?
