With tax calculation turned on, Chargebee asks Kintsugi for the tax on each invoice before it generates the invoice. Kintsugi returns the tax for every line, and Chargebee adds it to the invoice.
Setup takes 19 steps across Kintsugi and Chargebee. Each step is a single action, so you can follow along at your own pace.
Scale or Premium Plan Required
Tax engine integrations are available on the Scale and Premium plans. If you are on the Starter or Free plan, upgrade before you start. To check your plan, go to Configuration > Billing Details.
Ask Chargebee to turn on the Kintsugi Tax app. Contact Chargebee Support and ask them to enable Kintsugi Tax on your Chargebee site. It will not appear in the Chargebee Marketplace until they do.
Connect Chargebee read-only first. Follow the Chargebee Read-Only Integration Guide, and wait until the Chargebee card in Data Sources shows Read-only. Kintsugi needs your Chargebee products and customers before it can calculate tax on your invoices.
Approve your products. Review the products Kintsugi imported from Chargebee and approve their categories.
You need at least one active registration. Kintsugi only calculates tax where you are registered.
Your organization details (legal entity, business address, tax IDs) need to be complete.
Check your plan. Tax-engine integrations require a Kintsugi plan that includes them. If yours does not, clicking Enable Tax Collection lets you start a conversation with our sales team.
Check your Chargebee business address. Kintsugi uses it as the origin address for tax. In Chargebee, go to Settings, then Configure Chargebee, then Business Profile.
Collect full addresses at checkout. If you use Chargebee Hosted Pages, turn on the shipping and billing address fields, and make Zip Code, Country, and State required. In Chargebee, go to Settings, then Configure Chargebee, then Checkout & Portal, then Fields.
Use one tax provider per region. Turn off any other automated tax provider for the regions you plan to give to Kintsugi, so only one provider calculates tax on an invoice.
Check renewal addresses before you start. Chargebee cancels any subscription renewal that has an invalid address. Make sure your renewals have valid addresses before you turn on tax calculation. To turn off this auto-cancel behavior, contact Chargebee Support first. You can ask in the same request where you ask them to turn on the Kintsugi Tax app.
Use your production accounts. Make these changes in your live Chargebee site and your production Kintsugi organization. The screenshots in this guide come from a Chargebee test site and a Kintsugi test organization, so you will see "test" labels that will not appear for you.
Open your API keys. In Kintsugi, click Configuration, then API Key.
Create an API key. Click New, choose an expiration, and click Save. If you already have one for Chargebee, skip this step. See How to Create and Delete API Keys.
Copy the key. Kintsugi shows it only once. You will paste it into Chargebee in step 6.
Open Kintsugi Tax. In Chargebee, go to Apps, then Go to Marketplace, then Tax Management, then Kintsugi Tax.
Click Get Started. If you do not have a Kintsugi account yet, click Sign up instead and create one.
Paste your Kintsugi API key.
Tick the "I understand Kintsugi..." box.
Click Authenticate.
Confirm your organization address. Chargebee fills it in from your Business Profile. Update it if it is wrong, then click Proceed.
Turn on Shipping Address Validation. Switch on the toggles, then click Proceed. You can change these later.
Chargebee then validates the taxable address of every new subscriber. Existing subscriptions are checked the first time you run a validation check (Apps, then Apps Connected, then Kintsugi Tax, then Run Check).
Turn on sync rules. In Configure Sync Rules, switch on the toggle that sends invoices and credit notes to Kintsugi.
Choose Sync all invoices & credit notes. Pick it from the dropdown, then click Proceed.
Click Go to Taxes.
Select a region. Pick a region where you want Kintsugi to calculate tax.
Choose Kintsugi as the configuration mode. Kintsugi will calculate tax for that region in place of Chargebee's own tax rates. Repeat steps 14 and 15 for each region.
Your invoices do not get tax from Kintsugi yet.
That starts when you turn on tax collection in Kintsugi (steps 16 to 19).
Go to Data Sources. In Kintsugi, click Data Sources in the left menu.
Click Enable Tax Collection. It is on your Chargebee card. Kintsugi opens the setup checklist.
Everything under Required to enable must pass:
Initial Data Import: your customers, products, and invoices have synced.
Organization Details: your legal entity, business address, and tax IDs are on file.
Registrations: the jurisdictions where tax will be calculated. To add one, register first.
Tick the confirmation box. Kintsugi cannot see your Chargebee tax settings, so it asks you to confirm your Chargebee setup is complete.
The Recommended checks (Product Categorization, Address Validation, Invoice Addresses) are optional, but clearing them helps Kintsugi get the tax right.
Click Enable.
The Chargebee card's badge changes to Tax Engine, and Kintsugi starts calculating tax on new Chargebee invoices.
For more on each checklist item, see Enable Tax Collection on a Tax-Engine Integration.
Create a test invoice in Chargebee for a customer in a jurisdiction where you are registered. The invoice shows the tax Kintsugi calculated for each line.
Tax applies to new invoices only. Turning on tax collection does not recalculate invoices that already exist.
Tax is calculated only where you are registered. Turning on tax collection does not register you anywhere new.
Tax-exempt customers. If a customer is marked Tax Exempt in Chargebee, Kintsugi does not add tax to their invoices.
Addresses do not sync back. If you fix an address in Kintsugi, the change stays in Kintsugi. Update the address in Chargebee too, so future invoices have it.
Other sync rule options. Besides Sync all invoices & credit notes, Chargebee offers Sync only paid invoices and adjusted/refunded credit notes and Don't sync.
To disconnect Kintsugi from Chargebee, go to Apps, then Apps Connected, then Kintsugi, and click Unlink integration.
Q: I chose Kintsugi for a region in Chargebee, but my invoices show no tax. Why?
A: Tax starts only after you click Enable in Kintsugi (step 19). If you already did, check that you are registered in the customer's jurisdiction, your products are approved, the customer's address is complete, and the customer is not marked Tax Exempt.
Q: I do not see Kintsugi Tax in the Chargebee Marketplace. What should I do?
A: Contact Chargebee Support and ask them to enable the Kintsugi Tax app on your Chargebee site.
Q: Will Kintsugi recalculate invoices created before I turned on tax collection?
A: No. Tax applies only to new invoices.
For settings inside Chargebee, such as turning on the Kintsugi Tax app or auto-cancel, Chargebee Support can help you fastest. For anything else, reach out to us using the chat bubble in the Kintsugi app.