KintsugiKintsugi
API reference / Changelog

API changelog

Every change to the Kintsugi API and every release, newest first. Breaking changes carry the Breaking change mark. Tenanted releases are dated, and you choose one with the Api-Version header.

Changes

2026-11-11

Breaking changes
Turns off Saleor tax collection when you delete or disable a Saleor connectionBreaking change
Breaking changeConnections

DELETE /connections/{conn_id} on a Saleor connection now turns its tax collection off before archiving it. If the store still has Kintsugi's tax setup afterwards, the connection is not archived and the request answers 503; retrying may succeed. POST /connections/{conn_id}/disable-tax-collection on a Saleor connection that is already disabled retries any tax setup an earlier disable left behind, and answers 503, leaving tax collection enabled, while another tax change for the same store is running. A Saleor outage during that cleanup does not fail the request, so call disable again to retry it. POST /connections/vertex-o-series/{conn_id}/mark-installed answers 400 for a Saleor connection, because Saleor tax collection is turned on from the connection's own tax setting.

What to do
  • On 503 from DELETE /connections/{conn_id} or POST /connections/{conn_id}/disable-tax-collection, wait a moment and send the same request again.
  • Do not call POST /connections/vertex-o-series/{conn_id}/mark-installed for a Saleor connection.

2026-11-05

Breaking changes
Answers 409 when you delete or disconnect a connection that has filed historyBreaking change
Breaking changeConnections

DELETE /connections/{conn_id} and POST /connections/quickbooks/disconnect now refuse to archive a connection that owns filed tax history, and answer 409 with the error code connection_has_filed_history, a new value of the error code enum. Before, both archived the connection. The connection is left unchanged, and sending the request again returns the same 409. POST /connections/quickbooks/disconnect already answers 409 when realmId matches more than one connection, so read code to tell the two apart.

What to do
  • Handle 409 with code connection_has_filed_history from both endpoints, and do not retry it.
  • Branch on code when you handle 409 from POST /connections/quickbooks/disconnect, since it also answers 409 for an ambiguous realmId.
  • Show the user that the connection cannot be removed and point them to Kintsugi support.

2026-10-29

Breaking changes
Matches an existing ERP connection when activating an Apideck connectionBreaking change
Breaking changeConnections

POST /connections/apideck/{conn_id}/activate now finds an existing live connection for the same ERP account, not only by shopId: the NetSuite subsidiary, the DualEntry company, or the QuickBooks, Xero or Dynamics 365 entity. When this connection holds no data, the existing one is reactivated and this one is deleted, and the call answers 400 with code already_connected. When only the existing connection is empty, it is removed and this one is activated. When both hold data, the call answers 409 and both connections stay. A 409 was not possible on this endpoint for these sources before.

What to do
  • Handle 409 from this endpoint by keeping the existing connection and disconnecting the one you do not need with DELETE /connections/{connId}.
  • Send netsuiteAccountId, netsuiteSubsidiaryId or dualentryCompanyId on this call, not in an earlier settings update, so they land on the connection that stays.

2026-10-15

Breaking changes

2026-10-14

Breaking changes
Refreshes a Bunny connection with POST on 2026-10-06 and rejects a null nameBreaking change
Breaking changeConnections

On Api-Version: 2026-10-06, POST /connections/bunny/{conn_id}/refresh replaces PATCH, which now answers 405. The request body is unchanged. 2026-07-21 keeps PATCH. On every Api-Version, name is written as sent, including an empty string, and is left unchanged when omitted. Sending name as null now answers 422.

What to do
  • On Api-Version: 2026-10-06, call POST instead of PATCH to refresh the connection.
  • Leave out name to keep the current name, and do not send it as null.
Clears connection settings with null and rejects an empty idBreaking change
Breaking changeConnections

PATCH /connections/{conn_id}/settings now clears a nullable field when you send it as null; before, null was ignored and no field could be cleared. That covers airwallexHistoricalSyncStartDate, woocommerceHistoricalSyncStartDate, netsuiteHistoricalSyncStartDate, microsoftD365HistoricalSyncStartDate, amazonHistoricalSyncStartDate, apideckConnectionState, dualentryCompanyId, netsuiteAccountId and netsuiteSubsidiaryId. null on needsUpdate, isOneworldAccount or netsuiteSyncMode answers 422; before, it answered 200 and changed nothing. An empty string for dualentryCompanyId, netsuiteAccountId or netsuiteSubsidiaryId now answers 422; before, it cleared the value, so send null instead. This applies to every Api-Version.

What to do
  • Send null, not an empty string, to clear dualentryCompanyId, netsuiteAccountId or netsuiteSubsidiaryId.
  • Leave out needsUpdate, isOneworldAccount and netsuiteSyncMode when they should not change.

2026-10-05

Breaking changes
Returns already_connected when an activated store is already connectedBreaking change
Breaking changeConnections

When POST /connections/apideck/{conn_id}/activate finds that the shopId belongs to a connection your organization already has, it reactivates that existing connection, removes the one being activated, and answers 400 as before. The error code is now already_connected instead of invalid_request, with the message This store is already connected. The existing connection was reactivated. The store is connected and nothing more is needed. already_connected is a new value of the code field in error responses.

What to do
  • Treat 400 with code already_connected as success, and list your connections again to find the one that remains.
  • Stop relying on invalid_request to detect an already connected store.
  • If your client accepts only known code values, add already_connected.

Releases

2026-10-06

LatestTenanted API

Consistent country codes, empty values and status casing

2026-10-06 makes the Tenanted API more predictable to build on. Every country code is now countryCode, a value that is not set is null rather than an empty string, and status and type values are uppercase throughout. Integrations pinned to 2026-07-21 are unaffected until you choose to move, and the table below lists everything that changes when you do.

