1. Introduction to e-Invoicing

Electronic invoicing, or e-Invoicing, refers to the structured electronic exchange of invoice data between a supplier, buyer, and tax authority in a government-approved digital format. Unlike a PDF invoice sent via email, an e-Invoice is generated in a machine-readable format such as XML, UBL, or CII and transmitted through a mandated government platform or accredited network.

Many countries across the EU, Latin America, and Asia Pacific have introduced Continuous Transaction Controls and real-time reporting systems. Under these frameworks, invoices and credit notes must be submitted to or cleared by the tax authority before they are considered legally valid.

For businesses using Chargebee to generate invoices and credit notes, compliance with local e-Invoicing mandates is critical in regulated jurisdictions. An invoice created in Chargebee may not be legally recognized unless it is successfully transmitted through the appropriate e-Invoicing network.

Benefits of Avalara ELR Integration

The Chargebee integration with Avalara ELR enables you to:

• Transmit outbound invoices and credit notes to supported tax authorities
• Comply with country-specific schema and formatting requirements
• Automate regulatory reporting workflows
• Reduce manual submission and compliance risk

Failure to comply with local mandates can result in document rejection, penalties, and disruption to revenue recognition.

2. What is Avalara ELR?

Avalara E-Invoicing and Live Reporting, or Avalara ELR, is Avalara’s global solution for electronic invoicing compliance and real-time tax reporting. It enables businesses to generate, validate, transform, and transmit electronic invoices to tax authorities or accredited networks in jurisdictions where e-Invoicing is mandated.

Avalara ELR supports multiple country-specific mandates, transmission models, and document formats. It handles schema validation, format conversion, and communication with government platforms.

Within the Chargebee marketplace integration, Avalara ELR acts as the compliance layer between Chargebee and the relevant tax authority. Chargebee generates the commercial document, and Avalara transforms and routes it according to the selected country mandate.

3. Setting Up Avalara ELR in Chargebee

This section explains how to connect your Avalara ELR account to Chargebee and configure outbound e-Invoicing workflows for invoices and credit notes.

The integration ensures that invoices and credit notes generated in Chargebee are transmitted to Avalara ELR, which then validates, transforms, and routes them to the appropriate tax authority or clearance network based on the configured country mandate.

Prerequisites

Before beginning configuration, ensure the following:

• You have an active Avalara ELR account.

• The required country mandates are activated in Avalara.

• You have generated:

  • Avalara Client ID

  • Avalara Client Secret

  • Avalara Webhook Secret

• Your legal entity details in Chargebee are accurate and up to date.

Step 1: Connect Avalara from the Chargebee App Marketplace

To initiate the integration:

1. Navigate to Apps from the left-hand navigation panel.

2. Open the App Marketplace.

3. Search for Avalara E-Invoicing and Live Reporting (ELR).

4. Click Connect.

You will be prompted to authenticate your Avalara account by providing secure credentials.

Authentication Details

Enter the following:

• Client ID: Identifies your Avalara ELR account.

• Client Secret: Used to securely authenticate API communication.

• Webhook Secret: Configure webhook in Avalara using the webhook URL generated by Chargebee and enter the same Avalara Webhook Secret here.

  • Here’s how you can create a Webhook in Avalara

These credentials establish a secure, API-based connection between Chargebee and Avalara ELR.

Please check the checkbox to acknowledge that Avalara E-Invoicing may store the customer and subscription data before proceeding to click on the ‘Authenticate’ button.

Once authentication succeeds:

• Chargebee can fetch supported mandates, document formats, and Company IDs from Avalara.

• Avalara can push status updates such as acceptance, rejection, or clearance results.

If authentication fails, verify credential accuracy and confirm that API access is enabled in your Avalara account.

Testing connection

To manually test the connection (e.g., after network or credential changes), navigate to the Avalara ELR integration settings, click Update.

Please check the checkbox to acknowledge that Avalara E-Invoicing may store the customer and subscription data before proceeding to click on the ‘Authenticate’ button.

This re-authentication validates the API key, network access, and authorization. Success confirms an active connection; failure provides an error message for invalid credentials that needs to be updated accordingly.

Step 2: Organisation Address Configuration

Avalara ELR uses the legal origin address of your business when transmitting documents to tax authorities.

In Chargebee, this is sourced from:

Settings > Configure Chargebee > Business Profile

The organisation address configured here is used as:

• Supplier origin information

• Legal entity details in the structured e-Invoice

