Skip to main content

​
Introduction

Chargebee is a subscription management and billing platform designed for businesses that rely on recurring revenue. It automates tasks like subscription billing, invoicing, payment processing, and revenue recognition. Invopop’s Chargebee app lets you issue locally compliant electronic invoices and credit notes from Chargebee.

​
How it works

The Invopop Chargebee app will subscribe to new incoming invoices and credit notes. When a new document is received, it’ll be converted into GOBL, and stored in your Invopop workspace. Once an invoice or credit note is stored, the app will create a job on the configured workflow. Any updates and, importantly, error messages will be posted to Chargebee automatically, in the comment section of the invoice or credit note. We also recommend configuring workflows to send notifications via Slack or email to ensure any issues can be addressed quickly.
chargebee invoice

​
Setup

This guide assumes that you already have a Chargebee site configured and using Product Catalog 2.0. Sites created after May 05, 2021, will have this version enabled by default. If your site was created before this date, you may need to migrate to Product Catalog 2.0. More details here.
1

Create a Supplier

First we need to store the details of the supplier (the owner of the Chargebee account) in Invopop:
  1. In the console, navigate to “Contacts” → “Suppliers” and tap “New supplier”.
  2. Add the company’s contact details, including the name and tax code.
  3. If you’re issuing invoices from a region that requires special fields, please contact Invopop support for assistance.
  4. Save the document.
Note that when generating invoices, the app merges the supplier information in Invopop with the business profile data in Chargebee, giving precedence to the data from Chargebee.
2

Prepare a Workflow

Chargebee Basic PDF workflow

This workflow syncs with Chargebee and generates a basic PDF.

Chargebee ZUGFeRD

This workflow syncs with Chargebee, and generates a ZUGFeRD XML and PDF.
3

Connect the Chargebee app

You are now ready to connect and configure the Chargebee app itself. Go to Configuration → Apps in the Invopop console. Find the Chargebee app, then click on Connect. The app will be added to the list of active apps. Click on the app’s Configure button. You’ll see a form with the following fields:
  • Chargebee Site: The identifier of your Chargebee site. It is the part of the URL when you log in to Chargebee before the .chargebee.com domain. For example, if your URL is https://my-site.chargebee.com, your site is my-site.
  • Chargebee API Key: The API key used to access Chargebee. Go to “Settings” → “Configure Chargebee” → “API Keys” in the Chargebee UI to create one. Keep in mind that the used API must be a Full-Access Key.
  • Supplier: The supplier that will issue the invoices. You can select the one you created earlier.
  • Workflow: The workflow that will process the invoices. You can select the one you created earlier.
  • Ignore Chargebee’s invoice codes: If true, the app will ignore the invoice numbers set by Chargebee and let the workflow assign them instead. In special cases, such as Portugal and Colombia, invoice codes are regulated, and this setting should be set to true.
Some countries require specific codes set on tax-exempt invoices. If you’re in one of these countries, you’ll see the following fields:
  • Exemption Code (Generic): The local code to be used by default on tax-exempt invoices.
  • Exemption Code (Exports): The local code to be used by default on tax-exempt invoices for exports.
  • Exemption Code (Reverse Charge): The local code to be used by default on tax-exempt invoices for reverse charge.
Please note that those are the default exemption codes that will be set depending on the Chargebe exemption reason. If you need specific codes used for specific tax-exempt items, item prices, subscriptions, or customers, you can assign them as extensions (see next step).After saving the configuration, the page will provide a URL to set up a webhook in Chargebee. Save the URL, we’ll complete the setup in a later step.
4

Enter extension data

To generate valid invoices, most tax regimes require the issuer to provide custom data specific to that regime. GOBL provides mechanisms such as extensions, identities, or inboxes to carry that custom data. Please refer to the specific regime documentation to determine what is required and available in each regime.To enter this data in Chargebee, you can either configure custom fields or attach metadata to any of these entities: Customer, Plan Item, Plan Item Price, Action Item, Action Item Price, Charge Item, Charge Item Price, and Subscription.The keys of these metadata or custom fields need to have a specific prefix and include the extension, identity, or inbox key to be properly mapped to GOBL. Refer to the Custom Data section below for the full list of prefixes.For example, to set the customer’s mx-cfdi-fiscal-regime extension, you must add a custom field to the Customer entity with the API name: cf_gobl_mx_cfdi_fiscal_regime (note that, being a custom field, dashes in the original extension key are replaced by underscores). You can create it in Settings → Configure Chargebee → Custom Fields:
New Chargebee custom field
Alternatively, you could set it as Customer metadata using the gobl-customer-mx-cfdi-fiscal-regime key (note that dashes, instead of underscores, are used in the metadata key):
{
  "gobl-customer-mx-cfdi-fiscal-regime": "601"
}
5

