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-16

Breaking changes
Removes sltr_elected and single_local_tax_rate from the Texas fields on POST /v1/registrationsBreaking change
Breaking changeRegistrations

The Texas jurisdiction_specific_fields on POST /v1/registrations no longer include sltr_elected or single_local_tax_rate. Requests that still send them succeed, and the values are ignored, so a Texas registration created on v1 does not elect the single local tax rate.

What to do
  • Stop sending sltr_elected and single_local_tax_rate for Texas registrations.
  • Remove both fields from request models generated from the earlier v1 spec.

2026-11-13

Breaking changes
Filters exemptions by date range with startDate and endDateBreaking change
Breaking changeExemptions

On GET /exemptions and GET /v1/exemptions, the date filters are now range bounds, where they used to match one exact date. startDate (start_date on v1) returns exemptions whose validity start date is on or after that date. endDate (end_date on v1) returns exemptions whose validity end date is on or before that date. Setting endDate leaves out open-ended exemptions, the ones with a null end date. Sending both gives the exemptions that start and end inside the range. A request that sent the same date in both filters to find exemptions starting or ending on that day now returns every exemption inside the range instead.

What to do
  • Review calls that send startDate or endDate (start_date or end_date on v1) and expect an exact-date match.
  • To find exemptions that end on one day, filter with endDate and discard rows whose end date is earlier.
  • Do not send endDate when you want open-ended exemptions in the results.

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-06

Breaking changes
Limits who can reveal or overwrite stored registration credentials on v1Breaking change
Breaking changeRegistrations

Using reveal on GET /v1/registrations/{registration_id}, and sending a value for or clearing a credential that is already stored on PUT /v1/registrations/{registration_id}, now need an Owner of the organization or a Kintsugi Portfolio user who can open it. An API key counts as the user it belongs to, and a service key as the user who created it. Any other caller, and any automated assistant integration, gets 403, even when the PUT sends the value that is already stored. Before, any caller who could read or edit the registration could do both. The credentials covered are the username, password, security questions and portal access codes. A caller who can edit the registration can still fill a credential that has no stored value, except that a stored password also protects the username and security questions. Without reveal, credential fields come back masked.

What to do
  • Handle 403 from GET /v1/registrations/{registration_id} when you send reveal, and from PUT /v1/registrations/{registration_id} when the body sets or clears a stored credential.
  • Use credentials that belong to an Owner of the organization, or a service key, for integrations that reveal or replace stored credentials.
  • Stop sending credential fields back unchanged on PUT /v1/registrations/{registration_id}, since that is refused when a value is stored.
Requires an Owner behind an organization API key that reads or changes registration credentialsBreaking change
Breaking changeRegistrations

POST /registrations/{registration_id}/credentials/reveal, PUT and PATCH /registrations/{registration_id}/credentials and POST /registrations/{registration_id}/send-password now accept an organization's own API key only while an Owner stands behind it: the user the key belongs to or, for a key with no user, the user who created it. Before, any key for the organization could. Other keys get 403. An Owner is checked against their current role, so an Owner who is demoted or removed loses access at once instead of when their sign-in token expires. When the role cannot be confirmed, the endpoints answer 503 with a Retry-After header.

What to do
  • Create the API keys that call these endpoints as an Owner of the organization, or use a service key created by an Owner.
  • Handle 403 from these endpoints for a key whose user is not an Owner.
  • On 503, wait for the Retry-After delay and send the request again.

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-11-02

Breaking changes
Answers 409 when you approve a filing that is being recalculatedBreaking change
Breaking changeFilings

Approving a filing now answers 409 while the filing is being recalculated, instead of approving it on amounts that may be out of date. On the Tenanted releases the error code is recalculation_in_progress, a new value of the error code enum. The recalculation finishes within moments, so the same request succeeds when you retry it.

