Chargebee guide

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, and optionally report the payments and refunds collected against them.

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 (or of the transaction, for imported payments). We also recommend configuring workflows to send notifications via Slack or email to ensure any issues can be addressed quickly.

chargebee invoice — Invopop's output in Chargebee

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.

Create a Supplier

First we need to store the details of the supplier (the owner of the Chargebee account) in Invopop:

In the console, navigate to “Contacts” → “Suppliers” and tap “New supplier”.
Add the company’s contact details, including the name and tax code.
If you’re issuing invoices from a region that requires special fields, please contact Invopop support for assistance.
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.

Prepare a Workflow

Chargebee Basic PDF workflow

Add to my workspace →

Workflow
Code

Copy and paste the following JSON into a new Empty Invoice workflow code view. This example adds support for setting states on silo entries, which we strongly recommend.

Chargebee PDF invoice workflow

{
    "name": "Chargebee PDF invoice",
    "description": "Sync from Chargebee and generate a PDF",
    "schema": "bill/invoice",
    "steps": [
        {
            "id": "1b23a850-ff46-11ef-bc8b-49a3f98ea471",
            "name": "Import document from Chargebee",
            "provider": "chargebee.import"
        },
        {
            "id": "c9d569f0-ab1e-11ef-a0aa-f554af0a2b6c",
            "name": "Set state",
            "config": {
                "state": "processing"
            },
            "summary": "Set state to `processing`{.state .processing}",
            "provider": "silo.state"
        },
        {
            "id": "c7a347b0-ab1e-11ef-a0aa-f554af0a2b6c",
            "name": "Sign envelope",
            "provider": "silo.close"
        },
        {
            "id": "d1f2e5e0-ab1e-11ef-a0aa-f554af0a2b6c",
            "name": "Generate PDF",
            "config": {
                "logo_height": 40,
                "locale": "en",
                "date_format": "%Y-%m-%d"
            },
            "summary": "English · A4",
            "provider": "pdf"
        },
        {
            "id": "6277f270-abd0-11ef-a013-91c68ca9f44b",
            "name": "Set state",
            "config": {
                "state": "sent"
            },
            "summary": "Set state to `sent`{.state .sent}",
            "provider": "silo.state"
        },
        {
            "id": "02487016-0959-475c-9bc4-aa237313fefa",
            "name": "Update Chargebee",
            "provider": "chargebee"
        }
    ],
    "rescue": [
        {
            "id": "5504a610-abd0-11ef-a013-91c68ca9f44b",
            "name": "Set state",
            "config": {
                "state": "error"
            },
            "summary": "Set state to `error`{.state .error}",
            "provider": "silo.state"
        },
        {
            "id": "d8166690-ab1e-11ef-a0aa-f554af0a2b6c",
            "name": "Update Chargebee",
            "provider": "chargebee"
        }
    ]
}

For workflows that generate country-specific formats such as German ZUGFeRD or XRechnung documents, see the country guides below.

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.
Import payments: If enabled, payments and refunds are imported too, as GOBL payments. See Importing payments for what this requires.
Payment workflow: The workflow that will process payments, shown when Import payments is enabled. Leave it empty to use the invoice workflow.
Exclude customers by default: If enabled, Invopop will not process a customer’s invoices unless the cf_invopop_include custom field is present and set to true on that customer. This is the recommended way to allowlist a subset of customers — see Controlling which customers are processed below.

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 Chargebee 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.

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 fields & metadata 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:

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"
}

Set up a webhook

After saving the configuration in step 3, the page provides 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.

Currently, Invopop listens to the “Invoice Generated” and the “Credit Note Created” events, plus “Payment Succeeded” and “Payment Refunded” when Import payments is enabled. 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.

Tax names

The app reads each invoice’s tax category from the Tax name configured in your Chargebee account. Chargebee treats this as a free-text field, so many users set it to the local name of the tax in their country, such as MwSt, BTW, or TVA. If the tax name matches the code of a category in the supplier’s GOBL tax regime, such as VAT, GST, or HST, the app uses that category. Otherwise, it falls back to the main tax category of your account’s country. To change a tax name in Chargebee, go to Settings → Configure Chargebee → Taxes, select the country, and edit the tax. See Chargebee’s Configuring Taxes guide for details.

In regimes with more than one tax category, such as Canada or Brazil, a tax with an unrecognized name is imported under the regime’s main category. Name each tax in Chargebee after its exact category code so it’s imported under the right one.

Country guides

Depending on where your customers are located, you’ll need a different workflow to comply with local e-invoicing requirements. Each country guide covers the recommended workflow template, video walkthrough, and key custom fields:

Belgium

Send Peppol BIS invoices with the Chargebee PDF attached, with automatic participant ID lookup.

