# 1. Planning An Integration (2026-07-21) > Understand L1 (transaction sync) and L2 (tax engine) integration levels, and map endpoints to your workflow Source: https://docs.trykintsugi.com/docs/2026-07-21/api-guides/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 1 Baseline Transaction sync Send completed transactions so Kintsugi can determine nexus and prepare filings. Endpoints /products /customers /transactions CALC ONLY No 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 2 Full 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. ## Choosing Your Integration Pattern 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. Q1 Do you need compliance tracking? Nexus monitoring, registrations, filings YES Kintsugi tracks and files L1 Start with transaction sync Required first. Products, customers and transactions. then Q2 Calculate 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. NO You file and remit yourself Q2 Need 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 What if I don't have historical data? Kintsugi will still track your future transactions and calculate nexus going forward. You may need to set registration effective dates and nexus status manually from your own records. Contact our support team to walk through your situation. What date range should I sync? Sync from January 1st of the previous calendar year through today. Integrating in March 2026, for example, means syncing January 1, 2025 through March 2026. That gives nexus calculations a complete data set. Do I need to sync transactions for tax calculation only? In most cases, yes. Even when Kintsugi is not handling filing and remittance, tax calculation depends on nexus status, and Kintsugi derives nexus from your transaction data. The one exception is when you manage nexus and compliance entirely elsewhere and need Kintsugi only for rate lookup. ## 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. ## When to Use Each Endpoint 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. 1 Customer adds items to cart Your storefront, no Kintsugi call yet. 2 Customer enters shipping address Destination determines the rate. 3 Calculate tax Nothing is recorded. POST /tax-estimations Returns tax amount 4 Display total with tax Show the quoted amount before payment. 5 Process payment Declined? Return the customer to the cart. No transaction is recorded, so there is nothing to reverse in Kintsugi. 6 Record the transaction POST /transactions Only after payment succeeds 7 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: 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. Create product records: Start with your catalog. See the Product & Customer Records guide. Plan your data sync: If you need transaction sync, plan the historical import. See the Syncing Transaction Records guide. Build your integration: Wire the endpoints into the workflows described above. For endpoint-level detail, see the API Reference. --- Index of every page: https://docs.trykintsugi.com/llms.txt