Set up a webhook

After saving the configuration in Step, the page provided a URL to set up a webhook in Chargebee and trigger the import process. To do this, go to Settings → Configure Chargebee → Webhooks and create a new webhook with the provided URL.
Chargebee webhook form
Currently, Invopop listens to the “Invoice Generated” and the “Credit Note Created” events. However, we recommend that you configure your webhook to send “All events” to ensure that the integration will work in the future if we need to listen to other events.
You are now ready to start importing invoices and credit notes from Chargebee. The app will automatically create GOBL invoices and add them to your Invopop account. The invoices will then be processed using the workflow you set up.

​
Country-specific workflows

Depending on where your customers are located, you’ll need a different workflow to comply with local e-invoicing requirements. Below you’ll find the recommended workflow template, video walkthrough, and key custom fields for each supported country.
The metadata keys listed in the tables below follow the Chargebee metadata format (hyphens, no cf_ prefix). If you prefer to use custom fields instead, replace hyphens with underscores and add the cf_ prefix. For example, gobl-customer-inbox-peppol becomes cf_gobl_customer_inbox_peppol.

​
Controlling which customers are processed

By default, Invopop will process invoices for all your customers. If you only need to send e-invoices to a subset of them, you have two options — pick one, not both:
  • Allowlist: Create the cf_invopop_include custom field and set it to true for the customers you want to process and false for everyone else.
  • Denylist: Create the cf_invopop_exclude custom field and set it to true for customers you want to exclude. Everyone else will be processed by default.

​
🇧🇪 Belgium

Belgium uses the Peppol network for e-invoicing, which became mandatory in January 2026. The format used is Peppol BIS Billing UBL — the standard Peppol format — with one important Belgian-specific requirement: customers always expect to receive a PDF alongside the XML. To handle this, the workflow first downloads the existing Chargebee PDF and attaches it to the UBL document before sending it through Peppol. Required apps: Peppol, OASIS UBL
Before processing any invoices, you must register your supplier on the Peppol network through Invopop. See the Peppol guide for registration steps, and the Belgium Peppol guide for Belgium-specific details.

Chargebee Peppol

Syncs with Chargebee, downloads the PDF, looks up the customer’s Peppol participant ID, and sends via the Peppol network.

​
Participant ID lookup

Belgium enforces a standard set of Peppol participant ID schemes, all derived from the customer’s BCE number (Belgian company registration number). Since this number is typically available in Chargebee, the Lookup Participant ID step can automatically resolve the correct Peppol ID for each customer — no manual setup required in most cases. If you want to specify a Peppol ID manually for a particular customer (or override the lookup result), you can do so with the following custom field:
FieldMetadata keyCustom field keyExample
Peppol Participant IDgobl-customer-inbox-peppolcf_gobl_customer_inbox_peppol0208:0123456789

​
🇩🇰 Denmark

Denmark also uses the Peppol network and the same Peppol BIS Billing UBL format. However, unlike Belgium, Danish Peppol participant IDs come in a wide variety of schemes — GLN numbers, CVR numbers, and others — and they don’t all derive from the VAT number. This makes automatic lookup unreliable, so this workflow does not include a Lookup Participant ID step. You will need to set the Peppol ID directly on each customer as a custom field. If you do want to use automatic lookup for some customers, you can add the lookup step from the generic Peppol template. Required apps: Peppol, OASIS UBL
Before processing any invoices, you must register your supplier on the Peppol network through Invopop. See the Peppol guide for full registration steps.

Chargebee DK E-invoicing

Syncs with Chargebee and sends via Peppol to Danish customers, with automatic SEPA payment key handling.

​
Peppol Participant ID

Since there is no automatic lookup, the Peppol Participant ID must be set on each Danish customer before any invoices are processed. Use Chargebee’s bulk operations to back-populate this field across all your Danish customers before going live.
FieldMetadata keyCustom field keyExample
Peppol Participant IDgobl-customer-inbox-peppolcf_gobl_customer_inbox_peppol0088:5790000435968 (GLN)

​
SEPA payment key

The workflow includes one Denmark-specific step: Fixing bank-transfer details. If Chargebee sends a credit-transfer payment instruction on the invoice, this step automatically converts it to credit-transfer+sepa. Plain credit-transfer is not accepted in Denmark — the more specific SEPA variant is required. If the invoice has no payment instructions, the step is skipped. That’s the only difference from a standard Peppol workflow.

