The Chargebee integration brings Chargebee customers, item prices, invoices and credit notes TO iPaaS.com, where they are ready for the other systems you connect, and sends customers FROM iPaaS.com to Chargebee as billing accounts. Follow the sections in order.
Before You Begin
You need the following before you start in iPaaS.com:
A Chargebee site on Product Catalog 2.0. The integration is built for sites that use Product Catalog 2.0 (items and item prices). When Chargebee refuses the item price read as incompatible with the site's configuration, the integration treats the site as not using Product Catalog 2.0 and stops every transfer with CHGB-BIZL-1009. Confirm your site's catalog with Chargebee support before you subscribe, and validate the connection in a staging environment before relying on it in production.
Your Chargebee site name. It is the first part of your Chargebee address: for acme.chargebee.com it is acme; for a test site such as acme-test.chargebee.com it is acme-test.
A full-access Chargebee API key for that site. Chargebee states that "API keys can be viewed and created by users with admin access to Chargebee" (Chargebee API: Authentication). If you can't create one, ask the owner of your Chargebee site. The steps are under Authentication Configuration.
A free webhook slot on the site. Chargebee allows "up to five webhook endpoints per site" (Chargebee API: Webhook endpoints), and the integration adds one for each iPaaS.com subscription. In Chargebee, open Settings > Configure Chargebee > API Keys and Webhooks, then the Webhooks tab. If all five are taken, delete one you no longer use.
An iPaaS.com account with permission to add subscriptions.
A Chargebee test site, if you have one. Chargebee notes that "the API keys are different for your test site and your live site" (Chargebee API: Authentication). Give the test site its own subscription and run the checks under Post-Installation Verification there first: records created on a live site are real billing records, and they reach the other systems you connect.
Nothing else needs setting up in Chargebee: the integration registers its own webhook endpoint (see Turn On the Chargebee Webhooks). No OAuth application or redirect address is needed.
Setup is more than entering a key. Allow time to replace the placeholder values, fill in the payment-method translation, add your countries, check the custom fields and choose the Collision Handling Method (all described below).
Installation Instructions for Integration Setup
In iPaaS.com, go to Subscriptions and click Search Certified Integration Marketplace & Subscribe.
Click the Chargebee integration tile.
Click the Subscribe button.
Enter a name for the subscription that is unique in your company.
Format: Chargebee - [Environment/Purpose]
Example: Chargebee - Test Site, or Chargebee - Production
Leave Create Default Mappings checked. It installs the Chargebee mapping collections and translations that the rest of these instructions configure. Uncheck it only if you will build every mapping yourself.
Enter Chargebee Site: your site name, or your full Chargebee address (see Authentication Configuration).
Test site: acme-test, or the full address acme-test.chargebee.com
Live site: acme, or the full address acme.chargebee.com
Enter API Key: the full-access key for the same site (see Authentication Configuration).
Enter Initial Poll Days (optional): how many days back the first poll of each data type looks. Allowed values are 1 to 3650; blank is saved as the default, 7 (see Operational Configuration).
Enter Poll Page Size (optional): how many records each poll request reads. Allowed values are 1 to 100; blank is saved as the default, 100, which is Chargebee's largest page (see Operational Configuration).
Review the platform settings. They are pre-populated; leave them at their defaults unless subscribers or their MiSP have a reason to change them.
API Throttle Limit: the number of calls to Chargebee allowed per throttle period. Default: 500. Set it to no more than your Chargebee site's published per-minute limit (with API Throttle Seconds at 60). Chargebee states: "For test sites, it is 150 API calls per minute"; for live sites its published defaults are 150 (Starter), 1000 (Performance) and 3500 (Enterprise default) (Chargebee API: Error handling). On a test site or the Starter plan, lower the default 500 to 150 or less; for initial setup a low value such as 5 is safest. Chargebee notes that "you can easily request higher limits by contacting Chargebee Support with your requirements".
API Throttle Seconds: the length of the throttle period, in seconds. Default: 60.
API Throttle Limit (To iPaaS): the number of calls back to iPaaS.com allowed per throttle period, for transfers TO iPaaS.com. Default: 500.
API Throttle Seconds (To iPaaS): the length of that throttle period, in seconds. Default: 60.
Concurrent Connections: how many transfers run at the same time. Default: 2. Keep it low, within what your Chargebee plan's API limit allows.
Concurrent Batch Executions: not used by this integration. Leave the default.
Click Apply to save the settings.
What happens when you click Apply
iPaaS.com refuses to save the settings when Chargebee Site or API Key is empty (VALD-1002), or when Initial Poll Days or Poll Page Size holds something that isn't a number (VALD-1156). Otherwise it saves them without checking them against Chargebee. The integration checks the connection at the start of every transfer, by reading item prices from the site. A wrong site name or API key, or a site that does not appear to use Product Catalog 2.0, shows up on the first transfer as an error in Dashboard / Integration Monitoring / Error Logs that reads only "Unable to connect to subscription with id N". The integration's reason is in the company's Logs, at the error's time, and starts with a CHGB code (see Error Messages).
Authentication Configuration
The integration signs in to Chargebee with the API key alone. Chargebee "uses HTTP Basic authentication for API calls. The username is your API key while the password is empty" (Chargebee API: Authentication). There is no separate Authorize step: saving the settings is the authorization.
Chargebee Site and API Key
Chargebee Site
Location: the address of your Chargebee site, for example acme-test.chargebee.com.
Description: the site the integration reads and writes. Enter the bare site name (acme-test) or the full address (acme-test.chargebee.com, with or without https://); both point to the same site. Capital letters, a trailing slash or a page address on the site are accepted too.
API Key
Location: in Chargebee, Settings > Configure Chargebee > API Keys and Events, the API Keys tab (Chargebee: API keys). Older Chargebee pages and messages call it API Keys and Webhooks.
Description: a Full-Access Key, which Chargebee describes as allowing "full access to Chargebee data with configurable read, write, and update levels". It must belong to the same site as Chargebee Site. The key is masked once saved and is never shown in logs or errors.
To create the API key:
Sign in to Chargebee as a user with admin access, on the site this subscription connects to.
Click Settings, then Configure Chargebee, then API Keys and Events, then the API Keys tab.
Click Add API Key, choose Full-Access Key, name it (for example "iPaaS.com") and click Create Key.
Copy the key into a safe place, such as a password manager, and paste it into API Key in the subscription settings.
Important Notes
Use a Full-Access Key. Chargebee's Read-Only Key "allows read-only access to transactional and configuration data", and a restricted read-only key reaches only the API groups selected for it (Chargebee: API keys). Such a key is refused with CHGB-AUTZ-1001 wherever it lacks permission, including customer writes FROM iPaaS.com and the webhook endpoint registration. Subscribers or their MiSP should validate any key other than a Full-Access Key in a staging environment before relying on it in production.
Test and live keys don't mix. A key from another site is refused with CHGB-AUTH-1002. Use the test site's key with the test site's name, and the live site's key with the live site's name.
Keep the key out of Chargebee Site. A Chargebee API key pasted into Chargebee Site is recognized and refused with CHGB-AUTH-1001, without the key being repeated in the message.
One subscription per Chargebee site. The subscription remembers the Chargebee site it first exchanged data with. Each Chargebee site keeps its own numbering, so two sites can each hold an invoice 1042, and another site's records could overwrite this site's in iPaaS.com. If Chargebee Site later names another site, every transfer stops with "Unable to connect to subscription with id N" and CHGB-BIZL-1008 in Logs: change the setting back to the site the message names, or add a new subscription for the other site. Correcting a mistyped site name is safe: a site that doesn't exist never exchanges data (it gives CHGB-NFND-1001 with site_not_found), so it is never remembered.
Changing the key. Create a new full-access key on the same site, paste it into API Key and click Apply. The next transfer uses it. Delete the old key in Chargebee only after the new one is saved.
Revoking access. Delete the key in Chargebee's API Keys tab. Every transfer then stops with CHGB-AUTH-1002 until a new key is saved.
Operational Configuration
Initial Poll Days
Description: how many days back the first poll of each data type looks. Each later poll picks up from the last change it saw.
Purpose: decides how much Chargebee history the first polls bring into iPaaS.com. There is no separate initialization: history arrives through the first poll.
Example: 30 means the first invoice poll brings in every invoice changed in the last 30 days; the next poll reads only what changed after that.
Recommended values: initial setup: the number of days of history you want in iPaaS.com, set before the first poll runs (raising it later doesn't re-read older records). Ongoing operations: leave it as it is. High volume: a shorter window keeps the first polls small.
Default and range: 7; 1 to 3650.
Poll Page Size
Description: how many records each poll request reads from Chargebee.
Purpose: a poll reads one request per page, so a larger page means fewer requests against the site's API limit.
Example: 100 means a poll that finds 250 changed invoices reads them in three requests.
Recommended values: initial setup, ongoing operations and high volume: 100, Chargebee's largest page. Lower it only if subscribers or their MiSP are advised to.
Default and range: 100; 1 to 100.
Values the integration adjusts
iPaaS.com saves a blank Initial Poll Days or Poll Page Size as its default (7 and 100) and refuses a value that isn't a number (VALD-1156). A number the integration can't use as entered is adjusted: a value outside the allowed range uses the nearest allowed value, and a decimal uses its whole part. Each time the integration connects, it writes a warning in the transfer's activity log (Dashboard / Integration Monitoring) naming the setting and the value it used, never the value entered, for example: The "Initial Poll Days" setting is below 1, so 1 is used. The warning does not appear in Logs or in Error Logs, and the transfer carries on.
Additional Configuration Options
Turn On the Chargebee Webhooks (TO iPaaS.com)
Chargebee tells iPaaS.com about each change through a webhook. In the subscription configuration's Inbound Data Flows section, set Active the scopes for the data you send TO iPaaS.com.
When you set the first scope Active, the integration registers a webhook endpoint in Chargebee for you, named "iPaaS.com subscription {your subscription id}". It adds or removes events on that endpoint as you set scopes Active or inactive, and removes the endpoint when you set the last scope inactive. Leave that endpoint alone in Chargebee.
It can take ten minutes or more for Chargebee to show a new endpoint after the first scope is set Active, and nothing is recorded in iPaaS.com when it appears. Scopes added to an existing endpoint reach it within seconds. Check Chargebee's Webhooks tab after ten minutes or more rather than setting the scope inactive and Active again.
Set scopes inactive one at a time. Several scopes set inactive in quick succession can leave an event on the Chargebee endpoint that is no longer Active in iPaaS.com, and the endpoint can then stay after the last scope is set inactive. After turning scopes off, check the endpoint's events on Chargebee's Webhooks tab; remove a leftover event, or the endpoint once no scope is Active, in Chargebee.
Data | Scopes to set Active | What each sends |
Customers | customer_created, customer_changed | The customer and their billing address |
customer_deleted | A customer deleted in Chargebee: the iPaaS.com customer is kept, and its Chargebee Subscription Status becomes deleted | |
subscription_created, subscription_activated, subscription_changed, subscription_cancelled, subscription_reactivated, subscription_renewed, subscription_paused, subscription_resumed | The customer again, so their billing status (subscription status, next billing date, monthly recurring revenue) stays current. Keep these Active: billing status changes reach iPaaS.com only this way | |
Item prices | item_price_created, item_price_updated | The item price as a product. An archived price already in iPaaS.com becomes Discontinued |
Invoices | invoice_generated, invoice_updated, invoice_deleted | The invoice with its lines, payments, taxes, discounts and addresses |
payment_succeeded, payment_failed | The invoice again, with the payment on it | |
Credit notes | credit_note_created, credit_note_updated, credit_note_deleted, payment_refunded | The credit note as a return, with its refunds |
Add the Poll Events (TO iPaaS.com)
Webhooks are the main way changes reach iPaaS.com. The poll events are a backstop: each one reads the records Chargebee marks as changed since the last poll, so a record whose webhook was missed still arrives. A new subscription has no poll events until you add them.
For each data type you send, go to Integration Monitoring and Diagnostics > Events in iPaaS.com, select Add Event (see Events), and for this subscription set its Event Type to Webhook (Poll Request), and give it the poll scope and schedule below. For the two transaction polls, also add a filter: under Event Rules, select Add, choose Filter as the Name, and enter the value shown as the Expression.
Poll scope | Data | Filter Expression | Recommended schedule |
customer_poll | Customers | none | Every 30 minutes |
item_price_poll | Item prices | none | Every 30 minutes |
invoice_poll | Invoices | invoice | Every 30 minutes |
credit_note_poll | Credit notes | credit_note | Every 30 minutes |
Add the Filter rule on both transaction polls. The invoice_poll event must have a Filter rule with the Expression invoice, and the credit_note_poll event a Filter rule with the Expression credit_note. Without it, either transaction poll reads both invoices and credit notes, so with both events scheduled every document is sent twice. The customer_poll and item_price_poll events read no filter.
Why 30 minutes: a record whose webhook was missed arrives within about half an hour, and each poll that finds nothing new costs one request to Chargebee. Chargebee measures its limit on "the API requests for your Chargebee site" (Chargebee API: Error handling), so don't poll much more often. The first poll looks back Initial Poll Days; each later poll picks up from the last change it saw, and a poll that finds more changes than one run reads continues on its next run.
Polls don't catch everything. These changes reach iPaaS.com only by webhook, so keep their scopes Active:
A change to a customer's billing status that comes from one of their subscriptions (the subscription scopes).
A deleted record: polls never send deleted customers, invoices or credit notes (the customer_deleted, invoice_deleted and credit_note_deleted scopes).
An edit to an item (the plan, addon or charge an item price belongs to). It reaches iPaaS.com the next time the item price itself changes.
A payment applied to several invoices. The payment webhook refreshes the invoice it names; the others are refreshed by their own next change.
If Chargebee refuses the position a poll saved, the poll reads again from the saved time and writes the warning "Chargebee refused the saved paging cursor; reading again from the saved second." in its activity log (Dashboard / Integration Monitoring). Nothing needs doing: records already sent are not sent again.
Turn On the iPaaS.com Webhooks (FROM iPaaS.com)
To create and update Chargebee customers from iPaaS.com customers, subscribe to these iPaaS.com Customer triggers in the subscription configuration's Outbound Data Flows section:
Data | Triggers to subscribe to | What each sends |
Customers | customer/created, customer/updated | The customer's first name, last name, email and company, and their primary billing address, for the customers the Add/Update Chargebee Customer FROM iPaaS.com filter selects (see Customer FROM iPaaS.com Filter) |
Do not subscribe to customer/deleted: deleting Chargebee customers is not supported, and each delete stops with CHGB-BIZL-1005.
Mapping Collections
Collection | What it does |
Add/Update Chargebee Customer TO iPaaS.com | Sends Chargebee customers with an email, their billing address and their billing status. A Chargebee customer whose email already belongs to one iPaaS.com customer is linked to it. |
Add/Update Chargebee Item Price TO iPaaS.com | Sends each item price (a plan, addon or charge at one currency and billing period) as a product whose SKU is the item price id. An existing iPaaS.com product with that SKU is linked instead of duplicated. |
Add/Update Chargebee Invoice TO iPaaS.com | Sends closed invoices with their lines, payments, taxes, discounts and addresses. Draft invoices wait until Chargebee closes them. The invoice's customer and item prices are sent first when they aren't in iPaaS.com yet. |
Add/Update Chargebee Credit Note TO iPaaS.com | Sends credit notes as returns linked to the invoice they credit, with their refunds. |
Add/Update Chargebee Customer FROM iPaaS.com | Creates and updates Chargebee customers and their billing address FROM iPaaS.com, for the customers its filter selects. |
Placeholder Values
Placeholder value — replace during implementation: the default mappings and translations carry values that start with "REPLACE". Replace each before you turn the collections on. The same list is kept in Placeholder Values to Replace Before Go-Live in the Chargebee Integration Known Limitations article.
The SKU for ad-hoc charges (the Sku mapping of Add/Update Chargebee Invoice Line TO iPaaS.com and Add/Update Chargebee Credit Note Line TO iPaaS.com). It ships as REPLACE with the SKU of your ad-hoc charge product. An ad-hoc charge is a charge with no item price, and every transaction line in iPaaS.com needs a product. Create one product in iPaaS.com for these charges, for example "Chargebee one-time charge" with the SKU CB-ADHOC, and put its SKU in place of the REPLACE text in both collections. This product is like any other iPaaS.com product: every system you connect that takes products FROM iPaaS.com receives it, which can include an online store; if one of them shouldn't show it, have that system's filter leave it out. Left as REPLACE, an invoice with an ad-hoc line stops with "NFND-1003 - Product Id: REPLACE with the SKU of your ad-hoc charge product does not exist or can not be found."
The payment methods (the Chargebee Payment Method TO iPaaS.com translation, used by Add/Update Chargebee Invoice Payment TO iPaaS.com and Add/Update Chargebee Credit Note Refund TO iPaaS.com). It ships with 33 rows, one for each Chargebee payment method: ach_credit, alipay, amazon_payments, apple_pay, automated_bank_transfer, bancontact, bank_transfer, boleto, card, cash, chargeback, check, custom, direct_debit, dotpay, faster_payments, giropay, google_pay, ideal, klarna_pay_now, netbanking_emandates, online_banking_poland, other, pay_to, payconiq_by_bancontact, paypal_express_checkout, sepa_credit, sepa_instant_transfer, sofort, unionpay, upi, venmo and wechat_pay. Each row's right side ships as text such as REPLACE with your iPaaS.com payment method for Chargebee card payments. Replace it with the exact name of a payment method in your iPaaS.com company, for example card to Credit Card and bank_transfer to Bank Transfer. If you don't know which methods your site uses, fill every row: a payment whose method is still REPLACE stops its invoice with "VALD-1036 - Value (REPLACE with your iPaaS.com payment method for Chargebee … payments) provided for Payment Method is not valid." Don't delete a row: a payment whose method has no row is expected to stop its invoice with an iPaaS.com validation error (VALD-1024); validate this case in a staging environment before relying on it in production.
The customer filter (the filter of Add/Update Chargebee Customer FROM iPaaS.com). It ships as an example that looks for the customer category REPLACE with the customer category that marks a billing account. Until you change it, no customer matches and nothing is sent to Chargebee. See the next section.
Customer FROM iPaaS.com Filter
The filter of Add/Update Chargebee Customer FROM iPaaS.com decides which iPaaS.com customers become Chargebee billing accounts, so shoppers, leads and other contacts don't. As shipped, it is an example that sends only customers carrying one named customer category. Subscribers or their MiSP adapt it, or replace it, to match how they mark billing customers, for example:
A category name: replace the text inside the quotes with the exact name of the iPaaS.com customer category that marks a billing customer (for example, Chargebee Billing Account), keeping the quotes. The name must match exactly, including capitalization. Then add that category to every iPaaS.com customer that should have a Chargebee billing account; your other systems' mappings can add it too.
A custom field flag: replace the filter with one that checks a customer custom field you already use to mark billing customers.
Other criteria: any condition on the iPaaS.com customer, such as customers that have an email address.
A customer the filter skips logs no error, so test the changed filter with a few customers on your test subscription before relying on it in production. See the iPaaS.com to Chargebee Customer Mapping Documentation for the full filter.
Collision Handling (Customer FROM iPaaS.com)
Set the Collision Handling Method on Add/Update Chargebee Customer FROM iPaaS.com before you turn it on: templates don't carry it. When a Chargebee customer already has the email of the iPaaS.com customer being created, the integration hands the match to that method:
Collision Handling Method | What happens |
Error | The transfer stops with the error "A data collision occurred…" naming the Chargebee customer; nothing is linked or changed |
(none set) | The two are linked and nothing is sent to Chargebee. Choose one of the other methods instead |
Remap and Link | The two are linked, then iPaaS.com's values are sent to Chargebee |
Update and Link | The two are linked, then iPaaS.com's values are sent to Chargebee (recommended) |
Update and No Link | Chargebee's customer is updated with iPaaS.com's values without linking, so the next transfer searches by email again. If Customer TO iPaaS.com is on, Chargebee then reports that update back, and Customer TO iPaaS.com can link the two by email |
With this integration, Remap and Link and Update and Link have the same result. We recommend Update and Link. Under any method except Error, the matched Chargebee customer takes iPaaS.com's values, including fields someone edited in Chargebee: the integration hasn't written that customer before, so it has nothing to compare an edit with. Two or more Chargebee customers with the same email stop the transfer with CHGB-BIZL-1001; merge them or change their emails in Chargebee.
The billing address has no collision handling of its own: it goes with its customer and updates the linked customer's billing address.
Translations
The templates come with these translations:
Chargebee Document Status TO iPaaS.com (complete; no change needed): paid and adjusted become Complete; payment_due and not_paid become Awaiting Payment; posted and refund_due become Pending; refunded becomes Refunded; voided and deleted become Cancelled; pending becomes Draft.
Chargebee Payment Status TO iPaaS.com (complete; no change needed): success becomes Completed; failure and timeout become Failed; voided becomes Cancelled; in_progress and needs_attention become Pending.
Chargebee Payment Method TO iPaaS.com (yours to fill in: see Placeholder Values).
Chargebee Country FROM iPaaS.com (add your countries): turns the country on an iPaaS.com address into the two-letter code Chargebee needs. It starts with rows for the United States, Canada and the United Kingdom, by name and by code. Add a row for every other country your customers use, with the country as iPaaS.com holds it on the left and its two-letter code on the right. A country with no row stops that customer's transfer with CHGB-VALD-1001 instead of clearing the country.
Save the translation collection after editing its rows. A change to a translation row applies once the translation collection is saved. After saving, send the record again or let the next retry pick it up.
Custom Fields the Integration Fills
The default mappings write these iPaaS.com custom fields and keep them current. Use them in your other systems' mappings or in reports.
Setup step: check that each custom field below exists in your iPaaS.com company, for its data type, with exactly the name shown. Add any that is missing. A mapping whose custom field doesn't exist can't write it.
Data | Custom field | What it holds |
Customer | Chargebee Subscription Status | The customer's billing status: active, in_trial, future, non_renewing, paused, cancelled, none, or deleted when the customer was deleted in Chargebee |
Customer | Chargebee Active Subscriptions | How many of the customer's subscriptions are live |
Customer | Chargebee Next Billing Date | When Chargebee next bills the customer |
Customer | Chargebee Monthly Recurring Revenue | The customer's monthly recurring revenue |
Product | Chargebee Item Id | The Chargebee item the price belongs to |
Product | Chargebee Item Type | plan, addon or charge |
Product | Chargebee Currency | The price's currency |
Product | Chargebee Billing Frequency | How often the price is billed, in words |
Product | Chargebee Pricing Model | flat_fee, per_unit, tiered, volume or stairstep |
Product | Chargebee Price Tiers | The price tiers, for tiered, volume and stairstep pricing |
Transaction (invoice) | Chargebee Currency | The invoice's currency: every amount is in it |
Transaction (invoice) | Chargebee Subscription Id | The Chargebee subscription the invoice belongs to |
Transaction (invoice) | Chargebee Amount Due | What is still owed |
Transaction (invoice) | Chargebee Amount Paid | What has been paid |
Transaction (invoice) | Chargebee Due Date | When the invoice is due |
Transaction (invoice) | Chargebee Dunning Status | Where Chargebee's payment retries stand |
Transaction (invoice) | Chargebee Credits Applied | Credit from credit notes or promotional credits: part of the total that is neither paid nor due |
Transaction (invoice) | Chargebee Write Off Amount | What Chargebee wrote off. A written-off invoice reads Complete because Chargebee marks it paid, but this part was never paid |
Transaction (return) | Chargebee Credit Note Type | adjustment (lowers what the invoice owes, as a write-off does), refundable or store |
Transaction (return) | Chargebee Credit Note Reason | Chargebee's reason code, for example write_off |
Returns (credit notes) also use Chargebee Currency and Chargebee Subscription Id, the same transaction custom fields as invoices.
Things to Know
Archive an item price before you delete it. Once Chargebee deletes an item price it can no longer be read, so iPaaS.com can't learn about the deletion. Archive the price first: if the product is already in iPaaS.com, it becomes Discontinued.
A deleted Chargebee customer is kept in iPaaS.com. With customer_deleted Active, its Chargebee Subscription Status becomes deleted, so your other systems can act on it. The integration never deletes an iPaaS.com customer. Wait a few minutes after deleting a customer in Chargebee before running a Manual Sync for it: for a short time Chargebee still returns it as live, and a Manual Sync in that time treats it as not deleted.
Edits made in Chargebee stop an update that would change them. The integration remembers every field it writes to a Chargebee customer: name, email, phone, company, custom fields and each billing address field. If someone edits one of those fields in Chargebee, an update FROM iPaaS.com that would change that field stops with CHGB-BIZL-1003. An update that leaves the edited field alone, or already carries Chargebee's new value, goes through. To keep Chargebee's version, set those fields on the iPaaS.com customer to Chargebee's values and send it again. To keep iPaaS.com's version, make the same change in Chargebee, then send the customer again.
Each write FROM iPaaS.com comes back TO iPaaS.com. With customer_created and customer_changed Active, Chargebee reports every customer Customer FROM iPaaS.com writes, so at least one TO iPaaS.com transfer of the same customer follows each write. It brings Chargebee's values back; it does not start another FROM iPaaS.com transfer.
Chargebee owns billing. Invoices, credit notes, payments and item prices travel only TO iPaaS.com; changing them in iPaaS.com doesn't change Chargebee.
There is no initialization. History arrives through the first poll's Initial Poll Days window. To bring in a larger history, raise that setting before the first poll, or use bulk sync using Postman.
Before you delete a subscription, set all its Chargebee webhook scopes inactive, one at a time, and check that its endpoint is gone from Chargebee's Webhooks tab.
The Chargebee Integration Known Limitations article lists the other limits.
Post-Installation Verification
Run these checks on a Chargebee test site, with its own subscription. If you must check on a live site, use test records and void or delete them afterwards: every record you create there is a real billing record, Chargebee may email the invoice, and iPaaS.com passes it to the other systems you connect that take it. A voided or deleted invoice then shows as Cancelled.
Connection Test
There is no separate connection test: the first transfer checks the settings. If a transfer's error in Dashboard / Integration Monitoring / Error Logs reads "Unable to connect to subscription with id N", open the company's Logs at the error's time; the CHGB code there names the cause (see Error Messages).
Data Sync Test
In Chargebee, create a test customer with an email you control. Shortly after, it appears in iPaaS.com as a customer with its billing address.
Create an invoice for that customer in Chargebee. It appears in iPaaS.com as an Invoice transaction, with its lines.
After the customer_poll event's next scheduled run, check its activity log in Dashboard / Integration Monitoring: the run completes, with no warning about the poll settings.
Functionality Test
Record a payment on the test invoice in Chargebee. The same transaction in iPaaS.com shows the payment, and its status becomes Complete when the invoice is paid in full.
If you send customers FROM iPaaS.com, create an iPaaS.com test customer with an email you control that your adapted Customer FROM iPaaS.com filter selects. It appears in Chargebee with its billing address.
Error Messages
Errors appear in Dashboard / Integration Monitoring / Error Logs. Every error the Chargebee integration raises starts with a CHGB code and is described in the Chargebee Error Messages article; the messages below that don't start with CHGB come from iPaaS.com itself. iPaaS.com retries a transfer that ends in an error automatically while the error is active, so fix the cause first; the next retry then goes through. Dismiss an active error only when the record should not be retried: dismissing it stops the retry. An error that already shows Retry Pending has started reprocessing, and dismissing it then does not stop that reprocessing. These are the errors most often seen during installation.
"Unable to connect to subscription with id N"
Description: the integration couldn't connect with the saved settings; its reason is in the company's Logs.
Resolution: open Logs at the error's time and follow the CHGB code there.
CHGB-AUTH-1001 in Logs
Description: Chargebee Site holds something that isn't a site name, often the API key pasted into the wrong box (the message then says it looks like an API key).
Resolution: enter the site name in Chargebee Site and the key in API Key, then click Apply.
CHGB-AUTH-1002 in Logs
Description: Chargebee refused the key (HTTP 401, with Chargebee's reason): it is wrong, deleted, or from another site.
Resolution: create a full-access key on the same site and save it in API Key.
CHGB-AUTZ-1001
Description: the key is read-only or restricted, so Chargebee doesn't allow the integration to write.
Resolution: create a full-access key on the same site and save it in API Key.
CHGB-EXTN-1002 in Logs
Description: no answer came back from Chargebee at all, for example because of a Chargebee Site value with extra text in it, or a network or Chargebee outage.
Resolution: check that Chargebee Site holds only your site name or address; if it does, the transfer retries by itself once Chargebee answers again.
CHGB-NFND-1001 in Logs naming site_not_found
Description: Chargebee has no site with the name in Chargebee Site, for example a mistyped site name.
Resolution: correct the setting; your links stay as they are.
CHGB-BIZL-1009 in Logs
Description: Chargebee refused the item price read as incompatible with the site's configuration; the site does not appear to use Product Catalog 2.0.
Resolution: confirm the site's catalog with Chargebee support and ask about moving the site to Product Catalog 2.0, or connect a site that uses it.
CHGB-BIZL-1008 in Logs
Description: Chargebee Site now names another site than the one this subscription remembers.
Resolution: change it back to the site the message names, or add a new subscription for the other site.
CHGB-EXTN-1001
Description: Chargebee refused a value; the message quotes Chargebee's message, code and field.
Resolution: correct the value Chargebee names, usually in the mapping that fills it, then let the transfer retry.
CHGB-EXTN-1004 when setting a webhook scope Active
Description: the site already has five webhook endpoints. Look for the message in the company's Logs.
Resolution: delete an endpoint you no longer use in Chargebee, then set the webhook scope Active again. iPaaS.com also retries the registration while the error is active, but each retry fails until the site has fewer than five endpoints; if you leave the scope inactive, dismiss its active error in Dashboard / Integration Monitoring / Error Logs.
CHGB-EXTN-1005 when setting a webhook scope Active
Description: the subscription's endpoint was created moments ago and Chargebee does not list it yet, for example after two scopes were set Active close together. The message is in the company's Logs.
Resolution: iPaaS.com retries the registration automatically while the error is active, so the scope does not have to be set Active again. After about half an hour, check in Chargebee that the subscription's endpoint carries the scope's event; if it does not, set the scope Active again. If you set the scope inactive instead, dismiss its active error in Dashboard / Integration Monitoring / Error Logs. An error that already shows Retry Pending is reprocessed anyway, so afterwards check the endpoint's events in Chargebee and remove the scope's event there if it was added.
"A data collision occurred…"
Description: the Collision Handling Method on Customer FROM iPaaS.com is Error, and a Chargebee customer already has this email.
Resolution: to keep the two apart, dismiss the error; to link them, choose another method, then send the customer again.
"NFND-1029 - Duplicate transaction found! Transaction Number: …"
Description: another transaction in your company already holds that number, from another system or from this subscription after its link was cleared. The invoice or credit note is not linked to it.
Resolution: free the number in the other system, or give Chargebee documents a prefix of their own in the TransactionNumber mapping of both Add/Update Chargebee Invoice TO iPaaS.com and Add/Update Chargebee Credit Note TO iPaaS.com, as described in the Chargebee to iPaaS.com Invoice Mapping Documentation. Try it on your test subscription first.
"NFND-1003 - Product Id: REPLACE with the SKU of your ad-hoc charge product does not exist or can not be found."
Description: the ad-hoc charge SKU is still the placeholder.
Resolution: create the ad-hoc charge product and put its SKU in both Line collections (see Placeholder Values), then let the transfer retry.
"VALD-1036 - Value (REPLACE with your iPaaS.com payment method for Chargebee … payments) provided for Payment Method is not valid."
Description: that Chargebee payment method's row in Chargebee Payment Method TO iPaaS.com is still the placeholder.
Resolution: put one of your iPaaS.com payment methods in the row, save the translation collection, then let the transfer retry.
VALD-1024
Description: expected when the payment method on a payment or refund has no row in Chargebee Payment Method TO iPaaS.com. Validate this case in a staging environment before relying on it in production.
Resolution: add the row (Chargebee's method on the left, your iPaaS.com payment method on the right), save the translation collection, then let the transfer retry.
Nothing arrives from Chargebee
Description: the webhook scopes aren't Active, the endpoint isn't registered yet, or no poll event is scheduled.
Resolution: check that the scopes are Active in Inbound Data Flows, that Chargebee lists the endpoint "iPaaS.com subscription {id}" as enabled (allow ten minutes or more after the first scope), and add the poll events as a backstop.
Every invoice or credit note arrives twice
Description: a transaction poll event has no Filter rule.
Resolution: add a Filter rule with the Expression invoice on the invoice_poll event, and credit_note on the credit_note_poll event.
Nothing goes to Chargebee
Description: the Customer FROM iPaaS.com filter still holds its placeholder or doesn't select the customer, or the Outbound Data Flows triggers aren't subscribed.
Resolution: check the filter, that the customer meets it, and that customer/created and customer/updated are subscribed.
Chargebee states: "If you receive an HTTP 429 Too Many Requests error response to an API call, it means that the API requests for your Chargebee site have exceeded acceptable limits", and that it "may also send a Retry-After header" (Chargebee API: Error handling). The integration then writes a warning in the transfer's activity log, and the transfer is held and retried after that wait (60 seconds when Chargebee gives none). Subscribers or their MiSP should validate this behaviour in a staging environment before relying on it in production, and keep API Throttle Limit within the site's published limit.
Support and Troubleshooting
Support Portal: https://support.ipaas.com/en/
Contact Information: https://ipaas.com/contact-us/
Chargebee API documentation: https://apidocs.chargebee.com/docs/api
Chargebee support: https://www.chargebee.com/docs/, for API keys, webhook endpoints and Product Catalog 2.0 questions.
Known limitations: see the Chargebee Integration Known Limitations article for the integration's scope and the full list of placeholder values.