What to do
  • Handle 409 on an approval by waiting a few seconds and sending the same request again.
  • On the Tenanted releases, tell this 409 apart from the duplicate-period 409 by its code, and treat an unknown code as a failure rather than a retry.

2026-10-29

Breaking changes
Validates US routing and account numbers on bank account writesBreaking change
Breaking changeOrganizations

POST /bank-details, PATCH /bank-details/{bank_details_id} and PATCH /bank-details now check a US routing number or account number you add or change. A routing number must be 9 digits with a valid checksum, and an account number 4 to 17 digits. Spaces and dashes are removed before the check, and the digits are stored. A value that fails answers 422 with the field named in errors; it was stored as sent before. A number identical to the one already stored is not checked again, so saving other fields does not fail on an older value.

What to do
  • Send a routing number of 9 digits that passes the ABA checksum, and an account number of 4 to 17 digits.
  • Handle a 422 from these endpoints by showing the message for the field named in errors.
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-28

Breaking changes
Sets the debit account with isPrimary on PATCH /bank-details/{bank_details_id}Breaking change
Breaking changeOrganizations

POST /bank-details/{bank_details_id}/set-primary is removed on every Tenanted release, including integrations pinned to 2026-07-21 or 2026-10-06. Send isPrimary: true on PATCH /bank-details/{bank_details_id} to make that account the organization's debit account, alone or together with field updates. false or omitted leaves the debit account unchanged. Unlike set-primary, this request accepts an API key as well as an Owner or Admin user credential. It still answers 404 when the organization has no account with that id. makePrimary on PATCH /bank-details is unchanged.

What to do
  • Stop calling POST /bank-details/{bank_details_id}/set-primary.
  • Call PATCH /bank-details/{bank_details_id} with isPrimary: true to change which account is the debit account.
Validates a US ein on PATCH /organization-detailsBreaking change
Breaking changeOrganizations

When the organization is incorporated in the US, ein on PATCH /organization-details must be 9 digits, with or without the dash (XX-XXXXXXX). The value is stored with the dash. A value that is malformed, starts with 9 or is all zeros answers 400; it was stored as sent before. An ein identical to the stored value is not checked again, so saving unrelated fields does not fail on an older value. Changing the incorporation country to the US checks the stored value. Outside the US, ein stays a free-form business ID. Blank ein on a US organization is ignored, and null for taxId removes the tax id as before.

What to do
  • Send a US ein as nine digits or XX-XXXXXXX, and never one that starts with 9 or is all zeros.
  • Handle a 400 from PATCH /organization-details by asking the user to correct the number.

2026-10-27

Breaking changes
Removes the filing enhanced data endpointsBreaking change
Breaking changeFilings

GET /filings/{filing_id}/enhanced-data and POST /filings/{filing_id}/enhanced-data/rebuild are no longer available on any Tenanted release, including integrations pinned to 2026-07-21 or 2026-10-06. Requests to them answer 404. Read a filing's totals from GET /filings/{filing_id}.

What to do
  • Stop calling GET /filings/{filing_id}/enhanced-data and POST /filings/{filing_id}/enhanced-data/rebuild.
  • Read filing amounts from GET /filings/{filing_id} instead.

2026-10-23

Breaking changes
Requires a subcategory display label on POST /v1/productsBreaking change
Breaking changeProducts

POST /v1/products now accepts only the subcategory display labels that GET /products/categories lists, such as General Clothing, matched against product_category. Coarse values such as PHYSICAL_GENERAL were accepted before and now answer 400, as does any category and subcategory pair that does not resolve to a product tax code. product_subcategory is a plain string, and product responses return the same display label.

What to do
  • Send the subcategory display label from GET /products/categories as product_subcategory, not a coarse value such as PHYSICAL_GENERAL.
  • Handle 400 on POST /v1/products for a category and subcategory pair that does not resolve.

2026-10-20

Breaking changes
Shows Kintsugi's own task files only as payment receiptsBreaking change
Breaking changeFilings