Compared with 2026-07-21

ChangeApplies to2026-07-212026-10-06
Country code fieldAddresses, customers, transactions, tax estimates and billing usage, in requests and responsescountrycountryCode. Query parameters named country keep their name.
Batch address update method/addresses/transactionsPUTPATCH. The other method returns 405.
Omitted fields in a batch address updatePATCH /addresses/transactionsA field you leave out is clearedKept. null clears a text field, and isUnincorporated: null or an unknown countryCode returns 422.
Address revalidation method/addresses/revalidationPUTPOST. The other method returns 405.
Registration credentials method/registrations/{registration_id}/credentialsPUT, where null leaves a credential unchangedPATCH, where null clears a credential. The other method returns 405.
Filing submission methods/filings/{filing_id}/submissionPUT with actionPATCH saves a draft and POST /filings/{filing_id}/mark-filed marks it filed. PUT returns 405.
Bunny connection refresh method/connections/bunny/{conn_id}/refreshPATCHPOST. The other method returns 405.
Default country field on connectionsConnections, connection settings, PATCH /connections/{conn_id}/settings and POST /connections/apideck/{service_id}/connectdefaultCountrydefaultCountryCode
Incorporation country fieldGET /organization-details and PATCH /organization-detailsincorporationCountryincorporationCountryCode
State on nexus exposure eventsGET /nexus/{nexus_id}/exposure-historystatestateCode, always present
State of a country-level filingstateCode and stateName on every filingEmpty stringnull
Organization state and country when not setstate and countryCode on organizations, and state in organization listsEmpty string, always presentnull, and may be omitted
Exemption with no match on a certificate uploadexemptionId on missing-certificate upload resultsEmpty stringnull
Missing-certificate status valuesUpload, upload status and public confirm-upload resultsLowercase: processing, satisfied, rejectedUppercase: PROCESSING, SATISFIED, REJECTED, plus PENDING on the public landing page
Exemption type when approving certificate importsPOST /certificate-imports/{certificate_import_id}/approve and POST /certificate-imports/bulk-approveAny text, defaulting to customerCUSTOMER, WHOLESALE, TRANSACTION or REVERSE_CHARGE, defaulting to CUSTOMER. Any other value returns 422.
Security questions in a credential revealfields on POST /registrations/{registration_id}/credentials/revealsecurity_questionssecurityQuestions
Line item with no product nameproductName on transaction linesnullEmpty string
Help article label on back-filing optionsGET /filings/backFilingRequest/optionsText or nullAlways text
Job ID on bulk filing resultsPOST /filings/bulk/approve and POST /filings/bulk/pausejobId, always nullRemoved

Moving an integration from 2026-07-21

  1. Send Api-Version: 2026-10-06 with each request you move. Requests without it keep running against 2026-07-21.
  2. Rename country to countryCode wherever you send or read an address, customer, transaction or tax estimate, and rename defaultCountry and incorporationCountry to defaultCountryCode and incorporationCountryCode.
  3. Call PATCH /addresses/transactions for batch address updates, sending null for any text field you want cleared, and POST /addresses/revalidation to re-queue invalid addresses.
  4. Treat null as "not set" for filing and organization locations and for an unmatched exemptionId, and an empty productName as "no product name".
  5. Compare missing-certificate statuses in uppercase, and send exemptionType in uppercase when you approve certificate imports.
  6. Read stateCode on nexus exposure events, request securityQuestions when you reveal registration credentials, and stop reading jobId on bulk filing results.
  7. Call PATCH to save registration credentials, PATCH and POST /filings/{filing_id}/mark-filed in place of PUT for a filing submission, and POST to refresh a Bunny connection.

2026-07-21

Tenanted API

Introducing the Tenanted API

A fresh foundation for building on Kintsugi. The Tenanted API is versioned by date, and you choose the release you build against. It speaks one consistent dialect from end to end: clean paths, camelCase fields, exact decimal amounts, and a single error format. And it is built for scale, with one credential reaching every organization it owns.

Compared with v1

Topicv12026-07-21
VersioningThe /v1 path prefixThe Api-Version header, dated YYYY-MM-DD. Optional; without it, a request runs against the launch release
Paths/v1/transactions/transactions
Authenticationx-api-keyApi-Key. Endpoints that manage people accept a signed-in session token instead
Choosing an organizationx-organization-id, required on almost every requestOne credential reaches every organization it owns. Narrow a request with Organization-Id, Connection-Id, or Entity-Id
Field namessnake_casecamelCase
Money and ratesDecimal strings out, numbers or strings inDecimal strings at a fixed scale: amounts to 2 places, rates to 9
TimestampsNo single documented formatRFC 3339 in UTC, always ending in Z
ErrorsShapes vary by endpointOne envelope everywhere: code, message, requestId, and errors
PortfolioNot availablePortfolio and Portfolio Reseller endpoints, for partner accounts

Moving an integration from v1

  1. Send Api-Version with every request, pinned to the release you build against (the newest is 2026-10-06), so your integration stays on it until you decide to move.
  2. Drop /v1 from your paths.
  3. Send your key as Api-Key, and replace x-organization-id with Organization-Id wherever you target one organization.
  4. Rename fields to camelCase, and read every amount as a decimal string, never a float.
  5. Branch on the error code, not the message or the HTTP status, and quote requestId when you contact support.

Creating a transaction answers 202 Accepted straight away, and tax is calculated just after. Check processingStatus before you read the tax totals.

v1

Legacy

The original Kintsugi API, versioned in the path. It is documented exactly as before, so existing integrations can keep running with confidence. New integrations should start on the newest Tenanted API release.

Kintsugi API Changelog