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

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 /v1/products to sync your product catalog
• POST /v1/customers (optional) if you track exempt customers
• POST /v1/transactions to record completed sales

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 rates during checkout without using Kintsugi for filing and remittance. You will use:

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

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 estimate endpoint returns tax amounts, rates, and a per-line-item tax breakdown without creating a transaction record. That 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.

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 Estimate Endpoint (POST /v1/tax/estimate)

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 estimate endpoint does not create a transaction record, so you can call it as often as customers change their cart or address.

Transaction Sync Endpoint (POST /v1/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" and status: "COMMITTED" so the transaction counts toward compliance calculations.

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): /v1/transactions on order completion
• Tax calculation only: /v1/tax/estimate in checkout, plus transaction sync for nexus
• L2 (both): /v1/tax/estimate at checkout and /v1/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.

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 needs your x-api-key and x-organization-id headers. 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.