Kintsugi applies tax to Stripe invoices only when both of the following are true for your connection:
1. Tax calculation ready: Your organization has completed initial data import, organization setup, and has at least one active tax registration.
2. Tax calculation enabled: the Tax Engine Integration has been turned on for your Stripe connection.
If either condition is not met, Kintsugi still syncs invoices and transactions (Level 1) but does not write tax amounts back to Stripe.
Even when tax is enabled, tax is applied only when:
The customer address is in a country Kintsugi supports for tax calculation
Your organization has an active registration for that jurisdiction
Invoice line items have classified products ready for tax calculation
1. Stripe creates or updates a draft invoice (typically from a subscription renewal or billing event).
2. Stripe sends a webhook event to Kintsugi.
3. Kintsugi reads the invoice, resolves the customer address, and calculates tax.
4. Kintsugi writes tax amounts onto the invoice line items in Stripe.
5. Kintsugi records the transaction internally for compliance and reporting.
6. When the invoice is paid, Kintsugi marks the transaction as committed.
Kintsugi uses its own tax engine, not Stripe Automatic Tax. When Kintsugi applies tax, it disables Stripe Automatic Tax on that invoice to avoid double calculation.
Kintsugi receives events through the Stripe Connect webhook (OAuth connections). The events most relevant to Tax Engine Integration tax are:
Stripe event | What Kintsugi does |
invoice.created | Main tax path: calculates tax and writes it to the draft invoice, then creates the internal transaction. |
invoiceitem.created | Recalculates tax when a new line item is added to a draft invoice. |
invoice.updated | Syncs invoice changes; recalculates tax when quantities or discounts change. |
invoice.finalized | Validates that applied tax matches what Kintsugi calculated. Does not modify the invoice (finalized invoices are locked). |
invoice.paid | Marks the transaction as committed in Kintsugi. |
invoice.deleted | Archives the corresponding transaction in Kintsugi. |
Events with no direct tax engine action: invoice.voided and invoiceitem.deleted are handled indirectly via invoice.updated. Events like invoice.upcoming are not used for tax calculation.
Some billing platforms finalize invoices very quickly after they are created. If tax is not applied before finalization, the invoice becomes immutable, and Kintsugi cannot update it.
If an invoice is finalized before tax is applied, Kintsugi logs a discrepancy alert. That invoice requires manual reconciliation in Stripe.
Kintsugi does not attach pre-built tax rates from your Stripe Tax Rates catalog. Instead, it sets tax
directly on each invoice line using calculated amounts and rates.
On a draft invoice, you will see:
Per-line tax amounts on invoice line items
Invoice total tax updated to reflect Kintsugiʼs calculation
Tax rate labels such as “CA Sales Tax” or “US Sales Tax” (based on jurisdiction)
In the Stripe Dashboard, you may also see new Tax Rate objects under Product catalog → Tax rates. These are created automatically by Stripe when Kintsugi writes tax to an invoice. They are not manually selected from your catalog.
It is normal to see many tax rate objects in Stripe, including archived ones. This is expected behavior, not an error.
What happens:
1. Each time Kintsugi applies tax, Stripe creates a new tax rate object from the calculated rate and amount.
2. When an invoice is updated (e.g. discount applied, quantity changed, line item added), Kintsugi
clears the previous tax on the invoice and applies fresh tax amounts.
3. Tax rate objects from earlier applications are no longer linked to any invoice. Stripe marks them as archived/inactive.
Archived tax rates do not affect current invoices. The tax on an invoice always reflects the most recent
Kintsugi calculation. A large list of archived rates is common for subscription businesses with frequent renewals and invoice edits.
Stripe stores address data in several places. Kintsugi collects all available addresses from the invoice and the customer, then selects one bill-to and one ship-to address using fixed-priority rules.
1. Customer billing address (customer.address)
2. Invoice customer address (customer_address on the invoice)
3. Charge billing address (if a charge exists on the invoice)
4. Payment source owner address (legacy payment methods)
5. If none of the above are usable, a blank bill-to address is used
1. Customer shipping address (customer.shipping)
2. Invoice shipping details (shipping_details)
3. Invoice customer shipping (customer_shipping)
4. Default payment method billing address on the customer
If no ship-to address is found, tax estimation uses bill-to only.
United States: A postal code is required. If the country field is missing but the postal code is a 5-digit US ZIP, Kintsugi treats it as a US address.
Outside the US: A country is required. A postal code alone without a country is not sufficient unless a postal code is present (which satisfies the general rule).
Recommendation for subscription platforms: Set the subscriberʼs tax-relevant address on the Stripe Customer object—preferably customer.shipping for physical goods or customer.address for digital/services. The earlier this address is set before invoice creation, the more reliable tax calculation will be.
Before going live with Tax Engine Integration, confirm:
Subscriber addresses are written to Stripe Customer records before invoices are created
Stripe Automatic Tax is not enabled on invoices you expect Kintsugi to calculate (or accept that Kintsugi will disable it)
Products on invoice line items are synced and classified in Kintsugi
You understand that archived tax rates in Stripe Dashboard are expected
For invoice-specific issues, provide:
Stripe invoice ID (in_...)
Where the subscriber address is set in your integration (Customer shipping, billing, or invoice-level fields)
Your Kintsugi team can trace the webhook flow and confirm which address was used and whether tax was applied before finalization, just reach out to us using the chat in the bottom right corner of your screen.
