Introduction to Chargebee
Make Chargebee's subscription billing ready in iPaaS.com for the other systems you connect: customers with their billing status, item prices as products, and invoices and credit notes with their payments, refunds, taxes and discounts move TO iPaaS.com, and customers from your CRM or ERP can open billing accounts in Chargebee FROM iPaaS.com.
API Version Support
The integration uses the Chargebee API v2 and is built for Chargebee sites that use Product Catalog 2.0, where plans, addons and charges are items sold through item prices. Before you subscribe, confirm with Chargebee support that your site uses Product Catalog 2.0; if it uses another catalog model, validate the connection in a staging environment before relying on it in production. It connects to your own Chargebee site, named in the Chargebee Site setting, with a full-access API key. Each subscription works with one Chargebee site: the subscription remembers the Chargebee site it first exchanged data with, so to connect another site, including a Chargebee test site, add a separate subscription for it. See the Chargebee Connections and Settings and Chargebee API Endpoints articles for details.
Data Flows
The table below summarizes the data the integration can move between iPaaS.com and Chargebee, and in which direction. Arrows show the direction of transfer:
→ iPaaS.com writes the data to Chargebee
← iPaaS.com reads the data from Chargebee
←→ the data can move in both directions
Allow Initialization? indicates whether that data can be bulk-loaded from Chargebee when a subscription first connects. Whether a given flow is enabled, and in which direction, is configured per subscription during implementation.
iPaaS.com | Direction | Chargebee | Allow Initialization? |
Customer | ←→ | Customer (billing account) | |
Product | ← | Item Price | |
Transaction (invoice and return) | ← | Invoice and Credit Note |
Each customer travels with its billing address. Each invoice and credit note travels with its lines, payments or refunds, taxes, discounts and addresses. Chargebee stays in charge of billing: item prices, invoices, credit notes and their payments travel only TO iPaaS.com. Existing Chargebee history arrives through the first run of each scheduled poll, which looks back the number of days in Initial Poll Days.
Versions and Release Notes
The integration follows its own version numbers. The current version is 1.0.0.
Version | Release Notes |
1.0.0 (current) | Initial release. Chargebee customers with their billing address and billing status, item prices as products, and invoices and credit notes as transactions travel TO iPaaS.com as Chargebee changes them, through a webhook endpoint the integration registers in Chargebee for you, with scheduled poll events as a backstop. Invoices and credit notes carry their lines, payments, refunds, taxes, discounts and addresses, and their customer and item prices are sent first when they are not in iPaaS.com yet. Customers selected in iPaaS.com open and update billing accounts in Chargebee FROM iPaaS.com, with their billing address. Errors the integration reports carry a stable error code with a plain-language cause and resolution. |
Features by Release
The capabilities below reflect the current 1.0.0 integration. For the current behavior and any limitations of a given feature, see the referenced articles and the Chargebee Integration Known Limitations article.
Version 1.0.0 (current) — Initial release
Customers TO iPaaS.com, with their billing status (see the Chargebee to iPaaS.com Customer Mapping Documentation): Chargebee customers that have an email and a name or company are created and updated in iPaaS.com with their billing address. Four custom fields, Chargebee Subscription Status, Chargebee Active Subscriptions, Chargebee Next Billing Date and Chargebee Monthly Recurring Revenue, are worked out from the customer's Chargebee subscriptions each time the customer is sent; see the Chargebee Integration Known Limitations article for when they can lag behind a subscription change. A Chargebee customer whose email already belongs to one iPaaS.com customer is linked to it instead of creating a second one. With the customer_deleted scope Active, a customer deleted in Chargebee is kept in iPaaS.com with its Chargebee Subscription Status set to deleted.
Item prices as products (see the Chargebee to iPaaS.com Item Price Mapping Documentation): each Chargebee item price (a plan, addon or charge at one currency and billing period) becomes an iPaaS.com product whose SKU is the item price id, with its name, description and price, and custom fields for the Chargebee item, item type, currency, billing frequency, pricing model and price tiers. An existing iPaaS.com product with that SKU is linked instead of duplicated. An archived item price already in iPaaS.com becomes Discontinued.
Invoices TO iPaaS.com (see the Chargebee to iPaaS.com Invoice Mapping Documentation): closed Chargebee invoices become Invoice transactions with their lines, payments, taxes, discounts and addresses, and are updated as they are paid, voided, written off or deleted; voided and deleted invoices are shown as Cancelled. Custom fields carry the currency, subscription id, amount due, amount paid, due date, dunning status, credits applied and write-off amount.
Credit notes TO iPaaS.com (see the Chargebee to iPaaS.com Credit Note Mapping Documentation): Chargebee credit notes become Return transactions linked to the invoice they credit, with their refunds, credit note type and reason.
Transaction numbers ready for a shared company: a Chargebee invoice or credit note number made only of digits arrives as INV-1042 or CN-17, because iPaaS.com allows each transaction number once across all of a company's systems.
Customers FROM iPaaS.com as billing accounts (see the iPaaS.com to Chargebee Customer Mapping Documentation): iPaaS.com customers selected by the collection's filter, which ships as an example that subscribers or their MiSP adapt to how they mark billing customers, open and update Chargebee customers with their first name, last name, email, company and primary billing address. Before it creates a customer, the integration looks for a Chargebee customer with the same email and hands a match to the collection's Collision Handling Method. An update that would change a field someone edited in Chargebee stops with an error, so you choose which version wins.
Webhooks registered for you, with polls as a backstop (see the Chargebee Installation Instructions): setting a Chargebee webhook scope Active registers the subscription's webhook endpoint in Chargebee and adds or removes its events as you change the scopes. Scheduled poll events for customers, item prices, invoices and credit notes pick up changed records as a backstop to the webhooks; the invoice and credit note poll events each take a Filter rule (invoice and credit_note) so that every document is sent once.
Translations for statuses, payment methods and countries (see the Chargebee Installation Instructions): ready-made translations turn Chargebee document and payment statuses into iPaaS.com statuses and iPaaS.com countries into the two-letter codes Chargebee needs. Before go-live, fill in the payment method translation with your own iPaaS.com payment methods (it ships with placeholder rows) and add any countries you use beyond the United States, Canada and the United Kingdom. A change to a translation row applies once the translation collection is saved.
Mapping functions (see the Chargebee Mapping Functions article): ready-made functions that find the iPaaS.com customer and invoice linked to a Chargebee record and build transaction numbers, already used by the default invoice and credit note mapping collections.
Coded error messages (see the Chargebee Error Messages article): errors the integration reports carry a stable code with their cause and how to resolve them.