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-12
Connects a Fulfil company with POST /connections/fulfil/connectConnections
POST /connections/fulfil/connect validates a Fulfil merchant (a subdomain, or a fulfil.io host) and a personal access token in apiKey, then stores one connection for the company in companyId and returns it. companyName sets the display label and defaults to the name in the company list. historicalSyncStartDate sets how far back a new connection imports, as YYYY-MM-DD; it is ignored on reconnect, and null uses the Fulfil default of January 1, seven years back. Sending the same merchant and company id again updates the stored token instead of creating a second connection. The endpoint answers 400 when the merchant, token or company is rejected, and 503 when Fulfil cannot be reached. apiKey is limited to 512 characters and is never returned.
- List companies with
POST /connections/fulfil/companies, then send the chosencompanyIdhere. - Never store or log
apiKey, and on503wait and send the request again.
2026-11-11
Breaking changesTurns off Saleor tax collection when you delete or disable a Saleor connectionConnectionsBreaking change
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.
- DELETE/connections/{conn_id}2026-07-21
- DELETE/connections/{conn_id}2026-10-06
- POST/connections/{conn_id}/disable-tax-collection2026-07-21
- POST/connections/{conn_id}/disable-tax-collection2026-10-06
- POST/connections/vertex-o-series/{conn_id}/mark-installed2026-07-21
- POST/connections/vertex-o-series/{conn_id}/mark-installed2026-10-06
- On
503fromDELETE /connections/{conn_id}orPOST /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-installedfor a Saleor connection.
Checks Fulfil credentials and lists Fulfil companiesConnections
POST /connections/fulfil/validate checks a Fulfil merchant (a subdomain such as acme, or a fulfil.io host) and a personal access token in apiKey without saving anything, and returns the normalized merchant. POST /connections/fulfil/companies takes the same body and returns companies, each with id and name. The token travels in the request body because no connection exists yet, and apiKey is limited to 512 characters. Both answer 400 when the merchant is not a valid subdomain or host, or when Fulfil rejects the merchant or token, and the company list also answers 400 for a merchant with too many companies to list in one request. A missing, blank or malformed apiKey answers 422. 503 means Fulfil could not be reached or the service is busy; retry later.
- Call
POST /connections/fulfil/validateto confirm a merchant and token, thenPOST /connections/fulfil/companiesto list the companies the token can read. - Never store or log
apiKey, and on503wait and send the request again.
Adds FULFIL as a sourceConnections
FULFIL is a new value of source, in requests and responses wherever a connection, customer, product, transaction or marketplace reports its source.
- Accept
FULFILwherever your code switches onsource, including strict enums in generated clients.
2026-11-05
Breaking changesAnswers 409 when you delete or disconnect a connection that has filed historyConnectionsBreaking change
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.
- Handle
409withcodeconnection_has_filed_historyfrom both endpoints, and do not retry it. - Branch on
codewhen you handle409fromPOST /connections/quickbooks/disconnect, since it also answers409for an ambiguousrealmId. - Show the user that the connection cannot be removed and point them to Kintsugi support.
2026-10-29
Breaking changesMatches an existing ERP connection when activating an Apideck connectionConnectionsBreaking change
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.
- Handle
409from this endpoint by keeping the existing connection and disconnecting the one you do not need withDELETE /connections/{connId}. - Send
netsuiteAccountId,netsuiteSubsidiaryIdordualentryCompanyIdon this call, not in an earlier settings update, so they land on the connection that stays.
Enables tax collection on a Zoho Books connectionConnections
POST /connections/zoho-books/{conn_id}/enable-tax enables tax calculation on a Zoho Books connection and returns the connection. A Zoho Books connection cannot enable tax collection any other way. When the connection is already enabled and configured, it returns the connection unchanged. It answers 400 when the connection is not ready for tax calculation, has opted out of tax collection, or was connected without the Zoho Books permissions tax calculation needs (reconnect it to grant them), 404 when the connection does not exist, is not a Zoho Books connection, or belongs to an organization your credential cannot access, and 503 when setup with Zoho Books fails; retrying may succeed. A credential that spans several organizations must send an Organization-Id, Connection-Id or Entity-Id header, or gets 400. The optional body takes viaL2Checklist and requestId.
- Call this endpoint, not
POST /connections/{conn_id}/enable-tax-collection, to turn on tax collection for a Zoho Books connection.
Chooses where a Frisbii import starts with historicalSyncStartDateConnections
POST /connections/frisbii-billing/connect accepts historicalSyncStartDate (YYYY-MM-DD), the earliest date from which invoices and credit notes are imported. It applies to a new connection and is ignored when you reconnect. Leave it out or send null to import all available history. A date in the future answers 422.
- Send
historicalSyncStartDatewhen you connect a new Frisbii account and want to import only recent history.
2026-10-28
Connects a Saleor channel with POST /connections/saleor/connectConnections
POST /connections/saleor/validate checks a Saleor app token in appToken against the graphqlUrl you send, without saving anything, and returns saleorVersion and the store's channels, each with slug, name, currencyCode, pricesEnteredWithTax and isActive. A bare host in graphqlUrl gets /graphql/ added. POST /connections/saleor/connect stores a connection for the one channel named in channelSlug, returns it, and queues a sync. Sending the same store and channel again updates the stored token and reactivates the connection instead of creating a second one. Both endpoints answer 400 when the URL is not allowed or is not a Saleor GraphQL API, Saleor rejects the token, the store has no channel, or (on connect) the channel is not on the store. 503 means Saleor could not be reached or was busy; retry later. The endpoints are available to organizations with this feature enabled; others receive 404.
- Call
POST /connections/saleor/validateto list the channels, thenPOST /connections/saleor/connectwith the same token and theslugof the channel to import.
2026-10-27
Reports netsuiteCurrencyJoinEnabled on connectionsConnections
A connection now returns netsuiteCurrencyJoinEnabled. For a NetSuite connection it is true when transaction sync reads currency codes from the NetSuite currency record, and false for accounts without Multi-Currency or Currency View; it is true unless that was turned off. It is null for every other connection.
2026-10-26
Connects a Frisbii account with POST /connections/frisbii-billing/connectConnections
POST /connections/frisbii-billing/connect checks the Frisbii private API key in apiKey, stores that account as a connection with source FRISBII_BILLING, and returns the connection. One key is one account. Sending the same account again updates the stored key instead of creating a second connection, and queues a sync. A blank key, a key Frisbii rejects, any other client error from Frisbii, or an account that cannot be read answers 400. 503 means Frisbii could not be reached or answered 429 or 5xx; retry later. The endpoint is available to organizations with this feature enabled; others receive 404.
- Call
POST /connections/frisbii-billing/validateto show the account, thenPOST /connections/frisbii-billing/connectwith the same key to save it.
2026-10-21
Checks a Frisbii private API key with POST /connections/frisbii-billing/validateConnections
POST /connections/frisbii-billing/validate reads the Frisbii account behind the private API key in apiKey and returns its handle, name and currency, so you can show the account to the user before connecting. Nothing is saved. One key is one account. A blank key, a key Frisbii rejects, any other client error from Frisbii, or an account that cannot be read answers 400. 503 means Frisbii could not be reached or answered 429 or 5xx; retry later. The endpoint is available to organizations with this feature enabled; others receive 404.
- Call
POST /connections/frisbii-billing/validatewith the key before you save a Frisbii connection, and show the returnedname.
2026-10-15
Breaking changesReuses a Stripe connection's credentials on app connectConnections
POST /connections/stripe/app-connect accepts reuseFromConnectionId: the id of an active Stripe connection in another organization, for the same accountId and mode, whose credentials the new connection shares. Leave it out to connect through the Stripe App's OAuth session, as before. Reuse needs a signed-in Owner or Admin of the organization that holds the source connection, not an API key. Every refusal answers 404 with the error code stripe_reusable_connection_not_found, whether the id is unknown, belongs to an organization you cannot reach, or cannot be reused, so a client can fall back to a fresh install.
- Handle
stripe_reusable_connection_not_foundby connecting through the Stripe App's OAuth session instead.
Enables tax collection on a Hyperline connectionConnections
POST /connections/hyperline/{conn_id}/enable-tax enables tax calculation on a Hyperline connection and returns the connection. A Hyperline connection cannot enable tax collection any other way. When the connection is already enabled and configured, it returns the connection unchanged. It answers 400 when the connection is not ready for tax calculation, has opted out of tax collection, or Hyperline rejects the request, 404 when the connection does not exist, is not a Hyperline connection, or belongs to an organization your credential cannot access, and 503 when setup with Hyperline fails; retrying may succeed. A credential that spans several organizations must send an Organization-Id, Connection-Id or Entity-Id header, or gets 400. The optional body takes viaL2Checklist and requestId.
- Call this endpoint, not
POST /connections/{conn_id}/enable-tax-collection, to turn on tax collection for a Hyperline connection.
Opts a connection out of tax collectionConnections
POST /connections/{conn_id}/opt-out-tax-collection records that the customer chose not to enable tax collection on a connection, and returns the connection with taxCollectionOptedOutAt set. While the opt-out stands, enabling tax collection on the connection answers 400; Kintsugi support clears it. Opting out again returns the connection unchanged. It answers 400 when tax collection is already enabled or the connection's source does not support opting out, and 404 when the connection does not exist or belongs to an organization your credential cannot access. A credential that spans several organizations must send an Organization-Id, Connection-Id or Entity-Id header, or gets 400. The optional body takes requestId.
- Call this endpoint when a customer declines tax collection, and expect
400from enable calls until the opt-out is cleared.
Accepts an optional body when enabling or disabling tax collectionConnections
The enable and disable tax collection endpoints accept an optional JSON body, and a request without one behaves as before. requestId is a client-generated id of up to 64 letters, numbers, hyphens or underscores that tells repeated attempts apart. On the enable endpoints, viaL2Checklist defaults to false; when true, the connection's readiness is checked from live data and saved, instead of requiring it to be saved already.
- POST/connections/{conn_id}/enable-tax-collection2026-07-21
- POST/connections/{conn_id}/enable-tax-collection2026-10-06
- POST/connections/{conn_id}/disable-tax-collection2026-07-21
- POST/connections/{conn_id}/disable-tax-collection2026-10-06
- POST/connections/bill-com/{conn_id}/enable-tax2026-07-21
- POST/connections/bill-com/{conn_id}/enable-tax2026-10-06
- POST/connections/freshbooks/{conn_id}/enable-tax2026-07-21
- POST/connections/freshbooks/{conn_id}/enable-tax2026-10-06
Requires a Shopware Admin link to connect ShopwareConnectionsBreaking change
POST /connections/apideck/{service_id}/connect with shopware now answers 400 unless the connection was first started from a link opened in Shopware Admin. A call made without that link, which succeeded before, is rejected. Other services are unchanged. This applies to every Api-Version.
- Start a Shopware connection from Kintsugi in Shopware Admin instead of calling
connectdirectly.
2026-10-14
Breaking changesRefreshes a Bunny connection with POST on 2026-10-06 and rejects a null nameConnectionsBreaking change
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.
- On
Api-Version: 2026-10-06, callPOSTinstead ofPATCHto refresh the connection. - Leave out
nameto keep the current name, and do not send it asnull.
Clears connection settings with null and rejects an empty idConnectionsBreaking change
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.
- Send
null, not an empty string, to cleardualentryCompanyId,netsuiteAccountIdornetsuiteSubsidiaryId. - Leave out
needsUpdate,isOneworldAccountandnetsuiteSyncModewhen they should not change.
Updates Zuora tax setup one field at a timeConnections
PATCH /connections/zuora/{conn_id}/tax-setup no longer requires tenantId and zuoraVertexTaxEngineId. Send only the fields to change: an omitted field is left unchanged, and zuoraVertexTaxCompanyId: null clears the company id. null on tenantId or zuoraVertexTaxEngineId answers 422, and an empty value for either still answers 400. Both ids are saved without leading or trailing spaces. Webhook notifications are registered only when tenantId or zuoraVertexTaxEngineId changes, instead of on every call; a retry with the same ids registers them again if the earlier attempt failed. This applies to every Api-Version.
- Send only the ids you are changing, and
zuoraVertexTaxCompanyId: nullto remove the company id.
Adds ZOHO_BOOKS as a source valueConnections
source can now be ZOHO_BOOKS, which a Zoho Books connection and the products that sync from it report. The value appears wherever source is returned or accepted, including connections, customers, products, transactions and marketplaces.
- If your client checks
sourceagainst a fixed list, addZOHO_BOOKS.
2026-10-06
Lists active connections first by defaultConnections
When you leave out sort, GET /connections now lists ACTIVE connections first, then INACTIVE, then CONNECTION_ERROR, with the most recently updated first within each status. Before, it listed connections in id order. An explicit sort and order work as before. A cursor issued without sort before this change answers 400 with code stale_cursor.
- If your integration depends on
idorder, send asortinstead. - On
stale_cursor, start again from the first page without a cursor.
Narrows the connections list to one organization on requestConnections
GET /connections now honors the Organization-Id, Connection-Id and Entity-Id headers, with Entity-Source to disambiguate an Entity-Id, and lists only that organization's connections. Before, these headers were ignored and the list always covered every organization your credential can access, which is still what you get without them. An organization outside your access answers 404. A cursor works only with the selector it came from: reusing it with another answers 400 with code stale_cursor.
- Stop sending a selector header to
GET /connectionsif you expect every organization's connections. - Send
Organization-Idto list one organization's connections without filtering them yourself.
Returns each connection's first and latest transaction datesConnections
Connections from GET /connections and GET /connections/{conn_id} now include minDate and maxDate: the dates, as YYYY-MM-DD, of the earliest and latest transaction that GET /transactions returns for the connection. Both are null for a connection with no transactions. Other endpoints that return a connection, such as connect, activate and deactivate, return null for both.
Finds the organizations connected to a Shopify storeConnections
GET /connections/shopify/organizations takes a shopId, the store name such as mystore or the full mystore.myshopify.com, matched without regard to letter case. It returns one { organizationId } per organization you can access that has an ACTIVE connection to the store, ordered by organizationId, and an empty list when none does, including for a blank shopId. Inactive and failed connections are left out. It searches every organization your credential can access, or one when you send Organization-Id, Connection-Id or Entity-Id; an organization outside your access answers 404.
- Call it after a store connects to find which of your organizations it belongs to.
2026-10-05
Breaking changesReturns already_connected when an activated store is already connectedConnectionsBreaking change
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.
- Treat
400with codealready_connectedas success, and list your connections again to find the one that remains. - Stop relying on
invalid_requestto detect an already connected store. - If your client accepts only known
codevalues, addalready_connected.
Accepts NetSuite and DualEntry identifiers when activating a connectionConnections
POST /connections/apideck/{conn_id}/activate accepts three optional fields: netsuiteAccountId and netsuiteSubsidiaryId for a NetSuite connection, and dualentryCompanyId for a DualEntry connection. They are saved in the same step to the connection that remains active, which is your existing connection when the shopId matches one. A field you leave out keeps its saved value, and null or an empty string for dualentryCompanyId covers every company. Other sources ignore these fields.
- Send these identifiers with the activate call, so they are saved on the connection that remains.
Deletes a connection that was never finishedConnections
DELETE /connections/apideck/{conn_id} cleans up a connection left behind when the connect flow was cancelled or failed before activation, and answers 204. It removes only a connection with status INACTIVE or CONNECTION_ERROR that holds no data, and the removal is permanent. An active connection, or one that already holds data such as transactions, is kept and the call answers 409 with code conflict, so it is safe to call even when you did not see how an activation ended. A connection that does not exist or is not yours answers 404, as does a repeat call after a successful delete. A credential for more than one organization must name one with Organization-Id, Connection-Id or Entity-Id, or receives 400.
- After a cancelled or failed connect flow, call this endpoint, and keep the connection when it answers
409.
Releases
2026-10-06
LatestTenanted APIConsistent 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
| Change | Applies to | 2026-07-21 | 2026-10-06 |
|---|---|---|---|
| Country code field | Addresses, customers, transactions, tax estimates and billing usage, in requests and responses | country | countryCode. Query parameters named country keep their name. |
| Batch address update method | /addresses/transactions | PUT | PATCH. The other method returns 405. |
| Omitted fields in a batch address update | PATCH /addresses/transactions | A field you leave out is cleared | Kept. null clears a text field, and isUnincorporated: null or an unknown countryCode returns 422. |
| Address revalidation method | /addresses/revalidation | PUT | POST. The other method returns 405. |
| Registration credentials method | /registrations/{registration_id}/credentials | PUT, where null leaves a credential unchanged | PATCH, where null clears a credential. The other method returns 405. |
| Filing submission methods | /filings/{filing_id}/submission | PUT with action | PATCH saves a draft and POST /filings/{filing_id}/mark-filed marks it filed. PUT returns 405. |
| Bunny connection refresh method | /connections/bunny/{conn_id}/refresh | PATCH | POST. The other method returns 405. |
| Default country field on connections | Connections, connection settings, PATCH /connections/{conn_id}/settings and POST /connections/apideck/{service_id}/connect | defaultCountry | defaultCountryCode |
| Incorporation country field | GET /organization-details and PATCH /organization-details | incorporationCountry | incorporationCountryCode |
| State on nexus exposure events | GET /nexus/{nexus_id}/exposure-history | state | stateCode, always present |
| State of a country-level filing | stateCode and stateName on every filing | Empty string | null |
| Organization state and country when not set | state and countryCode on organizations, and state in organization lists | Empty string, always present | null, and may be omitted |
| Exemption with no match on a certificate upload | exemptionId on missing-certificate upload results | Empty string | null |
| Missing-certificate status values | Upload, upload status and public confirm-upload results | Lowercase: processing, satisfied, rejected | Uppercase: PROCESSING, SATISFIED, REJECTED, plus PENDING on the public landing page |
| Exemption type when approving certificate imports | POST /certificate-imports/{certificate_import_id}/approve and POST /certificate-imports/bulk-approve | Any text, defaulting to customer | CUSTOMER, WHOLESALE, TRANSACTION or REVERSE_CHARGE, defaulting to CUSTOMER. Any other value returns 422. |
| Security questions in a credential reveal | fields on POST /registrations/{registration_id}/credentials/reveal | security_questions | securityQuestions |
| Line item with no product name | productName on transaction lines | null | Empty string |
| Help article label on back-filing options | GET /filings/backFilingRequest/options | Text or null | Always text |
| Job ID on bulk filing results | POST /filings/bulk/approve and POST /filings/bulk/pause | jobId, always null | Removed |
Moving an integration from 2026-07-21
- Send
Api-Version: 2026-10-06with each request you move. Requests without it keep running against 2026-07-21. - Rename
countrytocountryCodewherever you send or read an address, customer, transaction or tax estimate, and renamedefaultCountryandincorporationCountrytodefaultCountryCodeandincorporationCountryCode. - Call
PATCH /addresses/transactionsfor batch address updates, sendingnullfor any text field you want cleared, andPOST /addresses/revalidationto re-queue invalid addresses. - Treat
nullas "not set" for filing and organization locations and for an unmatchedexemptionId, and an emptyproductNameas "no product name". - Compare missing-certificate statuses in uppercase, and send
exemptionTypein uppercase when you approve certificate imports. - Read
stateCodeon nexus exposure events, requestsecurityQuestionswhen you reveal registration credentials, and stop readingjobIdon bulk filing results. - Call
PATCHto save registration credentials,PATCHandPOST /filings/{filing_id}/mark-filedin place ofPUTfor a filing submission, andPOSTto refresh a Bunny connection.
2026-07-21
Tenanted APIIntroducing 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
| Topic | v1 | 2026-07-21 |
|---|---|---|
| Versioning | The /v1 path prefix | The Api-Version header, dated YYYY-MM-DD. Optional; without it, a request runs against the launch release |
| Paths | /v1/transactions | /transactions |
| Authentication | x-api-key | Api-Key. Endpoints that manage people accept a signed-in session token instead |
| Choosing an organization | x-organization-id, required on almost every request | One credential reaches every organization it owns. Narrow a request with Organization-Id, Connection-Id, or Entity-Id |
| Field names | snake_case | camelCase |
| Money and rates | Decimal strings out, numbers or strings in | Decimal strings at a fixed scale: amounts to 2 places, rates to 9 |
| Timestamps | No single documented format | RFC 3339 in UTC, always ending in Z |
| Errors | Shapes vary by endpoint | One envelope everywhere: code, message, requestId, and errors |
| Portfolio | Not available | Portfolio and Portfolio Reseller endpoints, for partner accounts |
Moving an integration from v1
- Send
Api-Versionwith every request, pinned to the release you build against (the newest is2026-10-06), so your integration stays on it until you decide to move. - Drop
/v1from your paths. - Send your key as
Api-Key, and replacex-organization-idwithOrganization-Idwherever you target one organization. - Rename fields to camelCase, and read every amount as a decimal string, never a float.
- Branch on the error
code, not the message or the HTTP status, and quoterequestIdwhen 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
LegacyThe 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.