• Reference data for country-level compliance validation

It is critical that this address matches the registered legal entity associated with your Avalara Company configuration.

If this information is incorrect:

• Documents may fail validation.

• Tax authority submissions may be rejected.

• Regulatory non-compliance risk increases.

Always verify and update the Business Profile before proceeding further.

Step 3: Avalara Company ID Configuration (Multi-Entity Support)

If you operate multiple business entities within Chargebee, each entity must be mapped to a corresponding Company in Avalara ELR.

This mapping ensures:

• Documents are submitted under the correct legal entity.

• Country-specific mandates are applied correctly.

• Regulatory reporting aligns with the right tax registration.

To configure:

1. Open the Avalara app settings.

2. Select Company ID Configuration.

3. Choose the Chargebee Business Entity.

4. Select the corresponding Avalara E-Invoicing Company ID.

Important behavior:

• The Company ID dropdown is dynamically fetched from Avalara via API.

• Only Companies configured within your Avalara ELR account are available.

• Each Chargebee entity must map to one Avalara Company.

If a Company is missing from the dropdown:

• Confirm it exists in Avalara.

• Verify that your credentials have access to it.

4. E-Invoicing Configuration by Country

After connecting Avalara, country-level configuration determines:

• Where e-Invoicing applies

• Which network or mandate is used

• Which document types are transmitted

Navigate to:

Settings → Configure Chargebee → E-Invoicing

Step 1: Adding Countries

Click + Add Country to select jurisdictions where e-Invoicing is required.

You should add countries based on:

• Where your taxable customers are located

• Where your entity has VAT registration

• Where e-Invoicing mandates are legally enforced

Multiple countries can be configured independently.

Each country configuration is isolated, meaning:

• Routing logic is country-specific

• Models are selected per country

• Documents are configured per country

Step 2: Selecting the Provider

For each country:

1. Click Manage.

2. Select Avalara E-invoicing.

3. Click Use This Provider.

Only providers connected through the App Marketplace will appear.

This step links the country configuration to Avalara as the compliance engine.

Step 3: Selecting the Model (Mandate)

Each country may support multiple transmission networks or regulatory frameworks.

In Chargebee, these are referred to as Models.

In Avalara terminology, they are referred to as Mandates.

Examples may include:

• Clearance models

• Reporting models

• Network-based frameworks such as PEPPOL

These represent the specific regulatory channel through which documents must be transmitted.

Important:

• Mandates must first be activated in your Avalara ELR account.

• If a mandate is not activated, it will appear disabled in Chargebee.

• Disabled mandates cannot be selected.

This prevents misconfiguration and ensures that Chargebee only allows routing to legally active networks.

Once selected, the Model becomes the regulatory framework under which documents will be validated and transmitted.

5. Adding Documents for Transmission

After selecting a Model, you must define which outbound documents should be sent to Avalara.

Chargebee supports outbound:

• Invoices

• Credit Notes

• Application Response

You must explicitly select document types and formats.

Click Add Documents under the selected Model.

Avalara dynamically returns supported formats based on:

• Country

• Mandate

• Document category (B2B, B2G, B2C)

Common formats include:

• UBL

• XML

• CII and more

The availability of formats depends on Avalara’s support for that specific mandate.

You may configure different document types for different customer categories.

Documents cannot be enabled until:

• Routing Conditions are defined

• Field Mapping is completed

6. Customer Type Categorization

E-Invoicing mandates often differentiate between:

• B2B transactions

• B2G transactions

• B2C transactions

Chargebee allows you to categorize documents accordingly. You may determine customer type using:

Option 1: VAT Number Logic

If VAT Number is present → treat as B2B

If VAT Number is absent → treat as B2G or B2C based on internal logic

This approach relies on tax identification data.

Option 2: Custom Field

Create a structured custom field on the Customer object.

Example:

Field: Customer Type

Type: Dropdown

Values: B2B, B2G, B2C

This method provides explicit classification and reduces ambiguity.

Your routing logic can then use this field as a condition.

7. Routing Conditions

Routing Conditions determine when a document qualifies for transmission to Avalara.

This logic acts as a filter that evaluates:

• Document attributes

• Customer attributes

• Country data

• Custom fields

The default condition includes:

Taxable Address Country

You may add:

• Additional conditions within a group

• Multiple condition groups

• Nested subgroups

Operator behavior:

• AND requires all conditions to be satisfied.

• OR allows alternate qualification paths.

This flexibility enables complex compliance logic, such as:

• Routing only B2B invoices above a certain threshold

• Excluding specific product categories

• Separating domestic and cross-border transactions

Mandatory: Document Type Filter

You must explicitly add:

Document Type equals Invoice

or

Document Type equals Credit Note

This ensures:

• Invoice workflows apply only to invoices.

• Credit note workflows apply only to credit notes.

• No overlap occurs between routing rules.

If omitted, document classification may be incorrect.

Routing Constraints

• No two documents within the same country can share identical Routing Conditions.

• You may save progress and complete configuration later.

• After routing is defined, click Next to proceed to Field Mapping.

8. Field Mapping

Field Mapping is the most critical configuration step in the Avalara ELR integration. This step determines how structured data from Chargebee invoices and credit notes is transformed into the format required by Avalara and the relevant tax authority network.

Without correct field mapping:

• Documents will fail schema validation.

• Mandatory regulatory fields may be missing.

• Submissions may be rejected by Avalara or the network.

Field Mapping ensures that each required document field is populated with the correct data from Chargebee.

Understanding Document Fields

Avalara expects documents in structured formats. Each document contains predefined fields that must be populated according to the selected mandate.

These fields are categorized into three types:

1. Required Fields

Required fields are mandatory for submission.

If even one required field is missing or improperly mapped:

• The document cannot be submitted.

• The configuration cannot be completed.

• The “Finish” button remains disabled.

These fields typically include:

• Invoice identifiers

• Issue dates

• Supplier and buyer details

• Tax totals

• Legal monetary totals

2. Conditional Fields

Conditional fields become mandatory depending on business logic.

For example:

• Tax-related fields may only be required if tax is applied.

• Reverse charge information may be required only if VAT is zero-rated under specific rules.

Chargebee enforces mapping for conditional fields if the logical dependency applies.

3. Optional Fields

Optional fields are not mandatory for submission. However, mapping them is strongly recommended.

Some networks may perform additional validations and expect supplementary data. Providing optional fields reduces the risk of rejection and improves interoperability across networks.

Viewing Field Descriptions

When configuring mapping:

• Hover over any UBL field.

• A tooltip description appears explaining:

  • What the field represents.

  • When it is required.

  • Example values.

This contextual guidance helps you determine which Chargebee object and field should be mapped.

Mapping Types

Each field can be mapped using one of three mapping types:

1. Field

2. Constant

3. Derivative

1. Field Mapping Type

Field mapping allows you to dynamically pull data from a Chargebee object.

You can select:

• Chargebee object (Invoice, Customer, Subscription, etc.)

• A specific field within that object

Example:

Document Field: Invoice.cbc:DueDate

Chargebee Mapping: Invoice > Invoice Due Date

This means:

• Every time an invoice is generated,

• Chargebee retrieves the invoice due date dynamically,

• That value is transmitted to Avalara for that field.

This is the most commonly used mapping type because it directly reflects transactional data.

2. Constant Mapping Type

Constant mapping allows you to assign a static value. The same value will be sent for every document generated under that configuration.

Example:

Document Field: Invoice.cbc:InvoiceTypeCode

Constant Value: 380

Under PEPPOL standards, 380 represents a commercial invoice.

Use Constant mapping when:

• The value does not change across documents.

• The mandate requires a fixed code.

• The network specification defines a mandatory constant identifier.

3. Derivative Mapping Type

Derivative mapping is used for advanced logic. It allows you to write expressions using Google’s CEL expression language to compute values dynamically.

This is required when:

• A Document field depends on multiple invoice line attributes.

• Tax codes vary based on line-level tax applicability.

• Conditional classification logic is needed.

Example:

For a Document field such as ClassifiedTaxCategory, you may need to:

• Evaluate tax rates on individual line items.

• Map different categories based on whether VAT is standard-rated, zero-rated, exempt, or reverse charge.

Selecting Derivative opens a script editor where you can:

• Define custom expressions

• Use operators

• Use macros

• Reference variables

The “Check Syntax” button validates your expression before saving.

This ensures:

• Proper syntax

• No runtime parsing errors

• Safer submission logic

Completing Field Mapping

Before you can click Finish:

• All Required fields must be mapped.

• All applicable Conditional fields must be mapped.

Once completed:

1. Click Finish to save configuration.

2. Enable the document workflow.

Important:

Configuration alone does not activate processing.

You must explicitly click Enable for the document type to begin transmission.

9. Submitting Documents

