Getting Started

Building Blocks

Subscription Features



Billing Features


Payment Methods

Direct Debit Payments

Configuring Gateways

Fraud Management

Hosted Pages

Attach Additional Data


Open Source Resources

Other Features

API Integration

Third Party Integrations


The option to integrate with Avalara is available only for the test site. If you'd like to have the option enabled for your live site, write to .

Avalara Integration 

Avalara  is a cloud-based SaaS solution for taxation and compliance requirements.

With Chargebee's Avalara integration, you can handle taxation with ease, eliminating the need to manually configure tax for each of your taxable region or nexus. Avalara automates accurate rate determination, address validation, tax filing, and reporting, while complying to jurisdiction rules. Apart from these, Avalara also handles tax rate updates, so you won't have to manually update the tax rates each time they change. All you need to do is integrate your Avalara account with your Chargebee site and take care of the few prerequisites explained below.

You can sign up for an Avalara account here .

Prerequisites for integrating with Avalara 

1. Organization Address

Avalara requires your business' address to calculate tax for an invoice. The Organization Address you provide in your Chargebee site will be used by Avalara for this purpose, and will also be stored as the Origin Address in Avalara. In order to use the Avalara integration, the Organization Address in Chargebee should have at least the Country, State, and Post Code filled.

The Organization Address can be configured for your site under SettingsSite SettingsSite Info.

2. Address for Tax Determination

Chargebee will use your customer's shipping address to calculate tax. If the shipping address is unavailable, then the billing address would be used for the same.


If you're using Hosted Pages, ensure that:

  • The Shipping/Billing Address field has been enabled. This can be done under SettingsHosted Page SettingsField Configurations.
  • The Zip Code, Country, and State fields are made mandatory in the hosted pages.

3. Nexus Jurisdictions

When your business has 'nexus' in a tax jurisdiction, it has a physical presence and connection in that jurisdiction and is thereby obligated to collect and remit taxes to the State. Configure nexus jurisdictions in your Avalara AvaTax account to let Avalara know where to tax. Country, regional, and local jurisdictions can be added for this purpose. While configuring nexus jurisdictions, you will be prompted to add the 'begin' and 'end' dates. Avalara requires these dates to determine when to process transactions.

More on nexus jurisdictions here .

Configuring your Avalara Account in Chargebee 

Once the prerequisites have been implemented, Avalara can be configured for your Chargebee site under SettingsThird Party IntegrationsAvalara.

  1. Enable Avalara for your site under SettingsThird Party IntegrationsAvalara.

  2. Enter the Account number, License key, and Company code received from your Avalara AvaTax account.

  3. If you're planning to use Avalara for tax filing, all invoices and credit notes can be posted to Avalara as soon as they are generated by enabling the Post Document to Avalara option.

  4. The status for all transactions will be set as uncommitted. You could enable the Commit Paid Documents option to set all Paid invoices as well as Adjusted and Refunded Credit Notes as Committed. Once the invoice has been marked as committed, no more changes can be made to it.


Ensure that the Invoice/Credit Note numbers of the documents in Chargebee that are yet to be committed, are different from the numbers used for documents that have already been committed in Avalara.

Avalara Address Validation

The Address Validation option can be used for additional Shipping Address validation (for example Street Address) for a more accurate tax calculation by Avalara. This is especially useful if your business involves delivering of physical goods. A valid street address would mean lesser goods returning to you. When Address Validation is enabled, the Shipping Address will be validated for every "Add/Update Shipping Address" operation.

When this option is turned on, if a customer's Shipping Address is invalid, an error will be returned. The customer will then have to edit the address before completing the signup process.


Only US and Canadian addresses will be validated.

Allow Customer to sign-up with/update Partially Valid Address

If the address is incomplete but Avalara is still able to return the tax rate, then this address is considered as a partially valid address.

The "Allow Customer to sign-up with/update Partially Valid Address" option has been provided to ensure that your signups are not affected due to invalid street addresses. If this option is enabled, Chargebee will allow partially valid addresses during checkout. These will be marked as ‘partially valid' in your Chargebee site. You can then filter the addresses from the web interface, and contact the customers to receive the correct address details.


Addresses with invalid Country, State and Zip codes will not be permitted during sign up.

What happens to existing customers?

For Customers that signed up before you enabled Avalara, Chargebee will cancel the associated Subscription during the renewal if tax cannot determined. To identify Subscriptions that are at a risk of getting cancelled due to this, Chargebee provides a validation tool that can be used to scan through all the existing Subscriptions. The ‘critical' Subscriptions will be marked as Invalid.

The tool will validate a Subscription's taxable address. This means that if the Shipping Address is present, then it will be used for the validation. If the Shipping Address is not present, then the Billing Address will be used instead.

