Chargebee
Import and process invoices and credit notes from Chargebee
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 for 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.
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
Firstly, we need to store the details of the supplier, the owner of the Chargebee account, in Invopop:
- In the console, go to “Contacts” then “Suppliers”, and tap “New supplier”.
- Add the company’s contact details, including the name, tax code, address, etc. in the form.
- 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 will merge the supplier information in Invopop with the business profile data in Chargebee when issuing the invoice, giving precedence to the data from Chargebee.
Prepare a Workflow
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.
Before starting, review the workflows guide to understand the general setup process.
In Console, create a new workflow and choose Empty Invoice workflow as the base. Then name the workflow with a descriptive label such as “Sync with ChargeBee”.
It’s essential to add the Import Chargebee document step at the very beginning of the workflow to import the document. Also, be sure to add a Sync with Chargebee step at the end of the workflow to report back to Chargebee once the document has been processed.
This is an example that combines the Chargebee app with a country-specific functionality (in this case, the ZUGfERD conversion step). You can replace the X-Rechnung step with any other country-specific functionality. See the country guides for more information.
Copy and paste into a new Empty Invoice workflow code view.
Before starting, review the workflows guide to understand the general setup process.
In Console, create a new workflow and choose Empty Invoice workflow as the base. Then name the workflow with a descriptive label such as “Sync with ChargeBee”.
It’s essential to add the Import Chargebee document step at the very beginning of the workflow to import the document. Also, be sure to add a Sync with Chargebee step at the end of the workflow to report back to Chargebee once the document has been processed.
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.comdomain. For example, if your URL ishttps://my-site.chargebee.com, your site ismy-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 the used API must be a Full-Access Key.
- Supplier: The supplier who will be issuing 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 totrue.
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 Chargebe. 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. See 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”:
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):
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.
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.
Custom Fields & Metadata
The following prefixes are used to map custom fields from Chargebee to GOBL:
| Prefix | Description | Type | Example |
|---|---|---|---|
cf_gobl_tax_ | Invoice tax extension | Single line text | cf_gobl_tax_gr_mydata_invoice_type |
cf_gobl_customer_ | Customer extension | Single line text | cf_gobl_customer_mx_cfdi_fiscal_regime |
cf_gobl_customer_identity_ | Customer identity | Single line text | cf_gobl_customer_identity_de_tax_number |
cf_gobl_customer_inbox_ | Customer inbox | Single line text | cf_gobl_customer_inbox_it_sdi_pec |
cf_gobl_item_ | Item extension | Single line text | cf_gobl_item_br_nfse_service |
cf_gobl_line_vat_ | VAT extension | Single line text | cf_gobl_line_vat_pt_saft_exemption |
cf_gobl_purchase_identity_ | Ordering purchase identity | Single line text | cf_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:
| 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_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 |
Here is a video of how you can set up the cf_invopop_include in your Chargebee site.
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. 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 behaviour, you should probably back-populate the field in bulk for all your Customers to “False” right after configuring the field.