Tax SPI

Overview

When processing checkout sessions and creating invoices for the merchant’s customer, Chargebee needs to perform the following operations:

  • Checking whether customer shipping addresses are valid for the purpose of tax calculation

  • Estimate taxes applicable on an invoice and its line items

  • Submit invoice and credit note documents for tax reconciliation

  • Validate customer shipping addresses for the purpose of product delivery

Chargebee relies on external services to fulfill these needs. These external services or tax services may be of one of the following:

  • Tax service providers that offer APIs for calculating tax.

  • In-house tax calculation software used by the merchant.

To communicate with the tax service, Chargebee needs a tax service adapter that acts as a connector with the service. Chargebee connects to the adapter using the Tax Service Provider Interface (SPI).

You must implement this SPI by building a tax service adapter app in order to integrate the tax service with Chargebee. You would typically do this when you are one of the following:

  • A tax service provider wanting to integrate your service with Chargebee.

  • A merchant looking to integrate your in-house tax calculation software with Chargebee.

  • A system integrator building a connector between a tax service provider and Chargebee.

The sequence diagram below illustrates how Chargebee interacts with the tax service via the adapter:

 

A UML sequence diagram showing communication between Chargebee, Tax Service Adapter, and the Tax Service.
How Chargebee communicates with a Tax Service via the Adapter.

 

SPI Capabilities

This section outlines the primary functions of the tax SPI and the scenarios in which Chargebee employs them.

Health check

GET /health

Required

Implementing this endpoint is a necessity for successful integration with Chargebee.

The /health endpoint supplies real-time updates about the operational health of the Tax Service Provider. Chargebee employs this endpoint to monitor the condition of the tax provider system. It assesses the overall service health as well as the status of individual components such as the Tax Adapter API server, Tax API server, and the application database.

Authenticating Chargebee calls

POST /credentials/validate

This endpoint is called when the merchant connects their Chargebee site to the tax service adapter.

Importing Chargebee Product Catalog

While importing merchants' Product Catalog from Chargebee into the tax system, it is important to handle both Product Catalog 1.0 and Product Catalog 2.0. The configurations resource provides information on the version of the Product Catalog for a specific Chargebee site.

Note

This is not applicable if the tax provider allows merchants to map products with tax codes in Chargebee.

Address verification and taxability check

When customers provide addresses, it is beneficial to validate them. This ensures the following:

  • Successful delivery of goods: Validating shipping addresses minimizes the likelihood of goods being returned due to inaccurate or nonexistent locations.

  • Accurate tax application and preventing subscription creation/renewal failures: Taxes are calculated using the customer's taxable address. If the address is invalid, tax calculation can fail, leading to unsuccessful invoicing. This results in failure to create subscriptions or subscription cancellations during renewals.

The Tax SPI provides a separate endpoint for each of these validation measures:

Address verification

POST /address/validate

To minimize the likelihood of returned goods due to invalid addresses, it is beneficial to immediately verify shipping addresses provided by customers.

Assuming the Shipping Address Validation is activated in Chargebee by the merchant, this endpoint is invoked whenever a shipping address for a customer is added or updated.

Note

While implementing this endpoint is optional, it is strongly recommended. Doing so enables Chargebee to flag unshippable addresses.

Taxability check

POST /address/check-taxability

Taxes applicable to a customer invoice are calculated based on their taxable address. This could be either the shipping or billing address, depending on certain conditions. For more details, see our FAQ here.

Therefore, it's always a good practice to check the taxability of an address when it's provided by the customer. This will prevent payment issues arising from the inability to compute taxes. Implement the /address/check-taxability endpoint to ensure that Chargebee can verify the taxability of addresses as they are entered by the customer.

Specifically, Chargebee calls the above endpoint in each of the following cases:

  • When connecting their Chargebee site to your tax service, the merchant is offered an option to trigger an action that checks all the existing taxable addresses in the Chargebee site to determine if tax can be calculated for them. The /address/check-taxability endpoint is called for each address to perform this check. This action typically manifests as a button labeled Run Check on the Chargebee UI.

  • When the taxable address for any customer is added or updated.

