Guides

Integrating Kintsugi's API

A Kintsugi integration is smaller than it first looks. Four surfaces in your product each make one call, two of them before a sale and two of them at it. This guide is the map: what talks to what, in what order, and why. For request shapes and endpoint details, each section links down to the guide that covers it.

Understanding Your Integration Context

Three questions shape everything that follows.

Core Integration Architecture

Every integration comes down to four touchpoints. Nothing else in your stack needs to know Kintsugi exists.

In your productThe call it makes

Customer managementSignup, account settings, address edits

Create and update customersReference dataBefore the sale

Product catalogNew SKUs, category and description changes

Sync productsReference dataBefore the sale

CheckoutCart totals, before payment

Estimate taxAt the saleRead-only, nothing stored

Order processingOnce payment clears

Create transactionsAt the saleThe record of what you owe

What Kintsugi does with it

Tax calculationRates per jurisdictionCompliance trackingNexus and thresholdsFiling preparationReturns per state

Build the two reference-data rows first, and note that they fail differently. An unknown product is rejected outright; an unknown customer is accepted, and the sale quietly collects tax that the buyer's exemption should have cleared.

Customer and Product Records

Customers and products are the same problem twice: a record in your system that Kintsugi needs a copy of, keyed on your own identifier. Learn the pattern once, then read the two differences.

Something changed on your side

A customer signs up or edits an address; a SKU is created or its classification changes. Fire on the write rather than on a nightly job, because tax depends on current data.

Does Kintsugi already have it?Look it up by your external_id

NO →Create itPOST with your external_id in the payload.

YES →Update itSame call shape, addressed to the existing record.

The lookup is not optional: create is not an upsert, and a duplicate external_id comes back an error rather than replacing the record. Non-2xx otherwise? Back off on 5xx and 429, fix the payload on 4xx.

Store the Kintsugi id

Keep it on your own record. It is what makes step 2 a lookup instead of a guess, and what transactions reference later.

Ready to use in transactions

The record can now be named on an estimate or a transaction.

Delta · customersExemptionsA separate object on its own schedule, since a buyer often uploads a certificate long after signup.

When a certificate arrives

Create the exemptionAssociate it with the customer

EffectLater sales to that buyer clear the exemption check instead of collecting tax.

Delta · productsClassificationYou pick the category from Kintsugi's taxonomy, and Kintsugi maintains what that category means in each state.

Re-send the product when

It moves to a different category or subcategoryIts tax-exempt flag changesIts name or description is revised

EffectThe category is what decides taxability per state at calculation time. Jurisdiction rule changes need nothing from you.

Reference by your own IDs. Transactions and estimates name products with external_product_id and customers with an external_id on the customer object, so a stable identifier on your side is what holds the whole integration together. Full request shapes are in Product and Customer Records.

Exemptions without a customer record. The exemption delta above assumes a buyer you have on file. For a one-off that belongs to no customer, set exempt: true on the line item instead.

For the initial load, create records in batches rather than one at a time, and pause between chunks to stay clear of rate limits. Products never expire, so the catalog can be built well ahead of your first transaction.

Tax Estimation Integration

Tax estimation runs during checkout, where the customer needs an accurate total before they pay. It is usually the most latency-sensitive call in the integration, and the only one that stores nothing.

Cart and shipping address

Tax needs both. The line items decide taxability, the address decides the rate, and until you have an address there is no estimate to show.

Resolve the address first

Rates go down to the local level, so an unresolved address gives a rate you cannot defend. Validate, then estimate against the corrected version.

INVALID →Surface the correction to the buyer at checkout rather than silently substituting it. They are the only one who knows where the parcel goes.

Estimate the tax

Send the line items and the resolved address. You get amounts broken out by jurisdiction.

Display it and take payment

Charge the buyer the estimated tax. Re-estimate if anything in the cart or the address moves between display and payment.

Payment clears, so record it

Now create the transaction. That is the next section, and it is the only step that changes what you owe.

If payment fails, stop. No transaction, no liability: an abandoned checkout leaves nothing behind in Kintsugi.

Estimates are free to repeat. Because nothing is recorded, you can call the endpoint every time the cart or the address changes. Debounce address input, and reuse a result while both are unchanged. Sales Tax Calculations covers the request, the response breakdown, and the zero-tax cases.

Transaction Reporting Integration

Once payment clears, the sale becomes a transaction record. This is the call that changes what you owe.

What goes in

The customerBy the id you stored, so exemptions apply.

Line itemsThe synced products, with quantities and amounts.

AddressesThe resolved ship-to, plus where you shipped from.

Tax chargedWhat the buyer actually paid, from the estimate.

Create the transactionSend it once, keyed on your order id. Same look-up-before-you-write rule as reference data: a repeat external_id is rejected, not merged.

What it unlocks

FilingsThe sale lands on the right return for its jurisdiction.Compliance reportingIt counts toward nexus thresholds, taxable or not.

Sales you never send are sales Kintsugi cannot see. Exempt, zero-tax and marketplace orders all belong here too, because the threshold math needs the whole picture.

Reconciling later. The transaction is keyed on your order ID, which is also how you find it again. Syncing Transaction Records covers status transitions and backfill, and Handling Refund Transactions covers credit notes.

Common Integration Patterns

Where you place these four calls depends on what you are building.

E-commerce: estimate tax during checkout (L2), create the transaction as soon as payment clears (L1). The most common shape.
SaaS and subscriptions: estimate per billing cycle rather than per page view, and create transactions in a batch after the billing run.
Marketplaces: calculate per seller, report centrally, and account for marketplace facilitator rules, which decide whether the tax is yours to collect at all. See US Sales Tax for Developers.

Whichever shape fits, the ordering constraint is the same: reference data first, then transactions, then live estimation on top.

Implementation Checklist

API keys created and authentication working end to end
Customers synced, with exemption certificates attached where they exist
Product catalog synced, every item carrying a category and subcategory
Kintsugi IDs stored against your own records
Address validation wired in ahead of estimation
Estimation called at checkout, with retry and graceful degradation
Transactions created on payment, keyed on your order ID
Tested against exempt customers, zero-tax states, and multi-jurisdiction addresses

L1 first, then L2. Start with transaction sync: customers, products, and transaction reporting. Once that is stable, add the estimation workflow for real-time checkout totals. See Planning an Integration for the full L1/L2 model.

Next Steps

API Reference

Endpoint documentation, request formats, and response structures in the API Reference.

SDKs

Skip the HTTP layer with our SDKs for Python, TypeScript, Java, PHP, and Ruby.