KintsugiKintsugi
API Guides

1. Planning An Integration

The best integrations are decided before they are coded. Kintsugi uses a two-level integration model: Level 1 (L1) is transaction sync, the foundation for every integration, and Level 2 (L2) adds real-time tax calculation. This guide helps you pick your level, sequence the work, and know which Tenanted API endpoint belongs at which point in your workflow.

Understanding Integration Types

Every integration sends transaction data. What changes is whether Kintsugi also calculates tax at checkout and files on your behalf.

LEVEL 1Baseline
Transaction sync
Send completed transactions so Kintsugi can determine nexus and prepare filings.
Endpoints
/products/customers/transactions
CALC ONLYNo filing
Tax calculation
Real-time tax at checkout or billing, while you file and remit yourself.
Endpoints
/tax-estimations/transactions
Transaction data is still required. It is how nexus is determined.
LEVEL 2Full
Tax + compliance
Level 1 plus the tax engine: calculate at checkout and stay filing-ready.
Adds to level 1
/tax-estimations
Turn on after transaction sync is running. L1 first, always.

L1 comes first: Establish transaction sync, then enable L2 when you need Kintsugi to calculate and collect tax at checkout. On a platform connection, Enable tax collection on a connection turns on tax calculation (L2), and it returns 400 if the connection is not ready for tax calculation.

Choosing Your Integration Pattern

Your choice comes down to two questions: where you are in your compliance lifecycle, and who owns filing.

L1: Transaction Sync Only

Transaction sync is the foundation. This pattern records completed sales for compliance tracking without real-time tax calculation. You will use:

  • POST /products to sync your product catalog
  • POST /customers (optional) if you track exempt customers
  • POST /transactions to record completed sales

Historical data requirement: For transaction sync integrations, send historical transactions covering the previous full calendar year through today. Kintsugi uses that history to determine nexus liability. Without it, we cannot pinpoint when you crossed economic nexus thresholds or calculate your compliance obligations accurately.

L1 fits teams moving off manual compliance processes, syncing after the fact from an accounting system, or building an audit trail across existing sales. In platform integrations, this is the Level 1 connection, often labeled "Read Only" or "Compliance" mode.

Tax Calculation Only

This pattern returns real-time tax during checkout without using Kintsugi for filing and remittance. You will use:

  • POST /products to create product records with tax classifications
  • POST /customers (optional) if you sell to exempt entities such as nonprofits or resellers
  • POST /tax-estimations to calculate tax before collecting payment

Transaction data is still required: Even when Kintsugi is not handling filing, tax calculation depends on nexus, and Kintsugi determines nexus from your transaction data. Tax calculation without transaction sync works only when nexus and compliance are managed elsewhere and you need Kintsugi purely for rate lookup.

When to use this pattern: You are replacing another tax calculation service, your compliance team files separately, or you are a marketplace calculating tax for sellers without owning their compliance.

The tax estimation endpoint returns tax amounts, rates, and a per-line-item tax breakdown without recording anything. Nothing is stored and the estimate cannot be retrieved afterwards, which makes it a natural fit for shopping carts, subscription billing platforms, and point-of-sale systems.

L2: Transaction Sync + Tax Calculation (Both)

Most production integrations use both: L1 for compliance plus the tax engine for checkout. Calculate tax during checkout for accurate pricing, then sync the completed transaction for compliance tracking. In platform integrations, L2 is the Level 2 connection, often labeled "Tax Engine" mode, enabled after L1 is established.

Choose Your Path

Two questions decide the integration. Start at the left.

Q1Do you need compliance tracking?Nexus monitoring, registrations, filings
YESKintsugi tracks and files
L1Start with transaction sync
Required first. Products, customers and transactions.
then
Q2Calculate tax at checkout?
YES →Level 2: tax + compliance
Add the tax engine on top of L1.
NO →Level 1 only
Sync now, enable L2 whenever you're ready.
NOYou file and remit yourself
Q2Need tax calculation only?
YES →Tax calculation only
Plus transaction data, so nexus stays accurate.
NO →Talk through the use case
Reach out and we'll scope the integration with you.

Historical Transaction Requirements

If you are building an L1 or L2 integration, or using tax calculation with Kintsugi-managed nexus, send historical transaction data covering the previous full calendar year through today.

Why Historical Data Matters

Kintsugi determines nexus liability by analyzing your sales volume and transaction counts across jurisdictions. Economic nexus thresholds (commonly $100,000 in sales or 200 transactions) are evaluated over a rolling 12-month period or a full calendar year, depending on the state. Some states use their own fiscal year: New York, for example, runs March 1st through the last day of February. Without history, we cannot:

  • Determine when you crossed nexus thresholds
  • Calculate accurate compliance start dates
  • Prepare accurate tax filings
  • Track nexus status changes over time