Once configuration and enablement are complete, submission of Invoices & Credit Notes becomes automatic. Chargebee listens to the following events to trigger the document submission:

1. Invoice generated
2. Credit note created

Chargebee evaluates the document against your configured Routing Conditions.

If a document matches:

• The document is immediately sent to Avalara ELR.

• Avalara validates the document.

• The document is routed to the appropriate mandate network.

Application Response

In certain e-Invoicing mandates, submission of an invoice or credit note alone is not sufficient to complete the legal transaction lifecycle.

Some regulatory frameworks require the buyer to formally acknowledge, accept, or reject the received e-Invoice. This acknowledgment is transmitted as a structured electronic message known as an Application Response.

What is an Application Response?

An Application Response is a structured electronic document that communicates the status of a previously submitted e-Invoice.

It is typically required in:

• PEPPOL-based networks

• B2G frameworks

• Clearance models that enforce buyer-side validation

The Application Response:

• References the original invoice

• Indicates buyer acceptance, rejection, or other defined status

• May include reason codes or explanatory comments

Without an Application Response in certain mandates:

• The invoice may not be considered fully accepted

• Payment timelines may not formally begin

• Regulatory audit trails may remain incomplete

For merchants operating in jurisdictions where buyer acknowledgment is mandatory, Application Responses are essential to maintain compliance and complete the transaction lifecycle.

How Application Response Works in Chargebee

Unlike invoices and credit notes, which are automatically triggered on creation, Application Responses are triggered manually via UI or API.

They can only be sent for documents that have already been successfully processed and accepted by the network.

To send an Application Response:

1. Navigate to the relevant document

2. Locate the E-Invoice card.

3. Click the ellipsis (three dots).

4. Select Send Response.

You will be prompted to:

• Select a Status Code from a predefined dropdown.

• Enter a Description comment.

Sending e-Invoices and Application Responses via API

E-invoices and Application Responses can also be sent programmatically via the send_einvoice API endpoint.

To Send an E-Invoice for Invoice or Credit Note:

Use the send_einvoice API for the respective document with a POST request. For detailed API documentation, refer to the links below:

• Invoice: Send an e-invoice for invoices
• Credit Note: Send an e-invoice for credit notes

To Send an Application Response via API:

An Application Response can be sent using the same send_einvoice endpoint for an invoice or credit note, by including the following extra parameters in the request body.

response_status

Description:

Indicates the buyer’s business response to a previously submitted e-invoice or credit note. This field represents a network-agnostic, canonical status that captures the buyer’s intent (for example: accepted, rejected, or requires clarification). Chargebee uses this value to derive and send the appropriate network-specific response document or status update (such as Peppol Invoice Response) based on the configured e-invoicing network and country.

Supported values are designed to be extensible across multiple networks and may include:

• ACCEPTED – The document is fully accepted by the buyer.
• REJECTED – The document is rejected by the buyer.
• QUERY – The buyer requires clarification or has raised a dispute.
• CONDITIONALLY_ACCEPTED – The document is accepted with conditions (if supported by the network).
• MESSAGE_ACKNOWLEDGEMENT - The response has been acknowledged by the receiving entity.
• IN_PROCESS - The response is being processed by the receiving entity.
• PAID - The buyer has confirmed that the document has been paid.

Additional statuses may be introduced in the future as support expands to other networks and country-specific workflows.

Notes:

• This is a business-level response, not a technical acknowledgment.
• The exact mapping of this value to network-specific statuses is handled internally by Chargebee.
• Not all statuses may be supported by every network; unsupported values may result in validation errors.

response_message

Description:

A human-readable message providing additional context for the specified response_status. This message is typically used to communicate the reason for a response (for example, rejection or query) and may be shared with trading partners depending on the capabilities of the underlying e-invoicing network. Chargebee may use this message, along with configured rules, to derive structured reason codes required by specific networks.

Examples:

• "Invalid GSTIN provided"
• "Invoice total does not match purchase order"
• "Please provide supporting documents for this charge"

Notes:

• This field is intended for informational and communication purposes and is not guaranteed to be preserved verbatim across all networks.
• Structured reason codes (if required by a network) are derived internally based on configured mappings and are not required to be provided in this API.
• It is recommended to provide clear and concise messages to improve downstream visibility and reconciliation.

response_document_type

Description:

Specifies the type of response document or message that Chargebee should generate and transmit for the given e-invoice or credit note. This field represents a network-agnostic abstraction of the response artifact, allowing Chargebee to map the request to the appropriate network-specific document type or message format based on the configured e-invoicing network and country.