Estimating taxes

POST /tax-estimate

Chargebee calls this endpoint before an invoice (or invoice estimate) is generated so that taxes can be added to it.

Submitting invoices and credit notes

POST /invoices

POST /credit-notes

Chargebee uses the above endpoints to submit invoices and credit notes to the Tax SPI. This functionality enables you to reconcile taxes on invoices and credit notes with the amounts posted to the account of the tax authority. Implementing these endpoints is optional for tax providers but is recommended for those offering or generating tax reports.

The endpoints are invoked asynchronously when an invoice is closed and a credit note is created respectively.

Committing invoices and credit notes

POST /invoices/{invoiceId}/commit

POST /credit-notes/{creditNoteId}/commit

These endpoints finalize (or "commit") an invoice or credit note. After being finalized, no further changes should be allowed to the invoice or credit note. Chargebee asynchronously invokes these endpoints when the status of the invoice or credit note changes to a value that the merchant has preconfigured. It is optional to implement these endpoints.

Voiding invoices and credit notes

POST /invoices/{invoiceId}/void

POST /credit-notes/{creditNoteId}/void

These endpoints are called asynchronously whenever an invoice or credit note status changes to voided.

App publishing and support

You can publish your tax adapter service as an app on the Chargebee Marketplace. This allows multiple tenants (merchants) to discover and use your app. If you’re building the adapter for specific tenants, you can publish it as a private app so that it will receive requests from the specified tenants only.

For any help and support on setting up the service, do write to us at taxation@chargebee.com.

JSON Schema for Tax Provider

JSON (JavaScript Object Notation) is a widely used, text-based data format that is both simple and lightweight. It is commonly used for transmitting data between web applications and servers, and it can be easily read and maneuvered by humans and machines alike.

JSON Schema, on the other hand, is an official standard established by the Internet Engineering Task Force (IETF) that defines the structure and constraints of a JSON document. It provides a way to describe the expected properties and types of data for a given application, as well as the rules for how that data should be interacted with.

Given below is the Chargebee Tax Provider JSON Schema. By utilizing this JSON Schema, you can ensure that your tax provider data is accurately structured and compliant with the requirements of the Chargebee platform. This can help to improve the consistency and validity of your data and make it easier to integrate with other applications or systems.