When to Use Each Endpoint

Knowing where each endpoint belongs in your workflow prevents wasted API calls and keeps your data consistent.

Tax Estimation Endpoint (POST /tax-estimations)

Call this endpoint during checkout or billing, before payment is collected. Typical integration points:

  • Shopping cart pages: When customers review their order before payment
  • Checkout flows: After address entry, before payment processing
  • Subscription billing: When calculating tax for recurring charges
  • Quote generation: When quoting a price to a customer

The estimation endpoint stores nothing, so you can call it as often as customers change their cart or address. To price the same cart again, send the same request again.

Best practice: Call POST /tax-estimations once the customer has entered an address and before final payment processing. Addresses are validated as part of the estimate, and one that cannot be validated returns 400, so you find out before the customer pays.

Transaction Sync Endpoint (POST /transactions)

Call this endpoint once a sale is complete and payment is confirmed. Typical integration points:

  • Order confirmation: After payment succeeds and the order is finalized
  • Invoice creation: When generating invoices for completed sales
  • Daily batch jobs: Syncing from your order management system
  • Webhook handlers: Processing order completion events from e-commerce platforms

Transaction records should reflect real completed sales, not estimates or open carts. Send type: "SALE" to record a sale.

Do not sync open carts: The create request has no status field, and a sale recorded through POST /transactions is stored as COMMITTED, which is the status that counts toward filed liability. Sync only after payment is confirmed.

POST /transactions answers 202 Accepted. The transaction is recorded immediately and tax is calculated afterwards, so the response starts with a processingStatus of QUEUED and tax totals of "0.00".

Integration Setup Workflow

Your setup sequence depends on your integration type, but the shape is consistent.

Step 1: Create Product Records

Every integration starts with product records. Products carry the tax classification that decides whether an item is taxable in a given jurisdiction. Create products before you calculate tax or sync transactions.

See the Product & Customer Records guide for product creation workflows.

Step 2: Create Customer Records (If Needed)

Customer records are required only when you sell to exempt entities such as nonprofits, resellers, or government agencies. If you sell to ordinary consumers, skip this step and pass customer details inline on the transaction.

See the Product & Customer Records guide for when and how to create customer records.

Step 3: Historical Transaction Sync (L1, L2, or Tax Calculation)

If you use transaction sync (L1 or L2) or tax calculation with Kintsugi-managed nexus, import historical transactions from the previous calendar year. This is a one-time bulk operation that sets your nexus tracking baseline.

See the Syncing Transaction Records guide for bulk import strategy.

Step 4: Real-Time Integration

With setup complete, wire the right endpoints into your live workflows:

  • L1 (transaction sync only): POST /transactions on order completion
  • Tax calculation only: POST /tax-estimations in checkout, plus transaction sync for nexus
  • L2 (both): POST /tax-estimations at checkout and POST /transactions after payment confirmation

Common Integration Patterns

Different business models call for different approaches.

E-Commerce Platforms

Most e-commerce platforms land on L2. Start with L1 to sync completed orders for compliance, then enable the tax engine to price tax during checkout and show customers an accurate total before they pay.

A Level 2 checkout makes two Kintsugi calls: one to quote tax, one to record the sale.

Customer adds items to cart
Your storefront, no Kintsugi call yet.
Customer enters shipping address
Destination determines the rate.
Calculate tax
Nothing is recorded.
POST/tax-estimationsReturns tax amount
Display total with tax
Show the quoted amount before payment.
Process payment
Declined? Return the customer to the cart. No transaction is recorded, so there is nothing to reverse in Kintsugi.
Record the transaction
POST/transactionsOnly after payment succeeds
Order complete
The sale now counts toward nexus and appears in filings.

Subscription Billing Platforms

Subscription platforms typically run L2: calculate tax when a subscription is created and at each renewal, then sync the transaction per billing cycle for compliance.

Marketplace Platforms

Marketplaces often price tax for sellers without owning seller compliance. Tax calculation only fits well here, with sellers handling their own transaction sync. Transaction data is still required wherever Kintsugi manages nexus.

Accounting System Integrations

Accounting integrations usually start at L1: sync invoices and completed sales for compliance tracking, with no real-time calculation. Enable the tax engine (L2) later if the need appears.

Next Steps

Once you have chosen your integration type:

  1. Set up authentication: Every request carries your key in the Api-Key header. When your key can reach more than one organization, add an Organization-Id, Connection-Id or Entity-Id header to choose one. See Creating and Managing API Keys for details.

  2. Create product records: Start with your catalog. See the Product & Customer Records guide.

  3. Plan your data sync: If you need transaction sync, plan the historical import. See the Syncing Transaction Records guide.

  4. Build your integration: Wire the endpoints into the workflows described above.

For endpoint-level detail, see the API Reference.