Skip to main content
Migrating from Avalara or TaxJar to Kintsugi requires careful planning to ensure a smooth transition without disrupting your tax calculations or compliance workflows. This guide provides a comprehensive roadmap for mapping your existing integration to Kintsugi’s API, migrating data, and validating your implementation.
Plan your migration during a low-traffic period and run both systems in parallel for at least one business cycle to validate results before fully switching over.

​
Understanding Key Differences

Before starting your migration, understanding the architectural differences between providers helps you plan effectively.
Avalara and TaxJar use different API patterns compared to Kintsugi. Avalara typically uses transaction-based APIs with separate endpoints for calculation and recording. TaxJar treats estimations and transaction recording as separate requests. Kintsugi separates tax estimation from transaction recording, enabling more flexible integration patterns.For example, with Kintsugi, you can choose to instantiate a transaction record first, and then calculate and add the amount. Or, you could choose to calculate taxes first, and then send the complete transaction payload. This provides an easy migration pathway from any existing tax provider.
Kintsugi’s separation of estimation and transaction creation allows you to estimate tax during checkout and record transactions after order completion, matching modern e-commerce workflows.
Customer, product, and transaction data structures differ between providers. Kintsugi uses external_id fields extensively to maintain references to your system, while Avalara relies on transaction codes and TaxJar uses transaction IDs. Understanding these mappings is crucial for maintaining data continuity.
Avalara uses TaxCode assignments, TaxJar uses product tax categories, and Kintsugi offers automatic AI-powered classification with optional manual override. This difference can simplify your integration by reducing manual product categorization work.

​
API Endpoint Mapping

Mapping your existing API calls to Kintsugi’s endpoints is the foundation of your migration.

Tax Calculation Mapping

  • Avalara: POST /transactions/create → Kintsugi POST /v1/tax/estimate

  • TaxJar: POST /taxes → Kintsugi POST /v1/tax/estimate

  • Both providers combine estimation and recording, while Kintsugi separates these operations

  • Kintsugi’s estimation endpoint returns tax details without committing the transaction

Transaction Recording

  • Avalara: Uses same endpoint → Kintsugi POST /v1/transactions

  • TaxJar: Uses same endpoint → Kintsugi POST /v1/transactions

  • Create transactions separately after order completion

  • Use external_id to maintain reference to your order system

Customer Management

  • Avalara: POST /customers → Kintsugi POST /v1/customers

  • TaxJar: POST /customers → Kintsugi POST /v1/customers

  • Map customer IDs using external_id field

  • Exemptions handled separately via Exemptions API

Product Management

  • Avalara: TaxCode assignments → Kintsugi automatic classification

  • TaxJar: Product tax categories → Kintsugi Product API

  • Sync products via POST /v1/products

  • Leverage automatic classification or provide manual codes

​
Migration Strategy

Choose a migration approach that minimizes risk and disruption to your business operations.

Parallel Run Approach

  • Run both systems simultaneously

  • Compare tax calculations for accuracy

  • Switch traffic gradually after validation

  • Recommended for production systems

Gradual Rollout

  • Migrate by geographic region first

  • Or migrate by product category

  • Lowest risk approach

  • Allows for learning and adjustment

​
Step-by-Step Migration Process

Follow this structured approach to ensure a successful migration.
1

Phase 1: Preparation and Setup

Set up your Kintsugi account and configure your integration environment.
  • Create Kintsugi account and obtain API keys
  • Configure organization settings and nexus information
  • Set up test environment separate from production
  • Document your current provider’s API usage patterns
  • Create mapping documentation for data structures
2

Phase 2: Data Migration

Migrate existing customers, products, and historical transaction data.
  • Export customer data from current provider
  • Map customer fields to Kintsugi’s customer model
  • Batch import customers using Create Customer API
  • Sync product catalog and map tax classifications
  • Optionally migrate historical transactions for reporting
Ensure customer external_id mapping is consistent between systems to maintain data relationships.
3

Phase 3: Integration Development

Build your Kintsugi integration following the mapping guide.
  • Replace tax calculation API calls with Kintsugi Estimate Tax endpoint
  • Implement transaction creation after order completion
  • Update customer management workflows
  • Handle product classification workflow
  • Implement error handling and retry logic
4

Phase 4: Testing and Validation

Thoroughly test your integration before going live.
  • Test tax calculations across different jurisdictions
  • Validate customer exemption handling
  • Verify product taxability classifications
  • Compare results with current provider during parallel run
  • Test error scenarios and edge cases
5

Phase 5: Cutover and Monitoring

Execute the migration and monitor closely for issues.
  • Execute cutover during low-traffic period
  • Monitor API response times and error rates
  • Validate tax calculations match expected results
  • Keep current provider active as backup initially
  • Have rollback plan ready if issues arise

​
Common Migration Challenges

Understanding potential pitfalls helps you avoid them during migration.
Avalara and TaxJar handle address validation differently than Kintsugi. Kintsugi provides separate address validation endpoints that you should call before tax estimation to ensure accurate calculations.Solution: Implement address validation as a prerequisite step in your checkout flow, using Kintsugi’s Address Validation API before calling Estimate Tax.
Exemption certificate workflows differ significantly between providers. Kintsugi manages exemptions separately from customers, requiring explicit association.Solution: Migrate exemption certificates using the Exemptions API, then associate them with customers using the exemption relationship endpoints.
Tax codes from Avalara or TaxJar don’t directly map to Kintsugi’s product classification system. Kintsugi uses automatic classification with product categories and codes.Solution: Leverage Kintsugi’s automatic product classification for most products, or manually map critical products using product codes during initial sync.
Maintaining transaction references between systems is critical for reconciliation. Your current provider’s transaction IDs won’t work in Kintsugi.Solution: Use Kintsugi’s external_id field to store your original transaction identifiers, enabling easy reconciliation and lookups.

​
Validation Checklist

Use this checklist to ensure your migration is complete and validated.

Integration Completeness

  • [ ] Tax estimation implemented

  • [ ] Transaction creation implemented

  • [ ] Customer sync completed

  • [ ] Product catalog synced

  • [ ] Exemption handling implemented

Data Accuracy

  • [ ] Tax calculations match expected results

  • [ ] All jurisdictions calculating correctly

  • [ ] Exemptions applying correctly

  • [ ] Product taxability accurate

  • [ ] Historical data migrated successfully

Error Handling

  • [ ] Retry logic implemented

  • [ ] Graceful degradation on failures

  • [ ] Error logging configured

  • [ ] Monitoring and alerting set up

  • [ ] Rate limiting handled

Production Readiness

  • [ ] Load testing completed

  • [ ] Documentation updated

  • [ ] Team trained on new system

  • [ ] Rollback plan documented

  • [ ] Support contacts established

​
Post-Migration Optimization

After successful migration, optimize your integration to leverage Kintsugi’s unique features.

Leverage Automatic Classification

Kintsugi’s automatic product classification can reduce manual work. Allow the system to classify products automatically, then review and approve classifications as needed rather than manually categorizing everything upfront.

Optimize API Calls

Since Kintsugi separates estimation from transaction creation, you can cache tax estimates during checkout and only create transactions after order completion, reducing API calls and improving performance.
A successful migration requires careful planning, thorough testing, and gradual rollout. Take time to validate your integration thoroughly before fully switching over to ensure accuracy and compliance.

​
Next Steps

API Reference

Review detailed endpoint documentation in our API Reference to understand request formats and response structures.

Support

Need help with your migration? Contact our Support Team for assistance with your specific migration scenario.