An attachment Kintsugi adds while working on your account is now visible to you only when it is the state's payment receipt for a balance that is paid. GET /attachments leaves every other such file out. GET /attachments/{attachment_id} and GET /attachments/{attachment_id}/download answer 404 for it, the same answer as an id that does not exist. Files you upload yourself are unchanged.

What to do
  • Treat 404 from the attachment endpoints as final for a file that is not shared with you, and do not retry it.
  • Read payment receipts from paymentConfirmationAttachmentIds on a PAID proposal outcome from GET /proposals.

2026-10-19

Breaking changes
Corrects null and empty values on five 2026-10-06 responsesBreaking change
Breaking changeBilling

On Api-Version: 2026-10-06, a missing value is null for codes and identifiers and an empty string for free text. GET /billing/invoices/{invoice_id}/usage returns null for state, countryCode and requestType on a usage line that has none, instead of an empty string. A VAT report from GET /reports/jobs/{report_job_id}/result returns filingEntityRegistrationNumber: null when the filing has no registration number, instead of an empty string. PATCH /bank-details and POST /bank-details/{bank_details_id}/set-primary return an empty string for an unset bankName or accountHolderName, instead of null, as GET /bank-details already does. GET /connections/openmeter/{conn_id} returns storeName: "" when the connection has no label, instead of null. 2026-07-21 is unchanged.

What to do
  • On 2026-10-06, treat state, countryCode, requestType and filingEntityRegistrationNumber as nullable, and test for null instead of an empty string.
  • Treat an empty bankName, accountHolderName or storeName as not set, and stop testing those for null.

2026-10-16

Breaking changes
Ends nexus and registration timestamps with ZBreaking change
Breaking changeNexus

Timestamps in nexus and registration responses now carry an explicit UTC marker, as in 2026-01-02T03:04:05Z. Before, they had no UTC offset, as in 2026-01-02T03:04:05. The values are unchanged and were always UTC. On a nexus the fields are created_at, updated_at, earliest_transaction_date, most_recent_transaction_date, earliest_collected_date, last_processed_at, last_tax_liability_processed_at, disregarded_at and registration.deregistration_completed. On a registration they are registration_requested, registration_completed, deregistration_requested, deregistration_completed, marked_collecting_date, created_at and deregistration_acknowledged_at. A parser that expects the exact old format fails on the new one.

What to do
  • Parse these fields as RFC 3339 date-times, which accept the Z suffix, instead of matching the old format.
  • Treat the values as UTC, and convert them to a local time only for display.

2026-10-15

Breaking changes
Limits how fast an organization can send invitationsBreaking change
Breaking changeOrganizations

POST /users/invites now counts against a limit per organization, which it shares with the legacy invite endpoint. A request over the limit answers 429 with the error code rate_limited and a Retry-After header that gives the seconds to wait. Before, there was no limit. Every request that passes validation counts, including one that repeats an existing invitation or is refused for its role. This applies to every Api-Version.

What to do
  • Wait the number of seconds in Retry-After before retrying a 429.
  • Space out bulk invitations, and do not retry a refused invitation in a loop.

2026-10-14

Breaking changes
Updates registration credentials with PATCH on 2026-10-06 and lets null clear a credentialBreaking change
Breaking changeRegistrations

On Api-Version: 2026-10-06, PATCH /registrations/{registration_id}/credentials replaces PUT, which now answers 405. A credential you leave out keeps its stored value, and null clears it. That covers username, password, pin and securityQuestions, where null or [] clears the stored set. In jurisdictionSpecificFields, a string sets cdtfaThirdPartyAccessSecurityCode or accessCode and null clears that key, while null for the whole object answers 422. PUT ignored null, so it could never clear a credential. 2026-07-21 keeps PUT with its previous behavior, where null and an empty securityQuestions list leave the stored values unchanged.

What to do
  • On Api-Version: 2026-10-06, call PATCH instead of PUT to save credentials.
  • Send null only for a credential you want removed, and leave out every credential you want to keep.