Denmark

Send Peppol invoices to Danish customers with SEPA payment key handling.

France

Route invoices automatically between the e-invoicing and e-reporting flows.

Germany

Generate ZUGFeRD hybrid PDFs for B2B or XRechnung documents for B2G.

Romania

Send invoices to ANAF through RO e-Factura and attach the official XML it returns.

Importing payments

Some countries require you to report when an invoice is paid, not just when it is issued. To support this, the app can import Chargebee payments and refunds as GOBL payments. This is off by default and needs two switches:

Enable Import payments in the app’s configuration, and optionally choose a Payment workflow.
Enable the “Payment Succeeded” and “Payment Refunded” events on your Chargebee webhook (already the case if it sends “All events”).

Payments are processed by the Payment workflow or, if you leave it empty, by the invoice workflow, including any assigned with the cf_invopop_workflow custom field. Whichever workflow processes payments must accept them: one whose schema is bill/invoice stops payments with a schema-mismatch error. How Chargebee payments become GOBL payments:

One payment per document. A Chargebee transaction that settles several invoices is imported as one payment for each invoice, each with the amount applied to it.
Refunds settle the credit note they were issued against, and are imported as a payment with the line marked as a refund.
Link to the invoice. The payment references the invoice it pays by UUID, series and number, and links to it in the Console, even if the payment is imported before the invoice. If you use Ignore Chargebee’s invoice codes and the payment arrives before Invopop has numbered the invoice, the payment can’t reference its number and the import fails; retry the job once the invoice has been processed.
VAT split. Chargebee doesn’t split payments by tax rate, so the app splits each payment across the invoice’s VAT rates in proportion to their weight in its total. Partial payments are split the same way.
No PDF. Chargebee doesn’t generate PDFs for payments, so the Download PDF from Chargebee step skips them, as does Update invoice details.
Comments. Import results and errors are posted as comments on the Chargebee transaction rather than on the invoice.

Payments only reach Invopop if the customer’s invoices do: the same business entity and customer include/exclude rules apply.

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: Enable the Exclude customers by default checkbox in the app’s configuration form, then set the cf_invopop_include custom field to true on each customer you want to process. Everyone else is excluded automatically — no back-populating required.
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.

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:

Go to the Customers page in Chargebee
Click on the customer in question
Scroll down to History
Go to the Events tab
Select the Invoice Generated event for the invoice and date you want to reprocess
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 document or Send Peppol document step failed) and nothing has changed in Chargebee, you can simply run the workflow again:

In the Invopop console, navigate to the workflow that processed the invoice
Find the last job for that invoice
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 document from Chargebee 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:

In the Invopop console, navigate to the silo entry for that invoice
Click Edit, then Save — this removes the signature without altering the data
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):

Prefix	Description	Example
`cf_gobl_tax_`	Invoice tax extension	`cf_gobl_tax_gr_mydata_invoice_type`
`cf_gobl_customer_`	Customer extension	`cf_gobl_customer_mx_cfdi_fiscal_regime`
`cf_gobl_customer_identity_`	Customer identity	`cf_gobl_customer_identity_de_tax_number`
`cf_gobl_customer_inbox_`	Customer inbox	`cf_gobl_customer_inbox_it_sdi_pec`
`cf_gobl_item_`	Item extension	`cf_gobl_item_br_nfse_service`
`cf_gobl_line_vat_`	VAT extension	`cf_gobl_line_vat_pt_saft_exemption`
`cf_gobl_note_`	Invoice note with that key	`cf_gobl_note_reason`
`cf_gobl_purchase_identity_`	Ordering purchase identity	`cf_gobl_purchase_identity_CIG`

Set invoice notes on the Customer to add them to all its invoices, or on a Subscription for that subscription’s invoices only. When both set the same key, the Subscription value wins. Formats that read a note key pick it up from there: for example, FatturaPA writes reason notes to Causale.

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:

Key	Description	Type
`cf_gobl_tags`	Invoice tags (comma-separated list)	Single line text
`cf_gobl_addons`	Invoice addons (comma-separated list)	Single line text
`cf_gobl_line_cost`	Line buyer accounting reference (cost)	Single line text
`cf_gobl_ordering`	Invoice 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:

Key	Description	Type
`cf_invopop_include`	Customer to include when importing (if “True”)	Checkbox
`cf_invopop_exclude`	Customer to exclude when importing (if “True”)	Checkbox
`cf_invopop_workflow`	Workflow 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 — unless the Exclude customers by default checkbox is enabled, which flips that default (see below).

By default, a customer’s invoices are imported unless cf_invopop_exclude is set to true, or the Exclude customers by default checkbox in the app’s configuration form is enabled and cf_invopop_include isn’t set to true for that customer.

