/ /

Chargebee Tax Engine Integration Guide

Set up Kintsugi as the tax engine in Chargebee in 19 steps: get your API key, connect the Kintsugi Tax app, set tax regions, and enable tax collection.
Updated 10 days ago

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.

Before you start

  • 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.

Get your Kintsugi API key

  1. Open your API keys. In Kintsugi, click Configuration, then API Key.

  2. 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.

  3. Copy the key. Kintsugi shows it only once. You will paste it into Chargebee in step 6.

Connect Kintsugi in Chargebee

  1. Open Kintsugi Tax. In Chargebee, go to Apps, then Go to Marketplace, then Tax Management, then Kintsugi Tax.

  2. Click Get Started. If you do not have a Kintsugi account yet, click Sign up instead and create one.

    Kintsugi Tax app page in the Chargebee Marketplace with the Get Started button

  3. Paste your Kintsugi API key.

  4. Tick the "I understand Kintsugi..." box.

  5. Click Authenticate.

    Connect to your Kintsugi Tax account window with the API Key field, checkbox, and Authenticate button

  6. Confirm your organization address. Chargebee fills it in from your Business Profile. Update it if it is wrong, then click Proceed.

    Organization Address Configuration screen with the Proceed button

  7. 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).

    Shipping Address Validation screen with both toggles turned on

  8. Turn on sync rules. In Configure Sync Rules, switch on the toggle that sends invoices and credit notes to Kintsugi.

  9. Choose Sync all invoices & credit notes. Pick it from the dropdown, then click Proceed.

Set Kintsugi as the tax provider for your regions

  1. Click Go to Taxes.

  2. Select a region. Pick a region where you want Kintsugi to calculate tax.

    Configure Tax page in Chargebee listing tax regions

  3. 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.

    Pick a mode of configuration list with the Kintsugi option highlighted

Region page in Chargebee showing Kintsugi selected as the tax mode

Your invoices do not get tax from Kintsugi yet.

That starts when you turn on tax collection in Kintsugi (steps 16 to 19).

Enable Tax Collection in Kintsugi

  1. Go to Data Sources. In Kintsugi, click Data Sources in the left menu.

  2. 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.

  3. 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.

  4. Click Enable.

    Enable Tax Collection Setup Checklist in Kintsugi with the Enable button

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.


Check an invoice

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.


Good to know

  • 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.


Turn it off

To disconnect Kintsugi from Chargebee, go to Apps, then Apps Connected, then Kintsugi, and click Unlink integration.


FAQs

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.


Need help?

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.

Was this article helpful?