Splits the filing submission into a draft PATCH and a mark-filed POST on 2026-10-06Breaking change
Breaking changeFilings

On Api-Version: 2026-10-06, PUT /filings/{filing_id}/submission no longer exists and answers 405. PATCH /filings/{filing_id}/submission saves the confirmation fields as a draft and leaves the filing status unchanged. POST /filings/{filing_id}/mark-filed stores any confirmation fields you send and marks the filing FILED. Neither takes action. Repeating a mark-filed request for a filing already filed with the same values answers 200 with the filing and does nothing more, where the PUT answered 409. Both new endpoints answer 409 when the filing is not in FILING or SUBMITTED status. 2026-07-21 keeps the PUT with action. On every Api-Version, amountAdjusted, amountFees, amountPenalties and amountDiscounts now answer 422 when sent as null; before, null was stored as 0.00. Send an amount, including "0.00", or leave it out. returnConfirmationId and paymentConfirmationId still clear when sent as null.

What to do
  • On Api-Version: 2026-10-06, call PATCH /filings/{filing_id}/submission to save a draft and POST /filings/{filing_id}/mark-filed to mark the filing filed.
  • Retry mark-filed after a timeout without checking the filing first: an identical repeat answers 200.
  • Stop sending null for an amount. Send "0.00" for zero, or leave the amount out.
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.
Rejects null on product and product configuration updatesBreaking change
Breaking changeProducts

PATCH /products/{product_id} now answers 422 when any field is sent as null; before, it answered 200 and changed nothing. A field you leave out keeps its value and a field you send is written as sent. To clear a description, send an empty string. PATCH /products/configs/{config_id} answers 422 for null on every field except productDescription, which null clears. Before, null on aiEnabled, isDefault or a category field changed nothing, and a null subcategory beside a category answered 400. This applies to every Api-Version.

What to do
  • Leave out a field you do not want to change instead of sending null.
  • Send an empty string as description to clear a product description.
Rejects null on exemption dates and status, and clears fein and salesTaxId on nullBreaking change
Breaking changeExemptions

PATCH /exemptions/{exemption_id} now answers 422 when startDate, reseller or status is sent as null; before, it answered 200 and changed nothing. null on fein or salesTaxId now clears the stored value, which then reads back as an empty string; before, it was ignored. endDate: null still removes the expiry. A field you leave out keeps its value. This applies to every Api-Version.

What to do
  • Leave out startDate, reseller and status when they should not change.
  • Send null for fein or salesTaxId only when you want the stored value removed.
Rejects null taxRegistrations and an unrecognized state on customer updatesBreaking change
Breaking changeCustomers

PATCH /customers/{customer_id} now answers 422 when taxRegistrations is sent as null; before, it was ignored. An empty list is still accepted and changes nothing. When countryCode is US or CA, a state that is not a valid code for that country now answers 422; before, it was stored as null. This applies to every Api-Version.

What to do
  • Leave out taxRegistrations instead of sending null.
  • Send state as a valid state or province code when countryCode is US or CA.
Reopens a physical presence with endDate null and rejects null on other fieldsBreaking change
Breaking changeNexus

PATCH /physical-nexus/{physical_nexus_id} now treats endDate: null as reopening a closed presence; before, null on any field meant leave it unchanged, and a closed presence could not be reopened. null on category, startDate, street1, street2, city or postalCode now answers 422. An empty string still clears an address field, and a field you leave out keeps its value. Reopening recalculates exposure like any other date change. This applies to every Api-Version.

What to do
  • Send endDate: null to reopen a presence, and leave endDate out to keep it.
  • Stop sending null on the other fields. Leave them out, or send an empty string to clear an address field.
Rejects null on organization settings, exemption reminder settings and user role updatesBreaking change
Breaking changeOrganizations