Enabling the Exclude customers by default checkbox is the recommended way to allowlist a subset of customers with cf_invopop_include — the app skips any customer where the field isn’t set to true, so there’s no need to back-populate anything across your existing customers.If you use cf_invopop_include without enabling that checkbox, keep in mind that a new custom field is not immediately attached to preexisting Chargebee entities — it’s only attached once you edit and save that customer. In that mode, the importer will always import a customer unless the field is present and set to false, so you’d need to back-populate the field in bulk to false for all your customers to get the expected allowlist behavior.

Writing values back to Chargebee

The Custom Fields & Metadata section above covers data flowing into GOBL. The Update invoice details step does the reverse: it writes values produced during your workflow back onto the originating Chargebee document. A typical use case is recording the official reference number returned by a tax authority — for example, the Polish KSeF number — into a Chargebee custom field so it stays visible and searchable in Chargebee. The values are stored as custom fields (keys starting with cf_) on the document: invoices are written through Chargebee’s update_details endpoint, and credit notes through the update endpoint.

Custom fields must be defined on the corresponding entity (Invoices and/or Credit Notes) in your Chargebee site under Settings → Configure Chargebee → Custom Fields before the step runs. Chargebee silently ignores fields that are not defined on the entity: the step will report success, but nothing will be written.

Configuration

Add the Update invoice details step to your workflow (its provider is chargebee.update.details) and open its configuration. You’ll see a table where each row maps one Chargebee field to a value:

Field — the Chargebee field name to set, e.g. cf_ksef_number.
Value — an expr expression, evaluated against the full GOBL envelope (both head and doc). Document extensions are available under doc.ext[...], while values added by earlier steps — such as the confirmation numbers returned by a tax authority — are stored as stamps under head.stamps and can be looked up with expr’s find() function. To set a static value, use a literal string such as "invopop".

Update invoice details step configuration — Configuring the Update invoice details step

For example, to write the Polish KSeF number into the cf_ksef_number custom field, set the value to:

find(head.stamps, {.prv == "favat-ksef-number"}).val

This finds the stamp whose provider (.prv) is favat-ksef-number — the KSeF reference number added when the invoice is submitted — and returns its value (.val). A few rules to keep in mind:

Each expression must resolve to a single scalar value (text, number, or boolean). Returning an object or a list is not allowed.
If an expression resolves to nothing (a missing or null value), that field is skipped rather than written as an empty value.
The step is idempotent — it replaces the field values each time it runs, so re-running a workflow won’t create duplicates.

In JSON, the step looks like this:

{
  "name": "Update invoice details",
  "provider": "chargebee.update.details",
  "config": {
    "fields": [
      {
        "field": "cf_ksef_number",
        "value": "find(head.stamps, {.prv == \"favat-ksef-number\"}).val"
      }
    ]
  }
}

Where to place the step

The value you want to write must already exist in the envelope by the time this step runs. For instance, to write the KSeF number back to Chargebee, place the step after the step that submits the invoice and obtains that number, and typically before the final Update Chargebee step. Once the workflow runs, the resolved value appears on the invoice’s custom fields in Chargebee:

Custom field populated on a Chargebee invoice — The KSeF number written back to the Chargebee invoice

Participate in our community

Ask and answer questions about your Chargebee integration →

Networks

Countries

Set-up

GOBL

Apps

API

Features

Chargebee guide

Introduction

How it works

Setup

Chargebee Basic PDF workflow

Tax names

Country guides

Belgium

Denmark

France

Germany

Romania

Importing payments

Controlling which customers are processed

Retriggering invoices

No silo entry created (invoice not imported)

Silo entry already exists

Error is downstream — data hasn’t changed

Data has changed in Chargebee — signature needs to be removed

Custom fields & metadata

Writing values back to Chargebee

Configuration

Where to place the step

Participate in our community

​Introduction

​How it works

​Setup

Chargebee Basic PDF workflow

​Tax names

​Country guides

Belgium

Denmark

France

Germany

Romania

​Importing payments

​Controlling which customers are processed

​Retriggering invoices

​No silo entry created (invoice not imported)

​Silo entry already exists

​Error is downstream — data hasn’t changed

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

​Custom fields & metadata

​Writing values back to Chargebee

​Configuration

​Where to place the step

Participate in our community

Introduction

How it works

Setup

Tax names

Country guides

Importing payments

Controlling which customers are processed

Retriggering invoices

No silo entry created (invoice not imported)

Silo entry already exists

Error is downstream — data hasn’t changed

Data has changed in Chargebee — signature needs to be removed

Custom fields & metadata

Writing values back to Chargebee

Configuration

Where to place the step