​
🇩🇪 Germany

Germany supports two structured e-invoicing formats: ZUGFeRD and X-Rechnung. Both are valid and supported by Invopop, but they serve different purposes and have different requirements.
  • ZUGFeRD is the most common choice for B2B invoicing. It has fewer validation constraints, which is why we always recommend embedding the XML inside a PDF — your customer receives a standard-looking PDF that also contains a machine-readable file. No per-customer setup is required.
  • X-Rechnung is primarily used for B2G invoicing (invoicing public authorities). It has stricter validations and more required fields, but if your customers require it, Invopop fully supports it.
Required apps: UN/CEFACT CII

​
Using Chargebee’s email delivery

For Invopop to update the invoice in Chargebee and trigger Chargebee’s own email delivery to your customer, you will need a Full Access API key. Beyond that, the following conditions must be met in Chargebee — if any of these are not in place, Chargebee will not forward the generated PDF (or XML, in the case of X-Rechnung) to your customer:
  1. The SEND_EINVOICE_NOTIFICATION feature flag must be enabled on your Chargebee site. Contact your Chargebee representative to enable this.
  2. Your Chargebee site’s business profile country must be set to Germany (or Spain — the two countries with PDF e-invoicing requirements).
  3. The cf_invopop_include custom field must be present and set to true on each customer you want to process.
  4. Invoice and credit note email notifications must be enabled on your Chargebee site.

Chargebee ZUGFeRD

Syncs with Chargebee, downloads the Chargebee PDF, generates a ZUGFeRD XML, and embeds both into a single hybrid PDF.
The ZUGFeRD workflow downloads the existing Chargebee PDF, generates the ZUGFeRD-compliant XML, and embeds the XML into the PDF to produce a single hybrid document. Chargebee then picks up the result and sends it to your customer. No per-customer configuration is required beyond having a valid German supplier set up in Invopop.
For a full walkthrough including required apps, email delivery setup, and custom fields, see the Germany section of the Chargebee guide.
Example Chargebee ZUGFeRD workflow
{
    "name": "Chargebee ZUGFeRD",
    "description": "Issue a ZUGFeRD Invoice in Germany with CB sync",
    "schema": "bill/invoice",
    "steps": [
        {
            "id": "ff581030-1943-11f0-b031-c71066181289",
            "name": "Import Chargebee document",
            "provider": "chargebee.import"
        },
        {
            "id": "bd7eb640-abd0-11ef-a013-91c68ca9f44b",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `processing`{.state .processing}",
            "config": {
                "state": "processing"
            }
        },
        {
            "id": "b913e860-1d43-11f1-a00f-9bd9990c5dfa",
            "name": "Download PDF",
            "provider": "chargebee.pdf.download"
        },
        {
            "id": "18910b60-6624-11f0-9087-c716f49f1585",
            "name": "Modify Silo Entry",
            "provider": "silo.modify",
            "summary": "Modifications configured",
            "config": {
                "addons": [
                    "de-zugferd-v2"
                ],
                "sign": false
            }
        },
        {
            "id": "c37c3860-abd0-11ef-a013-91c68ca9f44b",
            "name": "Sign Envelope",
            "provider": "silo.close"
        },
        {
            "id": "3548d720-6623-11f0-b3db-e7255a5da07c",
            "name": "Generate UN/CEFACT CII Invoice",
            "provider": "cii.generate",
            "summary": "ZUGFeRD V2",
            "config": {
                "attach_invoice_pdf": false,
                "doc_type": "zugferd-v2",
                "validate_cii": true
            }
        },
        {
            "id": "8e665990-81a3-11f0-82cb-9160968ac068",
            "name": "Embed FacturX/ZUGFeRD",
            "provider": "cii.pdf.embed"
        },
        {
            "id": "c6192a60-abd0-11ef-a013-91c68ca9f44b",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `sent`{.state .sent}",
            "config": {
                "state": "sent"
            }
        },
        {
            "id": "553f8c03-c0ff-4de5-9a66-33685b8f9c65",
            "name": "Update Chargebee",
            "provider": "chargebee"
        }
    ],
    "rescue": [
        {
            "id": "c94982c0-abd0-11ef-a013-91c68ca9f44b",
            "name": "Set State",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        },
        {
            "id": "c35d34c0-b7af-11ef-86a5-99a247862412",
            "name": "Update Chargebee",
            "provider": "chargebee"
        }
    ]
}

​
Retriggering Invoices