PATCH /organization-settings and PATCH /organization-settings/exemption-reminders now answer 422 when any field is sent as null; before, they answered 200 and changed nothing. PATCH /users/{user_id} answers 422 when additionalRoles is null; before, null was treated as omitted and kept the member's additional roles. A field you leave out is unchanged, false is written as sent, and additionalRoles: [] still clears the additional roles. This applies to every Api-Version.

What to do
  • Leave out a setting you do not want to change instead of sending null.
  • Send additionalRoles: [] to remove a member's additional roles, and leave the field out to keep them.
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.
Answers 200 with the stored record to an empty bank details updateBreaking change
Breaking changeOrganizations

PATCH /bank-details with an empty body now changes nothing and answers 200 with the stored record, or null when none exists. Before, it answered 400. It does not create a record. A client that reads the response must handle null. This applies to every Api-Version.

What to do
  • Handle a null response body, and do not rely on 400 to detect an update with no fields.

2026-10-13

Breaking changes
Rejects null on replace-only registration fields and a lone createFilingsFromBreaking change
Breaking changeRegistrations

PATCH /registrations/{registration_id} now answers 422 when filingFrequency, autoRegistered, doNotFile, isPreCollecting, registrationsRegime or changeRegimeStatus is sent as null. Those fields only change when you send a value; before, a null was cleared or failed with a server error. Dates, timestamps and free-text fields still clear when sent as null. Where Kintsugi derives the first filing period, createFilingsFrom is recalculated when filingFrequency or registrationDate changes, and sending createFilingsFrom without either change now answers 400 instead of succeeding and being ignored. This applies to every Api-Version.

What to do
  • Stop sending null for filingFrequency, autoRegistered, doNotFile, isPreCollecting, registrationsRegime and changeRegimeStatus. Leave a field out to keep its value.
  • Do not send createFilingsFrom on its own. Change filingFrequency or registrationDate and read the recalculated value from the response.
Rejects null and an empty items list when updating a credit noteBreaking change
Breaking changeTransactions

PATCH /transactions/{transaction_id} now answers 422 when any field is sent as null, and 400 when items is an empty list. Both used to answer 200 and change nothing. A field you leave out keeps its stored value, including marketplace. A sent items list replaces every stored line: a stored line you leave out is removed, and a line you send is written as sent. This applies to every Api-Version.

What to do
  • Leave out a field you do not want to change instead of sending null.
  • When you send items, include every line the credit note should keep, and never send an empty list.
Keeps omitted address fields when updating a transaction addressBreaking change
Breaking changeTransactions

PATCH /transactions/{transaction_id}/addresses now writes only the fields you send. An address field you leave out keeps its stored value; before, it was cleared. null still clears a text field, and isUnincorporated sent as null now answers 422 instead of meaning unchanged. This applies to every Api-Version.

What to do
  • To clear an address field, send it as null. Leaving it out no longer clears it.
  • Do not send isUnincorporated as null. Omit it to keep the stored value, or send false to clear it.

2026-10-09

Breaking changes
Replaces the Colorado retail delivery fee flag with tax_type on registration importBreaking change
Breaking changeRegistrations

POST /v1/registrations now takes tax_type for every jurisdiction, defaulting to SALES_TAX, and no longer reads retail_delivery_fee_obligated. A Colorado request that sets only retail_delivery_fee_obligated is created as a sales tax registration and no retail delivery fee registration opens. To import a retail delivery fee registration, send tax_type RETAIL_DELIVERY_FEE: it opens beside the organization's existing sales tax registration in that state, which must not be cancelled or deregistered, and a request without one answers 400. A tax_type the jurisdiction does not allow also answers 400. GET /v1/registrations/jurisdiction-specific-fields now returns tax_types, the values you can send for that jurisdiction: SALES_TAX is always listed, and USE_TAX, SALES_AND_USE_TAX and RETAIL_DELIVERY_FEE appear where the jurisdiction and your organization support them.

