Skip to main content
Integrating sales tax compliance into your platform requires careful architectural planning. This guide walks through the key decisions and design patterns needed to architect a robust Kintsugi integration, covering integration points, data flows, and implementation strategies from a Product Manager and Engineer’s perspective.

​
Understanding Your Integration Context

Before diving into implementation details, answer these foundational questions to shape your integration architecture:
Identifying the exact point in your transaction flow where tax calculations happen determines where to integrate Kintsugi’s tax estimation endpoints. Common scenarios include checkout flow, payment processing, order confirmation, and subscription billing.
Most integrations benefit from calculating tax during checkout to provide accurate totals before payment, while also creating transactions after order completion for compliance reporting.
If migrating from an existing tax solution, map existing API calls to Kintsugi’s endpoints, identify data mapping differences, plan a migration strategy that minimizes disruption, and handle edge cases. Focus on maintaining feature parity while leveraging Kintsugi’s additional capabilities like automatic product classification and exemption management.
Building a new integration offers flexibility to design optimal workflows. Consider webhook-based architectures for real-time updates, plan for initial data synchronization, design error handling and retry logic from the start, and build with scalability in mind. Start with the core tax estimation workflow, then expand to include customer management, product synchronization, and transaction reporting.

​
Core Integration Architecture

Every Kintsugi integration revolves around four primary areas: Customers, Products, Sales Tax Estimates, and Transaction Reporting. Understanding how these components interact forms the foundation of your architecture.

​
Customer Management Integration

Customer data drives tax calculations through address validation, exemption status, and registration information. Your integration should handle customer creation, updates, and exemption management.

Initial Customer Sync

  • Batch create customers using the Create Customer endpoint

  • Store mapping between your customer IDs and Kintsugi customer IDs

  • Handle exemptions and tax registrations during sync

  • Consider rate limiting for large customer bases

Real-time Customer Updates

  • Create customers immediately when they register

  • Update customer addresses when shipping information changes

  • Handle exemption certificate uploads asynchronously

  • Maintain customer status synchronization
Use the various external_id fields to maintain a stable reference between your system and Kintsugi, enabling efficient lookups and updates.

​
Product Catalog Integration

Products require tax classification to determine taxability across jurisdictions. Kintsugi offers automatic product classification, but you can also provide product categories and codes directly.

Product Classification

  • Submit product name and description

  • Receive taxability classification automatically

  • Products start with PENDING status

  • Classification happens asynchronously for scale

Manual Product Codes

  • Provide product category and subcategory

  • Set tax_exempt flag for exempt products

  • Use product codes for specific tax rules

  • Accelerate classification approval
Reference products by external_product_id in tax estimation requests to ensure accurate taxability calculations.

​
Tax Estimation Integration

Tax estimation occurs during checkout when customers need to see accurate tax amounts before completing their purchase. This is typically the most performance-critical integration point.

Real-time Estimation

  • Call Estimate Tax API when address changes

  • Include all cart items with product references

  • Handle customer exemptions automatically

  • Cache results for identical requests when appropriate

Address Validation

  • Validate addresses before tax estimation

  • Use address suggestions API for autocomplete

  • Store validated addresses for future use

  • Handle partial addresses gracefully
Integrate tax estimation at the point in your checkout flow where customers review their order, typically after address entry and before payment confirmation. Consider implementing address validation as a prerequisite step to ensure accurate tax calculations.

​
Transaction Reporting Integration

After a sale completes, create a transaction record in Kintsugi for compliance reporting and filing preparation. Transactions link customers, products, addresses, and tax calculations together.

Immediate Transaction Creation

  • Create transactions immediately after order completion

  • Include all transaction details from the order

  • Link to previously estimated tax calculations

  • Handle partial refunds and credit notes

Batch Transaction Sync

  • Batch create transactions periodically

  • Process transactions asynchronously

  • Handle synchronization errors gracefully

  • Implement idempotency using external_id
Create transactions after orders are confirmed and payment is processed. Use the same external_id from your order system to enable idempotent operations and easy reconciliation.

​
Where to Implement Kintsugi Endpoints

Determining the right integration points depends on your platform’s transaction flow and performance requirements. Map out your transaction lifecycle from cart creation through order fulfillment. Most integrations calculate tax during checkout to show accurate totals before payment. Plan data synchronization for initial setup and ongoing updates, design error handling with retry logic and graceful degradation, and optimize for performance with caching and batch operations where possible.

​
Common Integration Patterns

Different platform types benefit from different integration approaches. E-commerce platforms typically use real-time tax estimation during checkout with immediate transaction creation. SaaS and subscription platforms use recurring tax estimation with batch transaction reporting for billing cycles. Marketplace platforms calculate tax per seller with centralized reporting, handling marketplace facilitator rules and supporting multiple tax jurisdictions simultaneously.

​
Implementation Checklist

Ensure your integration covers setup and configuration, customer management with sync and exemption handling, product catalog synchronization and classification, tax estimation with address validation and error handling, transaction reporting with idempotency, and comprehensive testing with various address types and exemption scenarios.
Start with the core tax estimation workflow, then expand to include customer management, product synchronization, and transaction reporting as your integration matures.

​
Next Steps

API Reference

Explore detailed endpoint documentation in our API Reference to understand request formats, response structures, and error handling.

SDKs

Accelerate development with our official SDKs available in Python, TypeScript, Java, PHP, and Ruby.