For example:

• In Peppol, this corresponds to an ApplicationResponse document (Invoice Response profile).
• In other networks, this may map to status update messages, application advice, acknowledgments, or dispute documents.

Supported values include:

• APPLICATION_RESPONSE – Generates a business-level response document (for example, Peppol Invoice Response) to communicate acceptance, rejection, or query.

Additional document types may be introduced in the future as support expands to other networks and country-specific workflows.

Notes:

If not provided, Chargebee may determine the appropriate response document type automatically based on the configured network and context.

Not all document types are supported by every network; unsupported combinations may result in validation errors.

• This field controls the format and protocol of the response, while response_status captures the business intent of the response.

Example cURL for Application Response:

curl --location 'https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/send_einvoice' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {site_api_key}:' \
--data-urlencode 'response_document_type=APPLICATION_RESPONSE' \
--data-urlencode 'response_status=REJECTED' \
--data-urlencode 'response_message=rejecting the invoice'

Note: The below fields are the same between what is shown in mapping vs field names in API:

• Einvoice Artifact Code - response_status
• Einvoice Artifact Type - response_document_type
• Einvoice Artifact Description - response_message

Status Code and Network Transformation

The Status Code selected in Chargebee represents a business-level outcome, such as Accepted, Rejected and a few other options.

However, regulatory networks require standardized codes defined by the mandate.

The selected Status Code is therefore:

• Transformed into the required network-specific code

• Mapped using the configured Derivative field mapping logic

This ensures:

• Compliance with mandate-specific code lists

• Proper translation into compliant Application Response format

• Correct interpretation by the receiving network

For example, a business-level “Accepted” selection may be transformed into a specific PEPPOL response code through the derivative expression configured in Field Mapping.

E-Invoice Statuses

Each invoice or credit note displays an E-Invoice card indicating the submission status.

The possible statuses are:

Scheduled

The document is queued for submission to Avalara.

This typically appears immediately after invoice creation.

In Progress

The document is undergoing:

• Schema validation

• Format transformation

• Network transmission

This reflects active communication between Chargebee and Avalara.

Success

The document has:

• Passed validation

• Been accepted by the network

• Been successfully processed by the tax authority

The invoice record will reflect successful compliance.

Failed

The document failed due to:

• Validation errors in field mapping

• Missing required data

• Incorrect classification

• Network rejection

Failure details are visible within the E-Invoice card.

Additionally, if the user wants to know the responseKey or responseValue information, it will be present as part of the Activity log and in the Invoice_updated event.

10. Downloading Documents

For documents in Success status:

• Click the ellipsis (three dots).

• Download the available structured formats.

Depending on the mandate, this may include:

• XML

• UBL + XML

• Network-specific response files

These files represent the legally transmitted e-Invoice format.

In addition to fetching e-Invoices via the UI, Chargebee offers a programmatic solution using the Download e-invoice API. This lets you seamlessly integrate e-Invoice retrieval in various formats, automating the process for large-scale operations, archiving, or integration with other systems.

Troubleshooting Failed Documents

For documents in Failed status:

1. Click the ellipsis.

2. Download the XML file.

This file contains:

• The raw payload sent to Avalara.

• All mapped field values.

• The exact structured data transmitted.

By reviewing this file, you can:

• Identify missing values.

• Validate tax classifications.

• Confirm whether custom fields were populated.

• Compare expected vs actual data.

Resending Documents

After correcting:

• Field mapping

• Customer data

• Tax configuration

• Invoice data

You can click Resend E-Invoice to re-trigger submission.

This avoids:

• Creating duplicate invoices

• Manual recreation of documents

The system re-evaluates the document against the updated configuration and attempts submission again.

11. Email Notification Delivery

In addition to transmitting invoices and credit notes to tax authorities through Avalara ELR, you may also choose to automatically deliver the processed e-Invoice documents to your customers via email.

Chargebee leverages its existing Email Notification framework to attach the structured e-Invoice files once they have been successfully processed and returned by Avalara.

To configure this, navigate to the respective email notification, such as the Invoice Receipt notification, via Settings > Configure Chargebee > Email Notifications and ensure the setting ‘Attach invoice or e-Invoice if available’ is enabled:

When this setting is enabled, Chargebee automatically attaches the structured e-Invoice file to the relevant system email after the document has been successfully processed by Avalara and accepted by the network. The attachment includes the legally valid electronic format(s) returned.