1. Planning An Integration

Before writing your first API call, it helps to take time to understand what you’re building and why. Kintsugi uses a two-level integration model: Level 1 (L1) is transaction sync—the foundation for all integrations—and Level 2 (L2) adds real-time tax calculation. This guide helps you determine which level you need and when to enable each capability.

​

Understanding Integration Types

Every Kintsugi integration is built on transaction sync. Whether you need compliance tracking, tax calculation, or both, you must send transaction data to Kintsugi. Integration types are described in terms of L1 (Level 1) and L2 (Level 2):

​

Choosing Your Integration Pattern

Your choice depends on where you are in your business lifecycle and what compliance obligations you face.

​

L1: Transaction Sync Only

Transaction sync is the foundation. This pattern syncs completed sales for compliance tracking without real-time tax calculations. You’ll 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

Transaction sync suits teams migrating from manual compliance processes, integrating after-the-fact from accounting systems, or building audit trails for existing sales data. In platform integrations, this is the Level 1 connection—often shown as “Read Only” or “Compliance” mode.

​

Tax Calculation Only

This pattern provides real-time tax rates during checkout but does not use Kintsugi for filing and remittance. You’ll use:

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

When to use this pattern: You’re replacing another tax calculation service, your compliance team handles filings separately, or you’re a marketplace platform calculating tax for sellers but not handling their compliance. The tax estimate endpoint returns tax amounts, rates, and jurisdictions without creating permanent transaction records. This works well for shopping carts, subscription billing platforms, and point-of-sale systems that need real-time tax calculations.

​

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 shown as “Tax Engine” mode, enabled after L1 is established.

Show 📊 Integration Pattern Decision Flow

​

Historical Transaction Requirements

If you’re building an L1 (transaction sync) or L2 (transaction sync + tax calculation) integration—or using tax calculation with Kintsugi-managed nexus—you must 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 (like $100,000 in sales or 200 transactions) are evaluated using either rolling 12-month periods, or full calendar years. Some states, like New York, operate on a unique fiscal year (March 1st through the last day of February). Without historical data, 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

Understanding when to call each endpoint in your workflow prevents unnecessary API calls and ensures data consistency.

​

Tax Estimate Endpoint (POST /v1/tax/estimate)

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

• Shopping cart pages: When customers review their order before payment
• Checkout flows: After address entry but before payment processing
• Subscription billing: When calculating tax for recurring charges
• Quote generation: When providing estimates to customers

The estimate endpoint is idempotent and doesn’t create permanent records. You can call it multiple times as customers modify their cart or change addresses.

​

Transaction Sync Endpoint (POST /v1/transactions)

Call this endpoint after a sale is completed and payment is confirmed. Typical integration points include:

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

Transaction records should reflect actual completed sales, not estimates or pending orders. Sync transactions with status: "COMMITTED" to ensure they’re included in compliance calculations.

​

Integration Setup Workflow

Your setup process depends on your integration type, but follows a consistent pattern.

​

Step 1: Create Product Records

All integration types start with product records. Products define tax classifications, which determine whether items are taxable in specific jurisdictions. Create products before calculating tax or syncing transactions. See the Product & Customer Records guide for detailed product creation workflows.

​

Step 2: Create Customer Records (If Needed)

Customer records are only required if you sell to exempt entities like nonprofits, resellers, or government agencies. If all your customers are regular consumers, you can skip customer creation and pass customer data directly in transaction requests. 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’re using transaction sync (L1 or L2) or tax calculation with Kintsugi-managed nexus, sync historical transactions from the previous calendar year. This is a one-time bulk operation that establishes your baseline for nexus tracking. See the Syncing Transaction Records guide for best practices on bulk syncing historical data.

​

Step 4: Real-Time Integration

Once setup is complete, integrate the appropriate endpoints into your live workflows:

• L1 (transaction sync only): Integrate /v1/transactions into order completion flows
• Tax calculation only: Integrate /v1/tax/estimate into checkout (and sync transactions for nexus)
• L2 (both): Integrate /v1/tax/estimate at checkout and /v1/transactions after payment confirmation

​

Common Integration Patterns

Different business models require different integration approaches.

​

E-Commerce Platforms

Most e-commerce platforms use L2: transaction sync (L1) plus the tax engine. Start with L1 to sync completed orders for compliance; once that is running, enable the tax engine to calculate tax during checkout. Calculate tax during checkout to show accurate totals, then sync the completed transaction for compliance.

Show 🛒 E-Commerce Checkout Flow

​

Subscription Billing Platforms

Subscription platforms typically use L2: tax calculation during subscription creation and renewal, plus transaction sync for compliance. Calculate tax when subscriptions are created or renewed, then sync transactions monthly or per billing cycle.

​

Marketplace Platforms

Marketplace platforms often calculate tax for sellers but don’t handle seller compliance. Use tax calculation only, letting sellers handle their own transaction sync if needed. Transaction data is still required for nexus determination if Kintsugi manages nexus.

​

Accounting System Integrations

Accounting system integrations usually start with L1: transaction sync for compliance tracking. Sync invoices and completed sales from your accounting system without real-time tax calculations. The tax engine (L2) can be enabled later if needed.

​

Next Steps

Once you’ve determined your integration type:

1. Set up authentication: Get your API key and organization ID from the Kintsugi dashboard. See Creating and Managing API Keys for details.
2. Create product records: Start with your product catalog. See the Product & Customer Records guide for product creation workflows.
3. Plan your data sync: If you need transaction sync, plan your historical data import. See the Syncing Transaction Records guide for bulk import strategies.
4. Build your integration: Integrate the appropriate endpoints into your workflows following the patterns outlined in this guide.

For detailed endpoint documentation, see the API Reference.