In order to validate the address, Chargebee will make a tax estimate call to check if the address is taxable. If the taxable address happens to be the Shipping Address & if the Validate Full Address option has been enabled, then we will make an additional check to validate the complete address.

  1. The address validation check for existing customers has to be done before going live with Avalara.
  2. If you're collecting the Billing Address from your customer, the billing address will be marked as partially valid/invalid.
  3. The addresses for sign ups that occur after validation and before enabling tax might get through without validation/might surpass the validation check.

To specify the country/countries that Avalara has to use for tax determination, you could use the Enable For field under SettingsSite SettingsTaxesConfigure Tax.

Configuring Tax Codes for your Products (Plans and Addons) 

Avalara uses the tax code to determine the tax rate for each product. Apart from this, taxable and non-taxable products will also be automatically differentiated using tax codes. More on this here .

As soon as Avalara is configured for your site, the Avalara Tax Code field will be available for Plans and Addons. Add the corresponding tax codes here using this Avalara tool .

For taxable products, if the Avalara Tax Code field is not filled in Chargebee, the default tax code will be used by Avalara for that product.

For non-taxable products, the default tax code (NT) will automatically be added by Chargebee and hence the Avalara Tax Code field will not be shown.

As an alternative to configuring tax codes in Chargebee, you could create items in Avalara with the item ID matching the product (Plan/Addon) ID in Chargebee. While creating an item in Avalara, the appropriate tax code should also be provided. If you configure the tax code in both Avalara and in Chargebee, the tax code in Avalara will take override the one provided in Chargebee. However, we do not recommend configuring the tax code in Avalara as this method might be error prone.

Configuring Tax Exemption 

If you'd like a particular customer to be exempted from tax, you could do so while creating the customer in Chargebee by:

  1. Enabling the option This customer is exempted from tax payment

  2. Specifying the exemption reason using Avalara Entity Type or the Exemption Number field.


You can either provide the Avalara Entity Type, or the Exemption Number. Using both options will result in errors.

For customers who are already exempted from tax before the Avalara integration, the default value "NT" will be entered in the Avalara Entity Type. If you would like to enter a specific value for an existing customer, this can be done by updating either the Avalara Entity Type or the Exemption Number field for the customer.

Things to check before you start using the Avalara integration

Here's a checklist you could use to integrate Avalara with your Chargebee site:

  1. Ensure that your site's Organization address is filled out accurately in both Avalara and Chargebee.

  2. If you're using Hosted Pages, ensure that the shipping/billing address field has been enabled and the Zip Code, Country, and State fields are made mandatory.

  3. Configure Nexus jurisdictions in your Avalara AvaTax account.

  4. Include tax codes for your Plans and Addons in Chargebee.

  5. Add the exemption code in Chargebee for customers who are exempted from tax.

  6. If you're an API user, ensure that the address is passed in the estimate API only if you want tax to be calculated. If the address is present, you will be charged for the tax estimate lookup. For more information on how Avalara charges based on API calls, take a look at the 'Document/Transaction Calculations' section here.

  7. Test the integration in your sandbox site.

  8. Enable Avalara for your Chargebee live site.


This integration has the following limitations:

  • Avalara integration is currently supported for USA and Canada only. Supporting Avalara for other countries is on our product roadmap and we'll update the information here as soon as the implementation is done.

  • This integration does not support inclusive pricing.

  • The hosted pages theme "Rhapsody" does not support Avalara integration

  • When Avalara integration has been enabled (or disabled), the next billing amount is not recalculated for the existing subscriptions until the subscription is renewed or updated. This is to avoid the sudden surge of API calls that would be made to Avalara since Avalara charges are based on the number of API calls.

  • Enabling Invoice amount rounding in Chargebee will result in a total amount mismatch between Avalara and Chargebee.

Automatic Retries for Renewals and Activations 

When Avalara Credentials are invalid

Chargebee will notify you via email if the Avalara credentials are invalid, and will prevent sign ups.

Chargebee will set off retry attempts for renewals and activation as follows:




20 hours after the initial failure


40 hours after the previous retry


60 hours after the previous retry

When Avalara's server is down

If Avalara's server goes down, Chargebee will prevent sign ups, and will set off retry attempts for renewals and activations as follows:




30 minutes after the initial failure


60 minutes after the previous retry


120 minutes after the previous retry

You can check Avalara's status here 

Handling Refunds Made Through Chargebee 

When a payment is refunded to the customer, Chargebee will create a Credit Note for the refunded amount. This Credit Note will then be pushed to Avalara and be displayed as a "Returned Amount".

Handling Deleting/Voided Invoices 

When an invoice is voided/deleted in Chargebee, it's status will be marked accordingly in Avalara.