What to do
  • Replace retail_delivery_fee_obligated: true with tax_type RETAIL_DELIVERY_FEE, and import the state's sales tax registration first.
  • Read tax_types from GET /v1/registrations/jurisdiction-specific-fields to see which values a jurisdiction accepts.
Updates organization details one field at a timeBreaking change
Breaking changeOrganizations

PATCH /organization-details now changes only the fields you send. Before, a section you sent replaced the whole section, so its identity fields were required and an omitted optional such as address2 was cleared. Now an omitted section or field is left unchanged, and a sent field is written as sent, including an empty string, 0 and false. null clears a field whose description says it accepts null, which now includes taxId, homeStateRegistration, naics, businessPhone, businessEmail and businessFiscalYearEnd, so a null that was ignored before now removes the stored value. null on any other field answers 422. Sending taxId needs an incorporation country, sent in the same request or already stored, or the request answers 400. This applies to every Api-Version.

What to do
  • Send only the fields you want to change. To keep a value, leave the field out.
  • Stop sending null to mean "leave unchanged": it now clears the field, or answers 422 where the field cannot be cleared.
  • Set the incorporation country before, or with, taxId.

2026-10-08

Breaking changes
Removes retail delivery fee fields from v1 filings and registrationsBreaking change
Breaking changeFilings

A retail delivery fee is now its own registration and its own filing, so v1 no longer returns the fields that flagged it on a sales tax record. is_rdf is gone from filing responses, and retail_delivery_fee_obligated and retail_delivery_fee_effective_from are gone from registration responses. Read tax_type instead: a retail delivery fee registration or filing has tax_type RETAIL_DELIVERY_FEE, and it appears beside the state's sales tax record rather than inside it. On POST /v1/registrations for Colorado, retail_delivery_fee_obligated still asks for a retail delivery fee registration, opened beside the sales registration, but the value is no longer stored or returned on the sales registration. It is available to paid organizations with this feature enabled; for any other organization, a request that sets it answers 400.

What to do
  • Stop reading is_rdf, retail_delivery_fee_obligated and retail_delivery_fee_effective_from from v1 responses.
  • Identify a retail delivery fee filing or registration by tax_type RETAIL_DELIVERY_FEE.

2026-10-07

Breaking changes
Limits billing changes to an organization's Owners, Admins and own API keyBreaking change
Breaking changeBilling

POST /billing/checkout, POST /billing/portal-session, PATCH /billing/plan and PATCH /billing now accept only the organization's own Owners and Admins and the organization's own API key. Any other caller that can reach the organization, including a Member, a partner user and a portfolio or reseller key, answers 403 with code forbidden; these callers were accepted before. A user acting through a portfolio is refused the same way. An organization you cannot access still answers 404, and the billing read endpoints are unchanged.

What to do
  • Start checkouts, portal sessions and plan changes from the organization's own Owner or Admin session, or with its organization API key.
  • Handle 403 with code forbidden from these four endpoints.

2026-10-05

Breaking changes
Limits pausing a filing to the window before its due dateBreaking change
Breaking changeFilings

Pausing a filing now follows the same window as the Kintsugi app. After the 15th of the month a filing is due, it can no longer be paused with any pauseIntent, including assistance and skip, which were accepted before. A review pause also needs a pausedUntilDate from today through the 15th of the due month; a date in the past, accepted before, is now refused. A date that is still today anywhere in the world counts as today. POST /filings/{filing_id}/pause answers a refused pause with 400 and code invalid_request, and POST /filings/bulk/pause still answers 200, listing each refused filing in failed.

What to do
  • Pause a filing no later than the 15th of the month it is due.
  • For a review pause, send a pausedUntilDate no earlier than today and no later than the 15th of the due month.
  • After a bulk pause, check failed for filings that were not paused.
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.

2026-10-02

Breaking changes
Applies one access rule to every address changeBreaking change
Breaking changeAddresses