There may be situations where you need to reprocess an invoice. The method depends on whether Invopop has already created a silo entry (invoice) for it.

​
No Silo Entry Created (Invoice Not Imported)

If no job was created and no silo entry exists in Invopop, you can retrigger the webhook directly from Chargebee:
  1. Go to the Customers page in Chargebee
  2. Click on the customer in question
  3. Scroll down to History
  4. Go to the Events tab
  5. Select the Invoice Generated event for the invoice and date you want to reprocess
  6. Click Resend Webhook for the Invopop webhook
This will send the invoice to Invopop again, creating a new job and silo entry.

​
Silo Entry Already Exists

Once a silo entry (invoice) has been created in Invopop, retriggering from Chargebee will not work. Use the Run Again option on the last job instead. How you proceed depends on whether anything in Chargebee has changed.
Retriggering from Chargebee when a silo entry already exists will not work. Always use the Run Again option in the Invopop console in this case.

​
Error is downstream — data hasn’t changed

If the failure happened after the invoice was already signed (e.g. the Generate UBL or Send Peppol step failed) and nothing has changed in Chargebee, you can simply run the workflow again:
  1. In the Invopop console, navigate to the workflow that processed the invoice
  2. Find the last job for that invoice
  3. Click Run Again
The import step will detect that the invoice is already signed and skip the update — which is fine since the data is unchanged and processing can continue from where it failed.

​
Data has changed in Chargebee — signature needs to be removed

The Import Chargebee document step updates the invoice with fresh data from Chargebee each time it runs. However, if the invoice has already been signed, the import step will skip this update to preserve the signature. If you need the latest data from Chargebee to be pulled in — for example, because you updated a customer’s custom fields, corrected an error, or the failure happened before or during signing — you must first remove the signature:
  1. In the Invopop console, navigate to the silo entry for that invoice
  2. Click Edit, then Save — this removes the signature without altering the data
  3. Go to the workflow, find the last job for that invoice, and click Run Again
The import step will now pull the latest data from Chargebee before continuing with the rest of the workflow.

​
Custom Fields & Metadata

The following prefixes are used to map custom fields from Chargebee to GOBL (all of type Single line text):
PrefixDescriptionExample
cf_gobl_tax_Invoice tax extensioncf_gobl_tax_gr_mydata_invoice_type
cf_gobl_customer_Customer extensioncf_gobl_customer_mx_cfdi_fiscal_regime
cf_gobl_customer_identity_Customer identitycf_gobl_customer_identity_de_tax_number
cf_gobl_customer_inbox_Customer inboxcf_gobl_customer_inbox_it_sdi_pec
cf_gobl_item_Item extensioncf_gobl_item_br_nfse_service
cf_gobl_line_vat_VAT extensioncf_gobl_line_vat_pt_saft_exemption
cf_gobl_purchase_identity_Ordering purchase identitycf_gobl_purchase_identity_CIG
In addition to using custom fields, you can also set GOBL data as metadata in Chargebee. When using metadata, underscores must be replaced with hyphens, and the cf- prefix can be omitted.For example, the custom field cf_gobl_item_br_nfse_service would become gobl-item-br-nfse-service if passed as metadata.This applies to all the fields listed in this section.
In addition to the prefixes above, the following keys can be used to set specific GOBL fields:
KeyDescriptionType
cf_gobl_tagsInvoice tags (comma-separated list)Single line text
cf_gobl_addonsInvoice addons (comma-separated list)Single line text
cf_gobl_orderingInvoice ordering (full JSON)Single line text
Finally, you can use the following custom fields to choose which customer’s invoices Invopop should import and which ones we shouldn’t, or to route specific customers to a different workflow:
KeyDescriptionType
cf_invopop_includeCustomer to include when importing (if “True”)Checkbox
cf_invopop_excludeCustomer to exclude when importing (if “True”)Checkbox
cf_invopop_workflowWorkflow to use for this Customer (overrides the default one)Dropdown
You would typically use either cf_invopop_include to allowlist the customers to be imported, or cf_invopop_exclude to denylist them, but not both of them. They are optional, though, and if not set, all customers’ invoices will be imported.
When you configure a new custom field in Chargebee, it is not immediately added to any preexisting entities. The custom field is only attached to an entity after you edit and save it. This is particularly relevant to the cf_invopop_include field. The importer will always import a Customer unless the field is present and set to “False”. To ensure the expected behavior, you should probably back-populate the field in bulk for all your Customers to “False” right after configuring the field.

Participate in our community

Ask and answer questions about your Chargebee integration →