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
Lists 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.
2026-11-13
Breaking changesFilters 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.
2026-11-10
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-10-29
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.
2026-10-14
Breaking changesRejects 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.
2026-09-30
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.
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.