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 changesLists downloadable certificate forms with GET /public/exemption-requests/{token}/missing-certificates/certificate-catalogExemptions
GET /public/exemption-requests/{token}/missing-certificates/certificate-catalog returns the blank exemption certificate forms a purchaser can download and fill in. The link token is the only credential. The response is forms, ordered by jurisdiction and then formName, with multi-jurisdiction forms last. Each form has jurisdiction (the US state code, or null for a form several states accept), formName, formNumber (null when the form has none) and templateFile, the path of the blank PDF relative to the tax-forms/ folder of the public downloads host, such as ca/cdtfa-230.pdf. A state with no accepted form does not appear. The endpoint answers 404 when the link is unknown, 410 when it is closed or expired, and 422 when the token is malformed.
- Call the endpoint with the purchaser's link token to show which certificate forms apply, and build each download address from
templateFile.
Removes sltr_elected and single_local_tax_rate from the Texas fields on POST /v1/registrationsRegistrationsBreaking change
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.
- Stop sending
sltr_electedandsingle_local_tax_ratefor Texas registrations. - Remove both fields from request models generated from the earlier
v1spec.
Adds paymentSource to GET /billing for non-card payment methodsBilling
GET /billing now returns paymentSource when the primary payment method is not a card, such as a bank account. It carries type (for example bank_account), status (for example valid or pending_verification), last4 and bankName, which is present only for a bank account. status, last4 and bankName are null when not reported. When the primary payment method is a card, card describes it and paymentSource is null. paymentSource is also null when no payment method is set or the billing system could not report it.
- Read
paymentSourcewhencardisnullto show a bank account or other payment method. - Accept
paymentSourcein strict response models ofGET /billing.
2026-11-14
Accepts a US ein that starts with 9 on PATCH /organization-detailsOrganizations
A US ein that starts with 9 is now accepted on PATCH /organization-details and stored in the XX-XXXXXXX form. The other checks are unchanged: an ein must be nine digits, with or without the dash, and an all-zero value answers 400.
- Stop rejecting an
einthat starts with9before you send it.
Elects the Texas single local tax rate with POST /registrations/{registration_id}/single-local-tax-rate-electionRegistrations
POST /registrations/{registration_id}/single-local-tax-rate-election opts a Texas remote seller into the single local tax rate and returns the updated registration. The request has no body, and Kintsugi sets the date the rate starts. A registration still being set up starts on its registrationDate, or on the date nexus was reached when that is blank. An unconfirmed import starts on its first filing period. An active registration starts on the first day of the next filing period, and Kintsugi files the election with the Texas Comptroller. Send an Organization-Id, Connection-Id or Entity-Id selector to say which organization the registration belongs to. The endpoint answers 404 when the registration does not exist or belongs to an organization your credential cannot access, 400 when the registration cannot elect, and 409 when an active registration already has a start date.
- Call the endpoint with the Texas registration's id to elect the rate, then read the returned registration for the result.
- Treat
409as already elected: the registration keeps the date it has.
2026-11-13
Breaking changesAdds executedBy to filings and a managedBy filter to GET /filings and GET /filings/summaryFilings
Every filing now returns executedBy, KINTSUGI or PARTNER, saying who files the return. It is always present and is set when the filing is created, so a later change to the client's settings does not change it. GET /filings and GET /filings/summary accept a managedBy filter: a comma-separated list of KINTSUGI and PARTNER that matches any value listed. On GET /filings/summary, the counts and tax totals cover only the matching filings. A value other than KINTSUGI or PARTNER is rejected.
- Read
executedBywhen you need to know who files a return. - Send
managedByonGET /filingsorGET /filings/summaryto list or count only the filings a given party files. - Accept
executedByin strict response models of filings.
Filters exemptions by date range with startDate and endDateExemptionsBreaking change
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.
- Review calls that send
startDateorendDate(start_dateorend_dateonv1) and expect an exact-date match. - To find exemptions that end on one day, filter with
endDateand discard rows whose end date is earlier. - Do not send
endDatewhen you want open-ended exemptions in the results.
Adds taxBasis to VAT return reports on POST /reports/jobsReports
A VAT_REPORT job accepts an optional taxBasis in reportArgs. CALCULATED shows the tax Kintsugi calculated on the return's tax line. COLLECTED shows the tax the store collected, and only Canada filings support it: a COLLECTED request for any other filing is rejected with 400. Omitted or null means CALCULATED, which is what the report showed before. Totals that add the tax line follow the basis you choose. Every other line is the same.
- Send
taxBasis: "COLLECTED"with thefilingIdof a Canada filing to build the return with collected tax.
2026-11-12
Adds bank accounts outside the US with countrySpecificFieldsOrganizations
POST /bank-details now accepts an account in Canada, the United Kingdom, Australia, New Zealand, Mexico and the EU, as well as the US. For these countries, send the account's identifiers in countrySpecificFields instead of accountNumber and routingNumber: for example institutionNumber, transitNumber and accountNumber for Canada, sortCode or iban and bic for the United Kingdom and the EU, bsb for Australia, and clabe for Mexico. countrySpecificFields is required for these countries and not accepted for the US. A country that debits under a mandate also needs mandateCopyId, the id of the latest mandate text the user accepted; any other country refuses it with 400 and code bank_mandate_not_required. Only a user's own sign-in can send mandateCopyId. PATCH /bank-details/{bank_details_id} keeps the account's country and replaces all stored identifiers when you send countrySpecificFields, so send every field the country needs. Responses return countrySpecificFields as an object whose type is CA, GB, AU, NZ, MX, SEPA or US, with each identifier masked to its last four characters in a field ending Last4, or null when none are captured yet.
- To add a non-US account, send
countryandcountrySpecificFieldswith the identifiers that country uses. - Read
countrySpecificFieldson each account inGET /bank-details, and use itstypeto tell which identifiers it holds. - Handle
countrySpecificFieldsin strict response models: it is an object whose fields depend on the country.
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.
Returns how each setup step finished on GET /onboarding/steps-statusOrganizations
GET /onboarding/steps-status now returns primaryProductsCompletedVia, planStepCompletedVia, mailStepCompletedVia, ecmStepCompletedVia and analyticsStepCompletedVia. Each is done when the step was completed, skipped when it was skipped, and null when the step is not yet complete or does not apply to the organization's plan. A step that was skipped and later completed reads done.
- Read these fields to tell a skipped step from a completed one, since the step's status field is
truefor both.
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-10
Adds registrationExecutedBy, filingExecutedBy and a managedBy filter to registrationsRegistrations
Every registration now returns registrationExecutedBy and filingExecutedBy, each KINTSUGI or PARTNER, saying who registers with the jurisdiction and who files its returns. Both are always present and are set when the registration is created. GET /registrations accepts a managedBy filter: a comma-separated list of KINTSUGI and PARTNER that matches any value listed. While a registration is PROCESSING, VALIDATING or AWAITING_CLARIFICATION, managedBy compares against registrationExecutedBy; in every other status it compares against filingExecutedBy. A value other than KINTSUGI or PARTNER is rejected.
- Read
registrationExecutedByandfilingExecutedBywhen you need to know who handles a registration. - Send
managedByonGET /registrationsto list only the registrations a given party handles now.
Answers 503 with Retry-After when a credit note's original sale is busyTransactions
POST /transactions for a credit note, and PATCH /transactions/{transaction_id}, now answer 503 with a Retry-After header when another request is still updating the sale the credit note reverses. The response is safe to retry. Before, a request that waited too long for the sale could fail with 500.
- On
503, wait for theRetry-Afterdelay and send the same request again.
Adds ZOHO_BOOKS as an exemption sourceExemptions
Exemptions that come from a Zoho Books connection report ZOHO_BOOKS as their source. The value appears in the exemption source field and wherever a transaction returns the source of its exemption.
- Accept
ZOHO_BOOKSwherever your code switches on the exemption source, including strict enums in generated clients.
2026-11-06
Breaking changesLimits who can reveal or overwrite stored registration credentials on v1RegistrationsBreaking change
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.
- Handle
403fromGET /v1/registrations/{registration_id}when you sendreveal, and fromPUT /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 credentialsRegistrationsBreaking change
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.
- PUT/registrations/{registration_id}/credentials2026-07-21
- PATCH/registrations/{registration_id}/credentials2026-10-06
- POST/registrations/{registration_id}/credentials/reveal2026-07-21
- POST/registrations/{registration_id}/credentials/reveal2026-10-06
- POST/registrations/{registration_id}/send-password2026-07-21
- POST/registrations/{registration_id}/send-password2026-10-06
- Create the API keys that call these endpoints as an Owner of the organization, or use a service key created by an Owner.
- Handle
403from these endpoints for a key whose user is not an Owner. - On
503, wait for theRetry-Afterdelay and send the request again.
Adds Canada to the VAT_REPORT report, with box help text and section notesReports
A VAT_REPORT job now covers a CA filing whose registration has a return form. GET /reports/jobs/{reportJobId}/result returns the filing's totals laid out on that form, named in returnForm, for example CA_BC_PST. Canada reports do not need VAT accounts payable enabled, which every other country still does (else 403), and their sourceTransactionCount is always 0. A CA filing whose registration has no return form is refused with 400. Every report now also carries tooltip on each box, short help text on what the box means on the return form, and note on each section, an instruction for filing it in the government portal. Both are null when there is nothing to say, and tooltip is null for the non-Canada forms.
- Create a
VAT_REPORTjob for aCAfiling to read its return form boxes. - Show
tooltipandnotebeside the boxes and sections they describe when they are notnull.
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-11-04
Adds a list of Colorado home-rule cities for a registrationRegistrations
GET /registrations/{registration_id}/home-rule-cities returns cities, the Colorado home-rule cities that appear on committed sales on the registration's filings, as display names sorted A to Z. Sales that are archived are left out, and filings count in every status. A registration that is not Colorado sales tax, or that has no matching sales, returns an empty list. The registration is found across every organization your credential owns, so no selector header is needed. An id that does not exist or is not visible to your credential answers 404. When the lookup is briefly unavailable the endpoint answers 503 with a Retry-After header.
- Call it before you confirm a Colorado sales tax deregistration, to show the home-rule cities the registration has sales in.
- On
503, wait for theRetry-Afterdelay and send the request again.
2026-11-03
Accepts an API key that has no user on filing submissionFilings
Saving confirmation data as a draft, submitting it and marking a filing filed now work with an API key that is not tied to a user. These requests answered 404 for such a key before. Who may submit is unchanged: the organization's own filer, with self-managed filings enabled. A credential that carries neither a user nor a key identity is refused with 400.
- Remove any handling that treats
404from these calls as the sign of an API key without a user. - Keep sending an
Organization-Id,Connection-IdorEntity-Idselector to say which organization the filing belongs to.
2026-11-02
Breaking changesAnswers 409 when you approve a filing that is being recalculatedFilingsBreaking change
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.
- Handle
409on an approval by waiting a few seconds and sending the same request again. - On the Tenanted releases, tell this
409apart from the duplicate-period409by itscode, and treat an unknowncodeas a failure rather than a retry.
Returns a held filing to the queue after new credentials only when it is still eligibleRegistrations
Saving a new registration credential returns a held filing to the filing queue only if the organization's plan includes managed filings, the filing's jurisdiction is enabled, and its amounts have not changed since it was held. Otherwise the filing stays on hold until support moves it. The response is unchanged.
- Do not assume a new login releases a held filing; check the filing's status after you save it.
2026-10-30
Returns a held filing to the queue when you save new registration credentialsRegistrations
Saving a new value for username, password, pin, securityQuestions or jurisdictionSpecificFields on a registration can return a filing to the filing queue: one you already approved, held because the jurisdiction's portal sign-in failed, and waiting on you. Sending the stored value again does not. The new login is not tested; if it fails again, the filing goes back on hold. The response is unchanged.
- Check the new login before you save it: a filing returned to the queue goes back on hold if the sign-in fails again.
Returns entityType on invoice line itemsBilling
Each line item on GET /billing/invoices now includes entityType, the kind of item the line bills: plan_item_price, addon_item_price, charge_item_price or adhoc (a one-time charge with no catalog item). It is always present. New values may be added, so handle an unknown value as a generic charge.
- Use
entityTypeto tell plan, add-on and one-time lines apart instead of matching onentityIdordescription.
2026-10-29
Breaking changesValidates US routing and account numbers on bank account writesOrganizationsBreaking change
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.
- Send a routing number of 9 digits that passes the ABA checksum, and an account number of 4 to 17 digits.
- Handle a
422from these endpoints by showing the message for the field named inerrors.
Matches 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.
Ends a deactivated exemption's date window on PATCH /exemptions/{exemption_id}Exemptions
Setting status to DEACTIVATED now closes the exemption's date window: an endDate that is empty or later than today (UTC) becomes today, or the startDate when that is later, so later sales are taxed and sales dated up to the end date keep their treatment. An earlier endDate is kept. While the exemption stays DEACTIVATED, an edit cannot push endDate past that day. Setting status back to ACTIVE without an endDate restores the end date the deactivation replaced, including no end date, unless you changed endDate after deactivating.
- Read
endDatefrom the response after deactivating, since it can differ from the value you sent. - Send an
endDatewithstatusACTIVEwhen you reactivate an exemption and want a specific expiry.
Accepts STARTER on POST /billing/checkout for every organizationBilling
POST /billing/checkout with billingPlan STARTER returns a hosted checkout URL for every organization, where it answered 400 for an organization that could not buy the current Starter plan yet. That organization is subscribed to the legacy Starter plan, so its billingPlan can read GROWTH after checkout. An organization that can buy the current Starter plan gets it, as before.
- Read
billingPlanfromGET /billingafter checkout instead of assuming the plan you requested, and treatGROWTHandSTARTERas the Starter plan.
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.
Returns noticeAttachmentIds on proposalsProposals
Each proposal on GET /proposals returns noticeAttachmentIds: the ids of the state notices Kintsugi attached to it, oldest first, or an empty list when there are none. Download a notice with GET /attachments/{attachmentId}/download.
- Read
noticeAttachmentIdsto show a proposal's notices, and download each one withGET /attachments/{attachmentId}/download.
2026-10-28
Breaking changesConnects 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.
Sets the debit account with isPrimary on PATCH /bank-details/{bank_details_id}OrganizationsBreaking change
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.
- Stop calling
POST /bank-details/{bank_details_id}/set-primary. - Call
PATCH /bank-details/{bank_details_id}withisPrimary: trueto change which account is the debit account.
Validates a US ein on PATCH /organization-detailsOrganizationsBreaking change
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.
- Send a US
einas nine digits orXX-XXXXXXX, and never one that starts with9or is all zeros. - Handle a
400fromPATCH /organization-detailsby asking the user to correct the number.
Returns issueReason on filingsFilings
Filings now return issueReason while status is ISSUE: INVALID_CREDENTIALS, MFA_ISSUE, NEGATIVES_ON_REPORTS, RATE_ISSUES or OTHER. It is null for any other status or when no reason is recorded. New codes may be added, so treat an unknown code like OTHER.
Refines the estimated penalties and interest on back filingsFilings
estimatedPenaltyInterest on BACK_FILING rows (estimated_penalty_interest on /v1) now includes flat late penalties that some states charge even when the tax is zero, so a zero-tax filing can show a value above zero. For a filed return the estimate stops at the filing date instead of continuing to accrue. null still means unknown, and 0 means the estimate found nothing owed. The field is display-only.
- GET/filings2026-07-21
- GET/filings2026-10-06
- GET/filings/{filing_id}2026-07-21
- GET/filings/{filing_id}2026-10-06
- POST/filings/backFilingRequest2026-07-21
- POST/filings/backFilingRequest2026-10-06
- GET/v1/filingsv1
- GET/v1/filings/{filing_id}v1
- GET/v1/filings/registration/{registration_id}v1
- POST/v1/filings/back-filing-requestv1
- Do not treat
estimatedPenaltyInterestas0for a zero-tax filing; read the value as returned.
2026-10-27
Breaking changesRemoves the filing enhanced data endpointsFilingsBreaking change
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}.
- Stop calling
GET /filings/{filing_id}/enhanced-dataandPOST /filings/{filing_id}/enhanced-data/rebuild. - Read filing amounts from
GET /filings/{filing_id}instead.
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-23
Breaking changesRequires a subcategory display label on POST /v1/productsProductsBreaking change
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.
- Send the subcategory display label from
GET /products/categoriesasproduct_subcategory, not a coarse value such asPHYSICAL_GENERAL. - Handle
400onPOST /v1/productsfor a category and subcategory pair that does not resolve.
Lists, adds and updates bank accounts by idBilling
An organization can hold one bank account per country. GET /bank-details lists every account with the numbers masked to accountNumberLast4 and routingNumberLast4, the debit account first and marked by isPrimary; an organization with no accounts gets an empty list. POST /bank-details adds an account, requires country and answers 201. The first account becomes the debit account and a later one does not replace it. PATCH /bank-details/{bank_details_id} updates one account: an omitted field keeps its stored value, null clears any field except country, an empty body changes nothing, and an unknown id answers 404. A second account for a country already on file answers 409, and a country the API does not accept answers 422. Neither write changes the debit account; POST /bank-details/{bank_details_id}/set-primary does. An Owner or Admin user credential or an API key can call these routes, and a Member answers 403. On 2026-07-21, bankName and accountHolderName are null when not captured; on 2026-10-06 they are empty strings.
- Call
GET /bank-detailsto read every account, and useisPrimaryto find the debit account. - Add an account with
POST /bank-detailsand change one withPATCH /bank-details/{bank_details_id}, handling409for a country that already has an account.
Reports the Starter and Scale billing plansBilling
billingPlan on GET /billing and GET /billing/details can now be STARTER or SCALE, in addition to FREE, GROWTH and PREMIUM. GROWTH and STARTER are both the Starter plan: GROWTH is a legacy subscription and STARTER is a current one.
- Treat
GROWTHandSTARTERas the same plan, and acceptSCALEwherever you readbillingPlan. - Tolerate plan values you do not recognize.
Adds flatPrice to the billing estimateBilling
GET /billing/estimate now returns flatPrice, true when the organization is billed a flat monthly price (the Scale or Premium plan) and false when it is billed per filing or registration. When it is true, unitCost is the flat monthly price and estimatedAmount equals it. premium stays true only for the Premium plan.
- Read
flatPrice, notpremium, to tell whether the estimate is a flat monthly price.
2026-10-22
Records whether a bank account belongs to an individual or a businessBilling
Bank details now carry accountHolderType, INDIVIDUAL or BUSINESS. PATCH /bank-details accepts it, and sending null clears it; an omitted field keeps its stored value, and any other value answers 422. Responses from PATCH /bank-details and POST /bank-details/{bank_details_id}/set-primary always include accountHolderType, and it is null for an account where it was never recorded.
- Send
accountHolderTypewithPATCH /bank-detailswhen you collect whether the account is held by an individual or a business, and handlenullwhen you read it.
Returns the open checkout again when a checkout call repeatsBilling
POST /billing/checkout now returns the checkout the organization just started when you call it again for the same plan and price, for example after the user closes the hosted page. Before, the repeat call answered 409. A call that cannot reuse the open checkout, such as one still waiting on a completed payment, still answers 409.
- Let a user reopen checkout by calling
POST /billing/checkoutagain, and keep handling409for a checkout that cannot be reused.
2026-10-21
Shows whether Kintsugi Mail is on file for a registrationRegistrations
A registration now returns kintsugi_mail_on_file, true once the Kintsugi Mail address is on file with the state for that registration and false otherwise, and kintsugi_mail_confirmed_at, the date it was recorded as on file, or null when it is not. Both fields are read-only: they appear on every registration response and are not accepted in a request.
- Read
kintsugi_mail_on_fileandkintsugi_mail_confirmed_atto show whether state mail reaches Kintsugi Mail for a registration.
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-20
Breaking changesLists proposals and what followed with GET /proposalsProposals
GET /proposals returns the proposals Kintsugi sent, newest first by createdAt. Each one carries its subType (BALANCE_DUE or BACKFILING), its status (AWAITING_CUSTOMER, APPROVED or DECLINED), sentAt, decidedAt, the states and periods it covers in items, and, once accepted, an outcome of PAYMENT_IN_PROGRESS, PAID or BACK_FILINGS_CREATED. A PAID outcome lists the state's payment receipts in paymentConfirmationAttachmentIds; download one with GET /attachments/{attachment_id}/download. Amounts are in currency. The list covers every organization your credential can access, and an Organization-Id, Connection-Id or Entity-Id selector narrows it to one. Filter with status, set limit from 1 to 100 (default 50), and follow nextCursor or previousCursor as cursor to page. A cursor works only with the status filter and organization scope it was issued under; any other request answers 400 with stale_cursor, and a cursor that does not parse answers 400 with invalid_request.
- Call
GET /proposalsto follow each proposal fromsentAtto its decision and outcome.
Shows Kintsugi's own task files only as payment receiptsFilingsBreaking change
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.
- Treat
404from the attachment endpoints as final for a file that is not shared with you, and do not retry it. - Read payment receipts from
paymentConfirmationAttachmentIdson aPAIDproposal outcome fromGET /proposals.
2026-10-19
Breaking changesCorrects null and empty values on five 2026-10-06 responsesBillingBreaking change
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.
- On
2026-10-06, treatstate,countryCode,requestTypeandfilingEntityRegistrationNumberas nullable, and test fornullinstead of an empty string. - Treat an empty
bankName,accountHolderNameorstoreNameas not set, and stop testing those fornull.
2026-10-18
Offsets United Kingdom quarterly periods with period_end_monthRegistrations
period_end_month on POST /v1/registrations now accepts a month from 1 to 12 for United Kingdom (GB) registrations that file QUARTERLY, so a filer whose quarters do not follow the calendar can anchor each period end to that month. Before, a GB registration with period_end_month was rejected with 400. For a GB registration with any other filing frequency, a value still answers 400. null, the default, keeps the standard calendar quarters.
- Send
period_end_monthwithfiling_frequencyQUARTERLYto create aGBregistration with offset quarters.
2026-10-16
Breaking changesEnds nexus and registration timestamps with ZNexusBreaking change
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.
- Parse these fields as RFC 3339 date-times, which accept the
Zsuffix, instead of matching the old format. - Treat the values as UTC, and convert them to a local time only for display.
Sets an organization's debit account by idOrganizations
POST /bank-details/{bank_details_id}/set-primary makes the named bank account the organization's debit account, so an organization with several accounts can switch between them. It returns the account with the account and routing numbers masked to their last four characters. It needs a signed-in Owner or Admin of the organization selected by Organization-Id, Connection-Id or Entity-Id; an API key is refused. It answers 404 when the organization has no bank account with that id. makePrimary on PATCH /bank-details still applies only to the account that request updates.
- Call
POST /bank-details/{bank_details_id}/set-primarywith a user credential to change which account is the debit account.
2026-10-15
Breaking changesCreates service API keys that belong to no userOrganizations
POST /api-keys accepts kind: USER, the default, creates a key tied to you, and SERVICE creates a key with no user, for server-to-server use. A service key keeps working when the person who created it leaves, and it does not count against the per-user key limit. Only a signed-in Owner or Admin can create one; an Api-Key cannot, and the request needs an Organization-Id. An organization can hold at most 10 active service keys, and the 11th answers 409. On this API a service key can authenticate only to revoke itself: DELETE /api-keys/{api_key_id} with its own token as the Api-Key and its own id in the path answers success, and any other id answers 401. Every key now returns kind, and GET /api-keys for an organization includes its service keys. A page can hold fewer keys than limit, even none, while hasMore is true, so follow nextCursor until it is false.
- Send
kind: "SERVICE"with anOrganization-Idfrom a signed-in Owner or Admin to create a key that does not depend on a user. - Keep paging
GET /api-keysuntilhasMoreisfalse, and readkindto tell service keys from user keys.
Reuses 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.
Limits how fast an organization can send invitationsOrganizationsBreaking change
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.
- Wait the number of seconds in
Retry-Afterbefore retrying a429. - Space out bulk invitations, and do not retry a refused invitation in a loop.
Answers 409 while another mark-filed request is runningFilings
On Api-Version: 2026-10-06, POST /filings/{filing_id}/mark-filed answers 409 when another request to mark the same filing filed is still running, and nothing changes. Retry shortly: once the first request finishes, an identical repeat answers 200 with the filing.
- Retry
mark-filedafter a short wait when it answers409, and read the filing to confirm its status.
Moves a weekend or holiday payment deadline to a working dayFilings
For some jurisdictions, legalDeadline on GET /filings/{filing_id}/paymentInstructions is the nearest working day on or before the tax authority's deadline when that deadline falls on a weekend or bank holiday. Which holidays count depends on the jurisdiction. Other jurisdictions keep the authority's date. For those jurisdictions, the default deadline, the date to pay by, also counts working days.
- Show
legalDeadlineanddeadlineas returned, without recomputing them from the filing's due date.
2026-10-14
Breaking changesUpdates registration credentials with PATCH on 2026-10-06 and lets null clear a credentialRegistrationsBreaking change
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.
- On
Api-Version: 2026-10-06, callPATCHinstead ofPUTto save credentials. - Send
nullonly 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-06FilingsBreaking change
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.
- On
Api-Version: 2026-10-06, callPATCH /filings/{filing_id}/submissionto save a draft andPOST /filings/{filing_id}/mark-filedto mark the filing filed. - Retry
mark-filedafter a timeout without checking the filing first: an identical repeat answers200. - Stop sending
nullfor 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 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.
Rejects null on product and product configuration updatesProductsBreaking change
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.
- Leave out a field you do not want to change instead of sending
null. - Send an empty string as
descriptionto clear a product description.
Rejects null on exemption dates and status, and clears fein and salesTaxId on nullExemptionsBreaking change
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.
- Leave out
startDate,resellerandstatuswhen they should not change. - Send
nullforfeinorsalesTaxIdonly when you want the stored value removed.
Rejects null taxRegistrations and an unrecognized state on customer updatesCustomersBreaking change
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.
- Leave out
taxRegistrationsinstead of sendingnull. - Send
stateas a valid state or province code whencountryCodeisUSorCA.
Reopens a physical presence with endDate null and rejects null on other fieldsNexusBreaking change
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.
- Send
endDate: nullto reopen a presence, and leaveendDateout to keep it. - Stop sending
nullon 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 updatesOrganizationsBreaking change
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.
- 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 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.
Answers 200 with the stored record to an empty bank details updateOrganizationsBreaking change
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.
- Handle a
nullresponse body, and do not rely on400to detect an update with no fields.
Makes bank details the debit account with makePrimaryOrganizations
PATCH /bank-details accepts makePrimary, a boolean that defaults to false. When true, the account becomes the organization's debit account. It can be sent with other fields or on its own: on its own it applies to the stored record and answers 404 when no bank details exist. Only an Owner or Admin signed in as a user may send true; an API key answers 403, while an API key can still update the other fields.
- Send
makePrimary: truefrom a signed-in Owner or Admin to set the debit account.
Checks whether an organization name is availableOrganizations
GET /organizations/name-availability?name= answers { "available": true } when no organization has that name. The comparison ignores letter case and surrounding spaces and covers every organization, not only the ones your credential can access, so any authenticated credential learns whether a name is taken, as POST /organizations already does with 409. name is required, 1 to 255 characters. A name that is available now can still be taken by the time you create the organization.
- Check a name before
POST /organizations, and still handle409on create.
Returns externalId and isTest on organizationsOrganizations
Organizations now include externalId, the organization's identifier in the sign-in service, which you use to request a token scoped to it, and isTest, whether it is a test organization. Both are always present, on each row of GET /organizations and on the organization returned by GET /organizations/{org_id}, PATCH /organizations/{org_id}, POST /organizations and POST /organizations/{org_id}/archive. Only credentials that can read the organization see them.
- GET/organizations2026-07-21
- GET/organizations2026-10-06
- GET/organizations/{org_id}2026-07-21
- GET/organizations/{org_id}2026-10-06
- PATCH/organizations/{org_id}2026-07-21
- PATCH/organizations/{org_id}2026-10-06
- POST/organizations2026-07-21
- POST/organizations2026-10-06
- POST/organizations/{org_id}/archive2026-07-21
- POST/organizations/{org_id}/archive2026-10-06
Lists a user's own organizations and pins one firstOrganizations
GET /organizations accepts membersOnly for a signed-in user. true lists only the organizations the user belongs to directly. false lists those plus every organization the user reaches through a portfolio, without duplicates. Without it, a user who belongs to several organizations still answers 400 unless a selector header narrows the request. It is not available to an API key, which answers 400. selectedOrganizationId shows one organization first, ahead of the name order, when it is in the list and matches search and status. The first page then holds limit organizations plus that one, and later pages never repeat it. An id you cannot access is ignored.
- Pass
membersOnlyto build an organization switcher, andselectedOrganizationIdto keep the current organization on top.
Confirms an archive with the organization nameOrganizations
POST /organizations/{org_id}/archive accepts an optional organizationName, up to 255 characters. When you send it, it must match the organization's current name, ignoring letter case and surrounding spaces; otherwise the request answers 400 and archives nothing. Leave it out to archive without confirmation, as before.
- Send the organization's name as
organizationNamewhen a person confirms the archive.
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-13
Breaking changesRejects null on replace-only registration fields and a lone createFilingsFromRegistrationsBreaking change
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.
- Stop sending
nullforfilingFrequency,autoRegistered,doNotFile,isPreCollecting,registrationsRegimeandchangeRegimeStatus. Leave a field out to keep its value. - Do not send
createFilingsFromon its own. ChangefilingFrequencyorregistrationDateand read the recalculated value from the response.
Rejects null and an empty items list when updating a credit noteTransactionsBreaking change
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.
- 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 addressTransactionsBreaking change
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.
- To clear an address field, send it as
null. Leaving it out no longer clears it. - Do not send
isUnincorporatedasnull. Omit it to keep the stored value, or sendfalseto clear it.
Stores county, full address and phone when a batch update creates an addressAddresses
When the batch address update creates an address because no id was sent, it now saves county, fullAddress and phone along with the other fields. Before, they were dropped on the first call and saved only when the call was repeated.
Does not repeat an exemption when an amend is retriedTransactions
PUT /transactions/{transaction_id} with requiresExemption no longer creates another exemption on every repeat. While an active exemption of the same type and jurisdiction already covers the transaction or customer, a repeated request amends the transaction and creates nothing new. Omitting customer keeps the stored customer; an amend cannot remove one.
2026-10-09
Breaking changesReplaces the Colorado retail delivery fee flag with tax_type on registration importRegistrationsBreaking change
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.
- Replace
retail_delivery_fee_obligated: truewithtax_typeRETAIL_DELIVERY_FEE, and import the state's sales tax registration first. - Read
tax_typesfromGET /v1/registrations/jurisdiction-specific-fieldsto see which values a jurisdiction accepts.
Updates organization details one field at a timeOrganizationsBreaking change
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.
- Send only the fields you want to change. To keep a value, leave the field out.
- Stop sending
nullto mean "leave unchanged": it now clears the field, or answers422where the field cannot be cleared. - Set the incorporation country before, or with,
taxId.
Reads headline sales, transaction and tax totalsDashboard
GET /dashboard/stats returns an organization's totalSales, totalTransactions, totalTaxAmountImported, totalTaxAmountCalculated, outstandingTotalLiability and totalTaxRemitted, with every amount in the reporting currency. Leave out countryCode to count every country; stateCode works on its own. startDate and endDate (YYYY-MM-DD) bound the window: a transaction counts when its date is inside it, and a filing counts only when its whole period is inside it. A transaction in a currency with no exchange rate on its day is still counted in totalTransactions but left out of the money totals, and excludedTransactionCount, excludedCurrencies, excludedFilingCount and excludedFilingCurrencies report what was left out. An unsupported countryCode answers 400 and a malformed date answers 422. Select the organization with Organization-Id, Connection-Id or Entity-Id.
- Check
excludedTransactionCountandexcludedFilingCountbefore treating the totals as complete.
Sets California and Idaho account fields before saving an access codeRegistrations
PUT /registrations/{registration_id}/jurisdiction-fields sets the account fields a California or Idaho registration needs before PUT /registrations/{registration_id}/credentials can store its access code. Send registrationType, businessName and salesTaxId, all required and not blank. California accepts SALES_TAX or REMOTE_SELLER; Idaho accepts SALES_TAX only. An access code already stored is left unchanged. A blank sales tax id on the registration is filled from the request; one that is already set must be sent unchanged, because a different value is rejected so an imported account number is not replaced. The response is the registration. Only an owner of the organization or an API key scoped to it may call it. A registration that does not exist or belongs to an organization you cannot access answers 404; a registration outside US California and Idaho, REMOTE_SELLER on Idaho, or a changed salesTaxId answers 400; and a credential that can read the organization but not change it answers 403.
- For a registration created without these fields, call
PUT /registrations/{registration_id}/jurisdiction-fieldsfirst, then save the access code with the credentials endpoint (PATCHon 2026-10-06).
2026-10-08
Breaking changesRemoves retail delivery fee fields from v1 filings and registrationsFilingsBreaking change
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.
- GET/v1/filingsv1
- GET/v1/filings/{filing_id}v1
- GET/v1/filings/registration/{registration_id}v1
- POST/v1/filings/back-filing-requestv1
- PUT/v1/filings/{filing_id}/approvev1
- GET/v1/registrationsv1
- GET/v1/registrations/{registration_id}v1
- POST/v1/registrationsv1
- POST/v1/registrations/{registration_id}/deregisterv1
- PUT/v1/registrations/{registration_id}v1
- Stop reading
is_rdf,retail_delivery_fee_obligatedandretail_delivery_fee_effective_fromfrom v1 responses. - Identify a retail delivery fee filing or registration by
tax_typeRETAIL_DELIVERY_FEE.
2026-10-07
Breaking changesLimits billing changes to an organization's Owners, Admins and own API keyBillingBreaking change
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.
- Start checkouts, portal sessions and plan changes from the organization's own Owner or Admin session, or with its organization API key.
- Handle
403with codeforbiddenfrom these four endpoints.
Reports access to each capability on billing detailsBilling
GET /billing/details now fills in capabilities: one { capability, access } entry per capability, where access is INCLUDED, NOT_INCLUDED (the organization is on a paid plan that does not include it) or REQUIRES_PAID_PLAN (it needs a paid plan first). capabilities is null when access does not depend on per-capability settings for the organization, so gate on effectiveEntitlement instead. New capabilities and access values can be added, so treat an unknown access as not included and ignore a capability you do not gate on.
- Read
capabilitiesto show or hide a feature, and fall back toeffectiveEntitlementwhen it isnull.
Updates an organization's bank detailsOrganizations
PATCH /bank-details changes bankName, accountNumber, accountType (CHECKING or SAVINGS), accountHolderName and routingNumber. A field you leave out keeps its stored value, a field sent as null is cleared, and the record is created when none exists. Text values are trimmed and cannot be blank, bankName holds up to 100 characters, and an unknown field is refused. The response never returns full numbers: accountNumberLast4 and routingNumberLast4 hold the last four characters, or **** for a number of four characters or fewer, and are null when not captured. A user must be an Owner or Admin of the organization; an API key that reaches the organization is accepted. Select the organization with Organization-Id, Connection-Id or Entity-Id.
- Send only the fields you want to change, and
nullfor one you want to clear.
Recalculates a filing's amounts on requestFilings
POST /filings/{filing_id}/recalculate queues a recalculation of a filing's amounts from its transactions and answers 202 with filingId, countryCode and status QUEUED. The recalculation runs in the background, so read the filing again for the new amounts. Only US and Canadian filings that are not in FILING, SUBMITTED or FILED status can be recalculated; others answer 400 with code invalid_request. It is available only for organizations that file their own returns, to their Owners and Admins, their API keys and the portfolio that manages them; other callers receive 403. A filing that does not exist or belongs to an organization you cannot access answers 404. Send an Organization-Id, Connection-Id or Entity-Id selector to say which organization the filing belongs to.
- After the
202, readGET /filings/{filing_id}to see the recalculated amounts.
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.
Filters transactions by customerTransactions
GET /transactions and GET /transactions/summary accept customerId, 1 to 255 characters, which keeps only the transactions of the customer with that exact id. It combines with the other filters. A customer id that is unknown or belongs to an organization outside your access returns an empty page and a summary with zero count, never an error. The summary's incompleteAddressCount ignores every filter, this one included. A cursor works only with the customerId it came from: reusing it with another answers 400 with code stale_cursor.
- Send
customerIdto list one customer's transactions without searching by name.
Returns a US filing's tax liability by local jurisdictionFilings
GET /filings/{filing_id}/enhanced-data returns a US filing's actual tax liability: summary totals, jurisdictionBreakdown per local jurisdiction, deductions and exemptions, refunds, and state-specific breakdowns such as county groupings and use tax where the state reports them. Send the filing's two-letter state as jurisdiction. The data is built on request. When it is ready the response is 200 with status DONE and the data in data; while it builds the response is 202 with IN_PROGRESS, so poll until it is DONE. A failed build answers 200 with FAILED and is not retried until you ask. A filing with no transactions answers DONE with data set to null. POST /filings/{filing_id}/enhanced-data/rebuild starts a fresh build even when one is stored and answers 202, or reports the build already running. Rebuilding is open to the same callers as PUT /filings/{filing_id}/submission, for organizations that file their own returns; others receive 403. It allows 10 requests a minute per portfolio, or per organization outside a portfolio, then answers 429. Both endpoints answer 404 for a filing you cannot access, 400 with code invalid_request when jurisdiction does not match the filing, and 400 with the new code unsupported_jurisdiction for a state without this data.
- Poll the GET endpoint while it answers
202, and call rebuild after aFAILEDresult. - If your client accepts only known error
codevalues, addunsupported_jurisdiction.
Generates a VAT return report as a report jobReports
POST /reports/jobs accepts reportType VAT_REPORT with reportArgs.filingId, for a VAT filing in Germany, the United Kingdom, the Czech Republic, Spain or Singapore. Once the job is READY, GET /reports/jobs/{report_job_id}/result returns it as JSON in vatReport: the return form's boxes grouped in sections, each with its boxCode, boxLabel, amount, category and sourceTransactionCount; a summary of output VAT, input VAT, net VAT payable and sales and purchases excluding VAT; ossDestinations, the VAT owed per EU destination country, or null when there are no cross-border sales; and limitations. Amounts are decimal strings rounded to the cent. Creating the job answers 404 for a filing outside the organization, 400 for another country, for a filing with more than 100,000 transactions or with deliveryMethod EMAIL, and 403 for an organization without this feature enabled. The result endpoint answers 400 for a report you download instead, 409 before the job is READY and 404 for a job you cannot access.
- Start the job, poll
GET /reports/jobs/{reportJobId}until it isREADY, then read the report from the result endpoint.
2026-10-05
Breaking changesLimits pausing a filing to the window before its due dateFilingsBreaking change
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.
- Pause a filing no later than the 15th of the month it is due.
- For a
reviewpause, send apausedUntilDateno earlier than today and no later than the 15th of the due month. - After a bulk pause, check
failedfor filings that were not paused.
Returns 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.
Records the confirmation and documents for a return you file yourselfFilings
Two endpoints let an organization that files its own returns record each one in Kintsugi. PUT /filings/{filing_id}/submission takes an action of save_draft, which saves the confirmation details and keeps the filing in FILING, or mark_filed, which saves them and marks the filing FILED. Its optional fields are returnConfirmationId, paymentConfirmationId, amountAdjusted, amountFees, amountPenalties and amountDiscounts, with amounts as decimal strings; a field you leave out is unchanged and a field sent as null is cleared. It returns the updated filing, or 409 when the filing is not in FILING. PUT /filings/{filing_id}/artifacts/{artifact_type} stores the RETURN or PAYMENT confirmation as a PDF of up to 10 MB, sent in the file part of a multipart/form-data body, replacing any document already stored for that type. It answers 409 unless the filing is FILING or FILED, 413 for a larger file and 422 for a file that is not a PDF. Both endpoints are available only for organizations set up to file their own returns, to their Owners and Admins, their API keys and the portfolio that manages them; other callers receive 403.
- Upload the return and payment confirmations while the filing is in
FILING, then call the submission endpoint withaction: "mark_filed". - Download a stored document with
GET /attachments/{attachment_id}/download.
Saves California and Idaho portal access codes with registration credentialsRegistrations
PUT /registrations/{registration_id}/credentials accepts jurisdictionSpecificFields: cdtfaThirdPartyAccessSecurityCode for a California registration and accessCode for an Idaho registration, named as in the credentials reveal response. Only the keys you send change, and leaving the field out or sending null keeps the saved values. The codes are stored encrypted, are never returned by this endpoint, and can be read back with POST /registrations/{registration_id}/credentials/reveal. An unsupported key or a blank value answers 422. A code for a different state than the registration's answers 400, as does a registration that does not yet have its business name, registration type and sales tax id on file.
Adds filing metrics to the organizations listOrganizations
GET /organizations accepts expand=filingMetrics, which adds a filingMetrics object to each organization: totalFilings, filed, pendingApproval (unfiled returns not yet past their due date), overdue (unfiled returns past their due date) and liabilityByCurrency, one { currency, amount } entry per currency. Returns marked do not file are left out of pendingApproval and overdue. Currencies are listed in code order, with returns that have no currency yet last as currency: null, and amounts are decimal strings that are never converted between currencies. An organization with no returns gets zero counts and an empty liabilityByCurrency. Without expand the response is unchanged, an unknown expand value answers 422, and a cursor stays valid with or without expand.
- Pass
expand=filingMetricsto get each organization's filing status in the same call as the list.
2026-10-02
Breaking changesApplies one access rule to every address changeAddressesBreaking change
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.
- Have a portfolio Owner or Admin approve addresses, or approve with the organization's API key.
- Handle
403with codeforbiddenfromPOST /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 keyImportsBreaking change
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.
- With an API key, always send a non-empty
userIdthat names the person or process uploading. - Expect
400with codeinvalid_request, not422, whenuserIdis missing.
Lists imports newest firstImports
GET /imports now lists imports by createdAt, newest first, so a new upload appears on the first page. Before, the order did not follow upload time. Paging stays stable while new imports arrive, and a cursor issued before this change answers 400 with code stale_cursor.
- Expect the newest import first.
- On
stale_cursor, start again from the first page without a cursor.
Lists transactions with a blank or invalid addressTransactions
GET /transactions/blank-addresses lists transactions that have no address yet, newest first, and GET /transactions/invalid-addresses lists those whose address needs fixing. Both cover committed transactions, including partially and fully refunded ones, dated on or after 2018-01-01, and leave out marketplace transactions. They span every organization you can access, or one when you send Organization-Id, Connection-Id or Entity-Id. Pages use limit (1 to 100, default 50) and cursor, and search matches the transaction id, externalId, externalFriendlyId, description and customer name. The invalid list can also be sorted with sort (usFirst by default, countryAsc or countryDesc) and filtered with country, hasCountry, hasState, hasCity, hasCounty, hasPostalCode and addressNotEmpty, which apply to the invalid addresses themselves; an unsupported country answers 400. A cursor works only with the sort, filters and organization it came from: reusing it with others answers 400 with code stale_cursor.
- On
stale_cursor, request the first page again withoutcursor.
Returns your customer id on transactionsTransactions
Transactions now include customerExternalId, your own identifier for the customer, beside customerId and customerName. It is null when the transaction has no customer or the customer has no external id. A list can now show your customer ids without a second call.
Emails a report's download link on requestReports
POST /reports/jobs accepts an optional deliveryMethod. DOWNLOAD, the default, works as before: fetch the report from GET /reports/jobs/{reportJobId}/download once it is READY. EMAIL sends a download link, when the report is ready, to the email address of the user behind your credential; the request cannot name another address. The response echoes deliveryMethod. EMAIL answers 400 for BULK_FILING_REPORTS, for an organization with email turned off, and for a credential without an email address.
- Send
deliveryMethod: "EMAIL"to receive the report link by email.
Counts your importsImports
GET /imports/summary returns total, the number of imports across every organization your credential can access, or one organization when you send a selector such as Organization-Id. Archived imports are counted, so total can be higher than the number GET /imports lists.
Keeps an address's unincorporated setting when an edit leaves it outAddresses
Editing a transaction address through PUT /addresses/transactions or PATCH /transactions/{transaction_id}/addresses used to reset its unincorporated setting to false, so changing only a street or postal code could apply city tax rates to an address outside city limits. Both endpoints now accept an optional isUnincorporated: true keeps city rates from applying, false clears the setting, and leaving it out or sending null keeps the saved value. A new address created by an edit is saved as false when the field is left out. Changing only this setting on a verified address keeps it verified and recalculates the transaction's tax. Transaction addresses in responses now include isUnincorporated.
- Review
isUnincorporatedon addresses you edited through these endpoints before this fix. - Send
isUnincorporatedonly when you mean to change it.
Checks the length of a pause reason before pausingFilings
A pauseReason is saved in a note on the filing, and the note, including a short label Kintsugi adds, holds up to 500 characters. A longer reason used to fail with a server error, sometimes after the filing was already paused. It now answers 400 with code invalid_request before anything changes, and POST /filings/bulk/pause refuses the whole request.
- Keep
pauseReasoncomfortably under 500 characters.
2026-09-30
Requests back filings for past periods through v1Filings
Three v1 endpoints, now documented, let you ask Kintsugi to file returns for periods before your regular filing schedule began. GET /v1/filings/back-filing-request/options lists each active US registration with the periods it can request: periods that have ended, start on or after the registration's tax collection start, end before its first regular filing period, and are not already covered by a filing. Each period has a start_date, an end_date and a label, and each registration a remittance_tag (Paid with return, State bills you later or null) saying how the state collects penalties and interest. POST /v1/filings/back-filing-request takes requests, each a registration_id with its periods, and optional notes. It creates one BACK_FILING filing with status UNFILED per period and returns them in created_filings, with their count in total_created, and 200. Every period is checked before anything is created, so one invalid period refuses the whole request with 400. An unknown registration_id answers 404, an organization without a payment method on file receives 402, and an organization without back filing available receives 404 from both request endpoints. Nothing is filed until each filing is approved with the current terms from GET /v1/filings/back-filing-terms/current, which returns their id, version and text.
- Request only the
start_dateandend_datepairs that the options endpoint lists for each registration. - Show the current terms to the person approving, then approve each filing with
PUT /v1/filings/{filing_id}/approve, sending the termsidasback_filing_terms_id. Missing or outdated terms answer400.
Adds partial exemptions for California partial exemption certificatesExemptions
A new exemption type, partial, records a customer's California partial exemption certificate, such as the one for qualifying manufacturing and research equipment. Unlike a full exemption, a sale to that customer stays taxable: Kintsugi applies the reduced rate the certificate allows to qualifying items sold in California. Create one with exemption_type partial and a certificate_type on POST /v1/exemptions, or with exemptionType and certificateType on POST /exemptions and POST /exemptions/bulk in the 2026-07-21 release. The certificate type is the form's code from GET /v1/exemptions/partial-certificate-types, which lists each form's code, name, jurisdiction and country; its optional jurisdiction parameter narrows the list to one state, ignoring case. Today the list holds nine California forms. A partial exemption needs country US and jurisdiction CA, and the certificate type is accepted only on a partial exemption. Exemptions, including those embedded in transactions, now report the certificate type, which is null for every other type. Partial exemptions are available to organizations that have them enabled; for any other organization, creating one answers 400.
- Send
exemption_type: "partial", acertificate_typefrom the forms list,country_code: "US"andjurisdiction: "CA"on v1, or the same fields in camelCase on the 2026-07-21 release. - Expect a missing or unknown certificate type, another country or another state to be refused:
422on v1,400with codeinvalid_requeston the 2026-07-21 release.
2026-09-22
Breaking changesRequires a request body to deregister a registrationRegistrationsBreaking change
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.
- 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_CLOSUREorCLOSING_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 twiceTransactionsBreaking change
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.
- On v1, treat both
201and200as success. - Stop relying on
409to 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, orPATCH /transactions/{transaction_id}on the 2026-07-21 release.
2026-09-21
Breaking changesReturns the existing record when a physical nexus is created twiceNexusBreaking change
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.
- Stop relying on
409to 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, orPATCH /physical-nexus/{physical_nexus_id}on the 2026-07-21 release.
2026-09-17
Breaking changesReturns the existing product when a product is created twiceProductsBreaking change
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.
- Treat both
201and200as success. - Stop relying on
409to detect an existing product. - To change an existing product, update it with
PUT /v1/products/{product_id}.
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.