{ "$schema":"http://json-schema.org/draft-06/schema#", "$ref":"#/definitions/ProviderCapabilitySchema", "definitions":{ "ProviderCapabilitySchema":{ "type":"object", "description":"The main schema that defines the structure of both Provider's production and sandbox capabilities.", "additionalProperties":false, "properties":{ "prod":{ "$ref":"#/definitions/CapabilityBody" }, "sandbox":{ "$ref":"#/definitions/CapabilityBody" } }, "required":[ "prod", "sandbox" ], "title":"ProviderCapabilitySchema" }, "CapabilityBody":{ "type":"object", "description":"Specifies the capabilities and configurations of the Provider for a given environment (e.g., production or sandbox).", "additionalProperties":false, "properties":{ "identity_configuration":{ "$ref":"#/definitions/IdentityConfiguration", "description":"Specifies Identity Configuration details of the Provider such as Logo url, description, compliance related details." }, "api_configuration":{ "$ref":"#/definitions/APIConfiguration", "description":"Specifies API configuration details of the Provider including the base URL and any necessary credentials." }, "capabilities":{ "$ref":"#/definitions/Capabilities", "description":"Specifies the capabilities supported by the Provider with additional details such as supported countries and currencies." }, "product_identifiers":{ "type":"array", "description":"Specifies the custom fields which the Provider supports for a product to perform any special actions such as applying Tax exempt for a product.", "items":{ "$ref":"#/definitions/Identifier" } }, "customer_identifiers":{ "type":"array", "description":"Specifies the custom fields which the Provider supports for a customer to perform any special actions such as applying Tax exempt for a customer.", "items":{ "$ref":"#/definitions/Identifier" } }, "supported_number_of_line_items":{ "type":"integer", "description":"Specifies the supported number of line items in an invoice or a credit note.", "examples": [1200] }, "version":{ "type":"string", "description":"Specifies the Semantic Versioning of the schema.", "examples":["1.0.0"] } }, "required":[ "api_configuration", "capabilities", "customer_identifiers", "identity_configuration", "product_identifiers", "supported_number_of_line_items", "version" ], "title":"Prod" }, "APIConfiguration":{ "type":"object", "description":"Specifies API configuration details of the Provider including the base URL and any necessary credentials.", "additionalProperties":false, "properties":{ "api_base_url":{ "type":"string", "description":"Specifies the Provider's Base URL.", "format":"uri", "qt-uri-protocols":[ "https" ], "examples": ["https://api.tax-provider.com/integrations/chargebee/api/v1"] }, "credential_configuration":{ "type":"array", "description":"Specifies the list of parameters that Provider needed for authentication & authorization.", "items":{ "$ref":"#/definitions/CredentialConfiguration" } } }, "required":[ "api_base_url", "credential_configuration" ], "title":"APIConfiguration" }, "CredentialConfiguration":{ "type":"object", "description":"Specifies the list of parameters that Provider needed for authentication & authorization.", "additionalProperties":false, "properties":{ "id":{ "type":"string", "description":"Specifies the parameter name that Provider expects.", "examples": ["api_key"] }, "name":{ "type":"string", "description":"Specifies the name to be displayed for the provider app in Chargebee platform.", "examples": ["Tax Provider API Key"] }, "type": { "type": "string", "description": "Specifies the type of the parameter.", "enum": ["text", "password"] }, "is_sensitive":{ "type":"boolean", "description":"Specifies the the case sensitivity of the parameter." }, "is_required":{ "type":"boolean", "description":"Specifies if the Provider expects this parameter mandatorily." } }, "required":[ "id", "is_required", "is_sensitive", "name", "type" ], "title":"CredentialConfiguration" }, "Capabilities":{ "type":"object", "additionalProperties":false, "properties":{ "supported_countries":{ "type":"array", "description":"Specifies the supported countries(ISO 3166 alpha-2 country code format) by the Provider for all the capabilities such as Tax calculation, syncing invoices/credit notes, TIN validation. If supported countries are different for each capabilities, it shall be specified under the respective capability.", "items":{ "type":"string" }, "examples": ["US", "EU"] }, "supported_currencies":{ "type":"array", "description":"Specifies the supported currencies(ISO 4217 format) by the Provider for all the capabilities such as Tax calculation, syncing invoices/credit notes. If supported currencies are different for each capabilities, it shall be specified under the respective capability.", "items":{ "type":"string" }, "examples": ["USD"] }, "can_validate_shipping_address":{ "type":"boolean", "description":"Specifies if the full address validation is supported. Even if this is not supported by the Provider, it is mandatory that basic/partial address validation must be suppported." }, "can_sync_invoices":{ "type":"boolean", "description":"Specifies if invoices can be synced to the Provider." }, "can_sync_credit_notes":{ "type":"boolean", "description":"Specifies if credit notes can be synced to the Provider." }, "can_support_currency_inclusive_of_taxes":{ "type":"boolean", "description":"Specifies if tax inclusivity is supported." }, "is_consistent_pricing_supported":{ "type":"boolean", "description":"Specifies if consistent pricing is supported." }, "can_have_product_identifiers":{ "type":"boolean", "description":"Specifies if product custom fields are supported." }, "can_have_customer_identifiers":{ "type":"boolean", "description":"Specifies if customer custom fields are supported." }, "tax_calculation_capabilities":{ "$ref":"#/definitions/TaxCalculationCapabilities", "description":"Specifies details on tax calculation capability." }, "invoice_sync_capabilities":{ "$ref":"#/definitions/SyncCapabilities", "description":"Specifies details on invoice sync capability." }, "credit_note_sync_capabilities":{ "$ref":"#/definitions/SyncCapabilities", "description":"Specifies details on credit note sync capability." }, "tin_validation_capabilities":{ "$ref":"#/definitions/TinValidationCapabilities", "description":"Specifies details on TIN validation capability." } }, "required":[ "can_have_customer_identifiers", "can_have_product_identifiers", "can_support_currency_inclusive_of_taxes", "can_sync_credit_notes", "can_sync_invoices", "can_validate_shipping_address", "credit_note_sync_capabilities", "invoice_sync_capabilities", "is_consistent_pricing_supported", "supported_countries", "supported_currencies", "tax_calculation_capabilities" ], "title":"Capabilities" }, "SyncCapabilities":{ "type":"object", "description":"Specifies details on sync capability for an entity such as invoice, credit note.", "additionalProperties":false, "properties":{ "is_sync_supported":{ "type":"boolean", "description":"Specifies if sync is supported." }, "can_commit":{ "type":"boolean", "description":"Specifies if commit operation is supported. Commit operation can be described as an entity once commited cannot be modified." }, "can_delete":{ "type":"boolean", "description":"Specifies if delete operation is supported on the entity." }, "can_void":{ "type":"boolean", "description":"Specifies if void operation is supported on the entity." }, "supported_countries":{ "type":"array", "description":"Specifies the supported countries(ISO 3166 alpha-2 country code format) for this capability.", "items":{ "type":"string" } }, "applicable_sync_types": { "type": "array", "description": "Specifies the supported sync types to perform for an entity from Chargebee platform to the provider.", "items": { "oneOf": [ { "type": "string", "enum": ["DONT_SYNC"], "description": "Do not sync the entity." }, { "type": "string", "enum": ["SYNC_ONLY_PAID"], "description": "Sync only PAID Invoices or ADJUSTED/REFUNDED Credit notes." }, { "type": "string", "enum": ["SYNC_ALL"], "description": "Sync all the entities." }, { "type": "string", "enum": ["DONT_COMMIT"], "description": "Do not commit the entity." }, { "type": "string", "enum": ["COMMIT_ONLY_PAID"], "description": "Commit only PAID Invoices or ADJUSTED/REFUNDED Credit notes." }, { "type": "string", "enum": ["COMMIT_ALL"], "description": "Commit all entities." } ] } } }, "required":[ "can_commit", "can_delete", "can_void", "is_sync_supported", "supported_countries" ], "title":"SyncCapabilities" }, "TinValidationCapabilities":{ "type":"object", "additionalProperties":false, "properties":{ "is_supported":{ "type":"boolean", "description":"Specifies if the capability is supported." }, "batch_configuration":{ "type":"object", "description": "Specifies batch TIN Validation related configurations.", "properties":{ "is_supported":{ "type":"boolean", "description":"Specifies if the operation is supported." }, "batch_size":{ "type":"integer", "description":"Specifies the supported batch size.", "examples":[100] } }, "required":[ "is_supported" ] }, "async_configuration":{ "type":"object", "description": "Specifies asynchronous way of performing TIN Validation related configurations.", "properties":{ "is_supported":{ "type":"boolean", "description":"Specifies if the operation is supported." } }, "required":[ "is_supported" ] }, "supported_countries":{ "type":"object", "description":"Specifies the supported countries(ISO 3166 alpha-2 country code format) and country specific configuration.", "patternProperties":{ "^[A-Z]{2}$":{ "type":"object", "properties":{ "reference_number":{ "type":"object", "description":"Specifies about reference number configuration. Reference number is the number that provider provides as a proof of the TIN Validation.", "properties":{ "is_supported":{ "type":"boolean", "description":"Specifies if the reference number is supported." }, "display_name":{ "type":"string", "description":"Specifies the name for the reference number attribute to display in Chargebee Platform." } }, "required":[ "is_supported", "display_name" ] }, "customFields":{ "type":"array", "description":"Specifies the custom fields that are required or supported for the country.", "items":{ "$ref":"#/definitions/Identifier" } } }, "required":[ "reference_number" ] } }, "examples" : [{ "US": { "reference_number": { "is_supported": true, "display_name": "Reference number" }, "customFields": [{ "external_id": "email_address", "display_name": "Email Address", "is_mandatory": true, "is_default": false, "field_type": "text" }, { "external_id": "state_code", "display_name": "State code", "is_mandatory": true, "is_default": false, "field_type": "text" } ] } }], "additionalProperties":false } }, "required":[ "is_supported", "batch_configuration", "async_configuration", "supported_countries" ] }, "TaxCalculationCapabilities":{ "type":"object", "description":"Specifies the configuration for the tax calculation.", "additionalProperties":false, "properties":{ "accept_invalid_tax_reg_numbers":{ "type":"boolean", "description":"Specifies if invalid tax registration numbers are accepted." }, "supportedNumberOfLineItems":{ "type":"integer", "description":"Specifies the supported number of line items." } }, "required":[ "accept_invalid_tax_reg_numbers", "supportedNumberOfLineItems" ], "title":"TaxCalculationCapabilities" }, "Identifier":{ "type":"object", "description":"Specifies the custom identifiers for the entities such as Product and Customer.", "additionalProperties":false, "properties":{ "external_id":{ "type":"string", "description":"Specifies the parameter name Provider expects.", "example": ["productCode"] }, "display_name":{ "type":"string", "description":"Specifies the name of the parameter to be displayed in Chargebee platform.", "example": ["Product Code"] }, "is_mandatory":{ "type":"boolean", "description":"Specifies if the parameter is mandatory." }, "is_default":{ "type":"boolean", "deprecated": true, "description":"Specifies if the parameter has a default value." }, "field_type":{ "type":"string" } }, "required":[ "display_name", "external_id", "field_type" ], "title":"Identifier" }, "IdentityConfiguration":{ "type":"object", "description":"Specifies Identity Configuration details of the Provider such as Logo url, description, compliance related details.", "additionalProperties":false, "properties":{ "id":{ "type":"string", "description":"Specifies the identifier of the Provider" }, "Provider_type":{ "type":"array", "description":"Specifies the list of the features that the Provider supports. Provider may support Tax or Tax Identification Number(TIN) Validation capabilities or both.", "items":{ "type":"string", "enum":[ "TAX", "TIN_VALIDATION" ] } }, "display_name":{ "type":"string", "description":"Specifies the display name of the Provider in Chargebee platform.", "examples":["Anrok"] }, "logo_url":{ "type":"string", "description":"Specifies the logo url of the Provider to display in Chargebee platform.", "format":"uri", "qt-uri-protocols":[ "https" ], "qt-uri-extensions":[ ".png" ] }, "primary_description":{ "type":"array", "description":"Specifies the primary description of the Provider.", "items":{ "type":"string" } }, "secondary_description":{ "type":"array", "description":"Specifies the secondary description of the Provider.", "items":{ "type":"string" } }, "signup_url":{ "type":"string", "description":"Specifies the url for the merchant to sign up with the provider.", "format":"uri", "qt-uri-protocols":[ "https" ] }, "consent_policy_url":{ "type":"string", "description":"Specifies the url about the consent related details of the Provider for the merchant." }, "privacy_policy_url":{ "type":"string", "description":"Specifies the url about the privacy related details of the Provider for the merchant." }, "terms_of_service_url":{ "type":"string", "description":"Specifies the url about the terms of services related details of the Provider for the merchant.", "format":"uri", "qt-uri-protocols":[ "https" ] }, "documentation_url":{ "type":"string", "description":"Specifies the url about the documentation details of the Provider for the merchant.", "format":"uri", "qt-uri-protocols":[ "https" ], "qt-uri-extensions":[ ".html" ] }, "support_email":{ "type":"string", "description":"Specifies the support email of the Provider to reach out to incase of queries or escalations.", "format":"email" } }, "required":[ "consent_policy_url", "display_name", "documentation_url", "id", "logo_url", "primary_description", "privacy_policy_url", "secondary_description", "signup_url", "support_email", "terms_of_service_url" ], "title":"IdentityConfiguration" } } }

Â