KintsugiKintsugi
API reference / Changelog / 2026

API changelog: 2026

Every change to the Kintsugi API in 2026, newest first. For the latest changes and every release, see the API changelog.

2026-11-10

Answers 503 with Retry-After when a credit note's original sale is busy
Behavior changeTransactions

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.

What to do
  • On 503, wait for the Retry-After delay and send the same request again.

2026-10-13

Breaking changes
Rejects null and an empty items list when updating a credit noteBreaking change
Breaking changeTransactions

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

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

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

What to do
  • To clear an address field, send it as null. Leaving it out no longer clears it.
  • Do not send isUnincorporated as null. Omit it to keep the stored value, or send false to clear it.
Does not repeat an exemption when an amend is retried
FixTransactions

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

Filters transactions by customer
NewTransactions

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.

What to do
  • Send customerId to list one customer's transactions without searching by name.

2026-10-02

Lists transactions with a blank or invalid address
NewTransactions

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.

What to do
  • On stale_cursor, request the first page again without cursor.
Returns your customer id on transactions
NewTransactions

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

Breaking changes
Returns the existing credit note when a credit note is created twiceBreaking change
Breaking changeTransactions

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

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