Streamlining Tax Integrations with Tax SPI

At Chargebee, we’re at the forefront of revenue growth management for merchants worldwide. A core aspect of our service is our sophisticated tax system, which shoulders a myriad of responsibilities to ensure smooth and compliant financial operations for subscription businesses. These responsibilities include:

• Estimating taxes applicable on an invoice.
• Calculating country-specific taxes.
• Creating tax profiles for distinct product or service groups that fall under varying tax rates and compliance measures.
• Managing tax exemptions for specific customers.
• Validating customer shipping addresses both for accurate tax calculation and product delivery purposes.
• Submitting invoice and credit note documents for precise tax reconciliation.

With businesses spanning across borders, reconciling the numerous global tax rules with recurring invoicing becomes a challenging task. To manage this complexity, we’ve refined Chargebee’s tax system through three stages of innovation. Let’s walk through them:

Stage 1: In-House Solutions

The foundation of our tax system began as an in-house module within our core billing software. Merchants today still have the option of this built-in capability, packed with features like multi-region support, tax exemption management, and detailed tax reports.

Let’s peek into the architecture of this initial system. Merchants connect with Chargebee Billing either through our user interface or APIs. For clarity, the diagrams here focus on the API route:

Stage 1: System overview.

Going further into the Chargebee container, we reveal the dedicated tax module, which handles all tax-specific tasks:

Stage 1: Tax module, built in-house, added to the Chargebee container.

Over time, we noticed many merchants opting for third-party tax services. While our in-house solution was comprehensive, it became essential to cater to our merchants’ diverse requirements.

Stage 2: Integrating with Third-Party Tax Providers

To address the growing needs, we expanded our horizon and integrated with third-party tax providers like Avalara and TaxJar. The diagram below illustrates this:

Stage 2: System overview.

The following diagram displays the new internal components that were added to Chargebee Billing as part of the integration: the client modules for Avalara and TaxJar.

Stage 2: Client modules for tax service providers added to the Chargebee Billing container.

Yet, these third-party integrations brought along their own set of challenges, especially in managing integration complexities. Given our vast merchant base, it became evident that a single engineering team building these integrations wouldn’t scale.

Stage 3: The Dawn of Tax SPI

The problem was clear: How do we enable merchants, tax service providers, or independent software vendors (ISVs) to build integrations without being wholly dependent on Chargebee?

Enter the Tax SPI.

We introduced an API contract that sets the expectations for how our Billing module would interact with a tax provider. Any tax service provider keen on integrating with Chargebee can now align with our SPI, creating an adapter, compliant with the SPI’s specifications.

Case in point, the Anrok Adapter was the first to be crafted using the Tax SPI. Merchants can now effortlessly integrate with Anrok via the Chargebee Marketplace. The addition of Anrok’s self-made adapter into our Marketplace stands as a testament to the SPI’s success. Following this, we developed an adapter for another tax provider, Vertex, which is currently in early access.

With the Tax SPI, we’re not just forging a path for streamlined integrations; we’re championing flexibility. While we continue to build and host integrations for strategic tax providers like Vertex, we also empower other tax providers and ISVs to self-serve, allowing them to build and host their own integrations with Chargebee.

All future tax service integrations will adopt this design.

Stage 3: System overview. (Note that “Vertex adapter” is depicted as “internal” because it is built and hosted by Chargebee.)

In the diagram below, we show how the Tax SPI restructures Chargebee Billing’s internals, eliminating the need for a dedicated client library for each tax provider. Instead, the same SPI client library is used to connect to all new tax service provider integrations via their respective adapters.

Stage 3: The SPI client library added to the Chargebee Billing container.

Implementing the Tax SPI

For vendors implementing tax service adapters using our SPI, the process can be summed up in a few steps:

1. Sharing & Implementation: We share the Tax SPI and a configuration template with the third-party vendor. Subsequently, the vendor implements their adapter app in alignment with the SPI. Once this is achieved, they register their adapter app on the Chargebee Marketplace, complete with configuration details, ranging from identity configurations to supported capabilities.
2. Validation & Integration: The configuration undergoes rigorous validation before being loaded into Chargebee. Once the adapter is implemented, we run pre-written Postman tests to evaluate the adapter, sharing any discrepancies for rectification. Furthermore, we have an integration suite assessing end-to-end workflows.
3. Dynamic Integration: Any modifications to the vendor configuration are dynamically reflected on the vendor app’s screen within the Chargebee Billing app. This eliminates the need for additional development work on our end.
4. Merchant Onboarding: After ironing out any issues from the regression and integration suite, we onboard merchants with this new tax vendor integration via the Marketplace.

Keen to delve deeper? Check out Chargebee’s Tax SPI documentation.

Technical review, edits, and diagrams

John Machan, Staff Technical Writer, Chargebee