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
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-10-30
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
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.
2026-10-23
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-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-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.
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.