Skip to main content

Using Numeral’s Tax Engine with Chargebee

This article guides you through connecting Chargebee to Numeral and setting up your account to collect accurate sales tax on invoices.

Written by Sadie Rudiger
Updated over 2 weeks ago

Getting Started

Step 1: Connect Chargebee to Numeral

Log in to your Numeral dashboard and follow the steps below:

🔹 Navigate to Connections on the left-hand menu and select Chargebee

Screenshot for reference
​

🔹 Complete the fields in the pop-up window, including entering a name for your connection and your Chargebee dashboard URL.

Screenshot for reference

🔹 Paste your Full-Access Key from Chargebee → Click Go to Chargebee → copy your full_access_key_v1 → paste it in Numeral

Screenshot for reference

Step 2: Add the Numeral Webhook in Chargebee

Once you select Connect, you will be redirected to a new window prompting you to add the Chargebee webhook:

  1. Copy the Numeral API key
    ​

  2. Click Go to Chargebee

  3. In Chargebee, click Get Started in the top right corner

  4. Enter the Numeral API key
    ​

  5. Check the box next to Numeral's terms of service
    ​

  6. Click Authenticate


Once you select Authenticate, your organization address should auto-populate:
​

Step 3: Configure Organization and Invoice Settings

  1. Click Proceed
    ​

  2. Toggle Validate customer shipping addresses with Numeral

  3. Toggle Allow Chargebee to post invoices & credit notes to Numeral and select Commit only paid invoices and adjusted/refunded credit notices

  4. Click Proceed
    ​

  5. Validate existing addresses: select the regions you have customers in → Click Run Check


    ​

  6. Finalize integration by selecting Go to Taxes →

  7. Choose the regions in which you need to collect sales tax → select Numeral.

Step 4: Complete Connection

Navigate back to Numeral and click Continue.

✅ Your Numeral <> Chargebee integration is now active and syncing (indicated by the green dot).
​
​💡 For a visual walkthrough, check out the video below

Generating Your First Invoice

1. Go to the Subscriptions tab in Chargebee
​

2. Click + Create Subscription
→ select a customer
​

3. Choose your Product Family
→ click + Add Plan
→ select the plan to charge
​

4. Under Invoicing Options:
→ Select Generate all renewal invoices in pending state.
→ Check Also generate first invoice in pending state.

Screenshot for reference

⚠️ This ensures the tax engine has time to apply the correct tax rate.

5. If the customer does not have a shipping address, select Same as billing address

6. Click Create in the top right corner

7. Review the invoice under Invoices & Credit Notes.

Screenshot for reference

💡 For a visual walkthrough, check out the video below

Timing Considerations

If you currently use Chargebee for tax calculation, coordinate with your Onboarding Manager to confirm your go-live date with Numeral.

For example, if Numeral will begin managing your sales tax registrations in August, you should meet with your Onboarding Manager on August 1 to turn off Chargebee tax calculations and activate Numeral’s tax engine.

⚠️ Note

  • Numeral will not collect tax before your confirmed start date.

  • Tax collection will only occur in states where your company is registered.

You can confirm your start dates and registered states by navigating to the Jurisdictions tab in your Numeral dashboard.

Confirming Your Configurations

During your go-live call, your Onboarding Manager will ensure Chargebee’s automatic tax calculations are disabled. You can also verify this on your own –

🔧 How to Turn Off Chargebee’s Tax Calculations

  1. Log in to Chargebee

  2. Go to Settings

  3. Select Configure Chargebee

  4. Navigate to the Taxes section

  5. Disable Automatic Tax Calculation in your dashboard

Product Categorization and Taxability

Correct product categorization is essential for accurate tax calculation. It's important to note that the way your products are categorized in Chargebee does not carry over to Numeral, so categories must be set up directly within your Numeral account.

During onboarding, your Onboarding Manager will help you set up your initial product categories in Numeral and show you how to manage them going forward. Numeral’s tax engine uses these categories to determine the correct taxability for each product.

💡 Before You Start: Have a copy of Numeral’s Product Category List available for reference. This will help you quickly locate the correct category when editing or creating products.

Edit an Existing Product

  1. Go to Developers → Products.

  2. Click the Edit icon next to the product you want to update.

  3. Search for and select the correct Product Category.

  4. Save your changes.

Add a New Product

  1. Navigate to Developers → Products → Create Product.

  2. Enter the Product ID (this should match the Product ID in your sales platform).

  3. Add the Product Name.

  4. Select or type the appropriate Product Category.

  5. Click Create Product to save.

⚠️ If You Don’t See the Developers Tab: If you onboarded with Numeral before product categorization was available, the Developers tab may not appear in your dashboard. If so, please contact our team using the messaging widget in your dashboard, and we’ll enable this feature for your account.

Customer Tax Exemptions

If a customer is exempt (i.e. should not be charged sales tax), you must mark them as tax-exempt in Chargebee:

  1. Navigate to Customers → select the customer.

  2. Click Edit Customer.

  3. Scroll to Tax Details → check This customer is exempt.

💬 Questions? Reach out to our team anytime via the messaging widget in your Numeral dashboard.

Did this answer your question?