The five endpoints that change addresses now accept the same callers: any member of the organization, a portfolio Owner or Admin who manages it, or an API key for the organization. A portfolio Member now receives 403 with code forbidden from POST /addresses/approve, which accepted them before. The other four, which accepted only the organization's Owner among its own users, now also accept its Admins and Members, who received 403 before. An organization you cannot access still answers 404, and API keys work on all five as before.

What to do
  • Have a portfolio Owner or Admin approve addresses, or approve with the organization's API key.
  • Handle 403 with code forbidden from POST /addresses/approve.
  • If your app hid these address actions from organization Admins and Members, you can now offer them.
Requires a non-empty userId for imports started with an API keyBreaking change
Breaking changeImports

On POST /imports/initiate and POST /imports/upload-urls, whether you send userId now depends on your credential. With an API key it is required and must not be blank: a missing userId answers 400 with code invalid_request instead of 422, and an empty or whitespace-only value, accepted before, is now refused the same way. With a signed-in user session, userId is optional and ignored, and the import is recorded under that user.

What to do
  • With an API key, always send a non-empty userId that names the person or process uploading.
  • Expect 400 with code invalid_request, not 422, when userId is missing.

2026-09-22

Breaking changes
Requires a request body to deregister a registrationBreaking change
Breaking changeRegistrations

Deregistering now records when and why the registration closes. POST /v1/registrations/{registration_id}/deregister requires a JSON body with closure_date, reason and final_return_acknowledged, so a request with no body, which succeeded before, is now rejected with 422. The 2026-07-21 release changed the same way, with the fields closureDate, reason and finalReturnAcknowledged.

What to do
  • Send closure_date: the date the registration closes with the jurisdiction, as YYYY-MM-DD. Past and future dates are accepted.
  • Send reason: FULL_BUSINESS_CLOSURE or CLOSING_NEXUS_IN_STATE.
  • Send final_return_acknowledged: true, confirming that a final return is still owed.
Returns the existing credit note when a credit note is created twiceBreaking change
Breaking changeTransactions

Creating a credit note with an external_id already used for a credit note on the same original transaction used to fail with 409 Conflict. It now succeeds and returns the stored credit note unchanged. On v1 that response is 200, and creating a new credit note now answers 201 instead of 200. On the 2026-07-21 release the stored credit note comes back with 202, the same as a new one. The same external_id against a different original transaction still returns 409.

What to do
  • On v1, treat both 201 and 200 as success.
  • Stop relying on 409 to detect an existing credit note.
  • To change an existing credit note, update it: PUT /v1/transactions/{original_transaction_id}/credit_notes/{credit_note_id} on v1, or PATCH /transactions/{transaction_id} on the 2026-07-21 release.

2026-09-21

Breaking changes
Returns the existing record when a physical nexus is created twiceBreaking change
Breaking changeNexus

Creating a physical nexus for an organization, country, state and category that already has one used to fail with 409 Conflict. It now succeeds and returns the stored record unchanged: the dates and address in the request are not applied. On v1 and the Partner API the response is 200, the same as for a new record. On the 2026-07-21 release it is 200 for an existing record and 201 for a new one.

What to do
  • Stop relying on 409 to detect an existing record.
  • To change an existing record's dates or address, update it: PUT /v1/nexus/physical_nexus/{physical_nexus_id} on v1, or PATCH /physical-nexus/{physical_nexus_id} on the 2026-07-21 release.

2026-09-17

Breaking changes
Returns the existing product when a product is created twiceBreaking change
Breaking changeProducts

Creating a product with an external_id and source that already exist used to fail with 409 Conflict. It now succeeds with 200 and returns the stored product unchanged: the fields in the request are not applied. A product you deleted is restored instead, with status PENDING, and is not used in tax calculation until it is approved again. Creating a new product now answers 201 instead of 200.

What to do
  • Treat both 201 and 200 as success.
  • Stop relying on 409 to detect an existing product.
  • To change an existing product, update it with PUT /v1/products/{product_id}.

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