KintsugiKintsugi
API reference / Changelog

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

Adds taxBasis to VAT return reports on POST /reports/jobs
NewReports

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.

What to do
  • Send taxBasis: "COLLECTED" with the filingId of a Canada filing to build the return with collected tax.

2026-11-06

Adds Canada to the VAT_REPORT report, with box help text and section notes
NewReports

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.

What to do
  • Create a VAT_REPORT job for a CA filing to read its return form boxes.
  • Show tooltip and note beside the boxes and sections they describe when they are not null.

2026-10-06

Generates a VAT return report as a report job
NewReports

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.

What to do
  • Start the job, poll GET /reports/jobs/{reportJobId} until it is READY, then read the report from the result endpoint.

2026-10-02

Emails a report's download link on request
NewReports

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.

What to do
  • Send deliveryMethod: "EMAIL" to receive the report link by email.

Releases

2026-10-06

LatestTenanted API

Consistent 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

ChangeApplies to2026-07-212026-10-06
Country code fieldAddresses, customers, transactions, tax estimates and billing usage, in requests and responsescountrycountryCode. Query parameters named country keep their name.
Batch address update method/addresses/transactionsPUTPATCH. The other method returns 405.
Omitted fields in a batch address updatePATCH /addresses/transactionsA field you leave out is clearedKept. null clears a text field, and isUnincorporated: null or an unknown countryCode returns 422.
Address revalidation method/addresses/revalidationPUTPOST. The other method returns 405.
Registration credentials method/registrations/{registration_id}/credentialsPUT, where null leaves a credential unchangedPATCH, where null clears a credential. The other method returns 405.
Filing submission methods/filings/{filing_id}/submissionPUT with actionPATCH saves a draft and POST /filings/{filing_id}/mark-filed marks it filed. PUT returns 405.
Bunny connection refresh method/connections/bunny/{conn_id}/refreshPATCHPOST. The other method returns 405.
Default country field on connectionsConnections, connection settings, PATCH /connections/{conn_id}/settings and POST /connections/apideck/{service_id}/connectdefaultCountrydefaultCountryCode
Incorporation country fieldGET /organization-details and PATCH /organization-detailsincorporationCountryincorporationCountryCode
State on nexus exposure eventsGET /nexus/{nexus_id}/exposure-historystatestateCode, always present
State of a country-level filingstateCode and stateName on every filingEmpty stringnull
Organization state and country when not setstate and countryCode on organizations, and state in organization listsEmpty string, always presentnull, and may be omitted
Exemption with no match on a certificate uploadexemptionId on missing-certificate upload resultsEmpty stringnull
Missing-certificate status valuesUpload, upload status and public confirm-upload resultsLowercase: processing, satisfied, rejectedUppercase: PROCESSING, SATISFIED, REJECTED, plus PENDING on the public landing page
Exemption type when approving certificate importsPOST /certificate-imports/{certificate_import_id}/approve and POST /certificate-imports/bulk-approveAny text, defaulting to customerCUSTOMER, WHOLESALE, TRANSACTION or REVERSE_CHARGE, defaulting to CUSTOMER. Any other value returns 422.
Security questions in a credential revealfields on POST /registrations/{registration_id}/credentials/revealsecurity_questionssecurityQuestions
Line item with no product nameproductName on transaction linesnullEmpty string
Help article label on back-filing optionsGET /filings/backFilingRequest/optionsText or nullAlways text
Job ID on bulk filing resultsPOST /filings/bulk/approve and POST /filings/bulk/pausejobId, always nullRemoved

Moving an integration from 2026-07-21

  1. Send Api-Version: 2026-10-06 with each request you move. Requests without it keep running against 2026-07-21.
  2. Rename country to countryCode wherever you send or read an address, customer, transaction or tax estimate, and rename defaultCountry and incorporationCountry to defaultCountryCode and incorporationCountryCode.
  3. Call PATCH /addresses/transactions for batch address updates, sending null for any text field you want cleared, and POST /addresses/revalidation to re-queue invalid addresses.
  4. Treat null as "not set" for filing and organization locations and for an unmatched exemptionId, and an empty productName as "no product name".
  5. Compare missing-certificate statuses in uppercase, and send exemptionType in uppercase when you approve certificate imports.
  6. Read stateCode on nexus exposure events, request securityQuestions when you reveal registration credentials, and stop reading jobId on bulk filing results.
  7. Call PATCH to save registration credentials, PATCH and POST /filings/{filing_id}/mark-filed in place of PUT for a filing submission, and POST to refresh a Bunny connection.

2026-07-21

Tenanted API

Introducing 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

Topicv12026-07-21
VersioningThe /v1 path prefixThe Api-Version header, dated YYYY-MM-DD. Optional; without it, a request runs against the launch release
Paths/v1/transactions/transactions
Authenticationx-api-keyApi-Key. Endpoints that manage people accept a signed-in session token instead
Choosing an organizationx-organization-id, required on almost every requestOne credential reaches every organization it owns. Narrow a request with Organization-Id, Connection-Id, or Entity-Id
Field namessnake_casecamelCase
Money and ratesDecimal strings out, numbers or strings inDecimal strings at a fixed scale: amounts to 2 places, rates to 9
TimestampsNo single documented formatRFC 3339 in UTC, always ending in Z
ErrorsShapes vary by endpointOne envelope everywhere: code, message, requestId, and errors
PortfolioNot availablePortfolio and Portfolio Reseller endpoints, for partner accounts

Moving an integration from v1

  1. Send Api-Version with every request, pinned to the release you build against (the newest is 2026-10-06), so your integration stays on it until you decide to move.
  2. Drop /v1 from your paths.
  3. Send your key as Api-Key, and replace x-organization-id with Organization-Id wherever you target one organization.
  4. Rename fields to camelCase, and read every amount as a decimal string, never a float.
  5. Branch on the error code, not the message or the HTTP status, and quote requestId when 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

Legacy

The 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.

Kintsugi API Changelog