API changelog
Every change to the Kintsugi API and every release, newest first. Breaking changes carry the mark. Tenanted releases are dated, and you choose one with the Api-Version header.
Changes
2026-10-06
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.
2026-10-02
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.
2026-09-22
Returns the existing credit note when a credit note is created twiceTransactions
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.
Releases
2026-07-21
LatestTenanted 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-Version: 2026-07-21with every request, so your integration stays on this release 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 remains the default in these docs and is documented exactly as before, so existing integrations can keep running with confidence. New integrations should start on the Tenanted API.