New here? This page is a configuration reference for teams implementing the Chargebee integration in iPaaS.com. It documents scope, design decisions, and settings to confirm before go-live. These are not product defects, and most items are handled during implementation by iPaaS.com or your Managed Integration Service Provider (MiSP). See Understanding Integration Scope & Known Limitations for how we document this for every integration.
Introduction
These are the known limitations of the Chargebee integration. They are inherent to the current design of the integration and the capabilities of the Chargebee platform and its API, and they apply to all subscribers at the time this documentation was written. For each limitation, this page describes how the integration behaves and what this means for you.
Platform Scope and Tested Versions
Item | Value |
Remote platform | Chargebee Billing (subscription billing). The integration is built for sites that use Product Catalog 2.0, where plans, addons and charges are items sold through item prices |
Host | Your own Chargebee site's address, for example acme.chargebee.com for the site acme (the Chargebee Site setting holds the site name) |
Chargebee API | Chargebee API version 2, built against Chargebee's documented production API as of 2026-11-04 |
Integration version | 1.0.0 |
Last tested end to end | 2026-11-09 |
Data handled | Customers and their billing address (TO and FROM iPaaS.com); item prices, invoices and credit notes with their lines, payments, refunds, taxes, discounts and addresses (TO iPaaS.com only) |
Not built for:
Chargebee sites on Product Catalog 1.0. The integration reads items and item prices and is not built for sites that use the earlier catalog model (see Product Catalog 2.0 sites, with a full-access API key, below).
Other Chargebee products, such as Chargebee RevRec, Receivables, CPQ, Growth and Reveal. The integration reads and writes only the Chargebee Billing records listed above.
More than one Chargebee site per subscription (see One Chargebee site per subscription, below).
If Chargebee launches a new API version or a new product catalog model, this integration will not automatically support it.
1. Billing records travel only TO iPaaS.com
Chargebee is the system of record for billing. Item prices, invoices, credit notes, and the payments and refunds on them are transferred from Chargebee TO iPaaS.com and are never written back. A FROM iPaaS.com collection for products or transactions added to a Chargebee subscription fails every transfer with CHGB-BIZL-1005.
What this means for you:
Create and change plans, prices, invoices, credit notes and payments in Chargebee. An edit made to one of these records in iPaaS.com does not change Chargebee, and the next transfer from Chargebee replaces it.
Payments recorded in another system are not sent to Chargebee: record them in Chargebee.
If your workflow needs another system's billing records written into Chargebee, submit a feature request to your iPaaS.com partner channel describing it; input like this informs future enhancement releases.
2. Customers FROM iPaaS.com: the customer and its billing address
The only records written to Chargebee are customers (billing accounts) and each customer's billing address, through Add/Update Chargebee Customer FROM iPaaS.com and its child Add/Update Chargebee Customer Billing Address FROM iPaaS.com. The integration never creates or changes subscriptions, payment sources, charges, invoices or credit notes in Chargebee, and it never deletes a Chargebee customer: a customer delete FROM iPaaS.com stops with CHGB-BIZL-1005. Chargebee keeps one billing address per customer, so only the iPaaS.com address marked as the primary billing address is sent.
What this means for you:
Set up subscriptions and payment methods for each customer in Chargebee after the customer arrives there.
Do not subscribe to the customer/deleted trigger for this subscription. To remove a Chargebee customer, do it in Chargebee.
Mark the address that should become the Chargebee billing address as the primary billing address in iPaaS.com. Shipping and other addresses are not sent.
If your workflow needs subscriptions or charges created from iPaaS.com, submit a feature request to your iPaaS.com partner channel.
3. History arrives through the polls, not an initialization run
No data type in this integration offers initialization. Existing Chargebee records reach iPaaS.com through the first run of each scheduled poll, which looks back the number of days in Initial Poll Days (7 when blank), through webhooks as records change, or one at a time through Manual Sync. Item prices also arrive with the first invoice or credit note that bills them. FROM iPaaS.com, existing customers are sent as they are created or updated in iPaaS.com, or one at a time through Manual Sync.
What this means for you:
To bring in more history TO iPaaS.com, raise Initial Poll Days (1 to 3650) before the first poll runs. A larger window makes the first poll run longer.
For a large one-time load in either direction, use Syncing a Large Dataset Using iPaaS.com and Postman Runner.
4. One Chargebee site per subscription
Each Chargebee site keeps its own numbering, so two sites can each hold an invoice 1042. Each iPaaS.com subscription therefore works with one Chargebee site. The subscription remembers the Chargebee site it first exchanged data with. If Chargebee Site is later changed to a different site, every transfer stops with "Unable to connect to subscription with id N", and Logs shows CHGB-BIZL-1008 naming both sites. Correcting a mistyped site name before the first connection is safe: a site that does not exist never exchanges data, so it is never remembered.
What this means for you:
Enter Chargebee Site carefully at install time. It accepts the bare site name (for example acme) or the full site address.
To connect another Chargebee site, including a Chargebee test site, add a separate iPaaS.com subscription for it. If you see CHGB-BIZL-1008, change Chargebee Site back to the site the message names.
Two subscriptions in the same iPaaS.com company each send their own invoice numbers. Give each site's transactions their own prefix (see Transaction numbers are unique across your company, below).
5. Product Catalog 2.0 sites, with a full-access API key
The integration is built for Chargebee sites that use Product Catalog 2.0: it reads Chargebee items and item prices. Before each transfer it checks that the site answers item price requests; when Chargebee refuses that request as incompatible with the site's configuration, the integration treats the site as not using Product Catalog 2.0, the error reads "Unable to connect to subscription with id N", and Logs shows CHGB-BIZL-1009 at the error's time. The integration also writes to Chargebee (customers FROM iPaaS.com, and its own webhook endpoint), which needs a full-access API key. Chargebee describes a full-access key as one "used to access all API resources in your Chargebee site"; when Chargebee refuses a write from a read-only or restricted key, the integration stops the transfer with CHGB-AUTZ-1001.
Other connection problems show the same "Unable to connect to subscription with id N" error, with the reason in Logs: CHGB-NFND-1001 naming site_not_found when no Chargebee site has the name in Chargebee Site (for example, a mistyped site name); CHGB-AUTH-1002 when Chargebee refuses the API key, with Chargebee's reason; CHGB-AUTH-1001 when Chargebee Site holds something that is not a site name (for example the API key pasted into the wrong setting, which is never repeated in the message); CHGB-EXTN-1002 when Chargebee cannot be reached. iPaaS.com refuses to save the subscription with an empty Chargebee Site or API Key.
What this means for you:
Before you subscribe, confirm with Chargebee support that your site uses Product Catalog 2.0 (items and item prices), or connect a site that does. If your site uses another catalog model, validate the connection in a staging environment before relying on it in production.
For CHGB-NFND-1001 naming site_not_found, correct Chargebee Site; existing links are kept.
Create a full-access API key in Chargebee (in the API keys section under Settings > Configure Chargebee, as described in Chargebee API keys) and save it in API Key. If you plan to use a restricted key, validate it in a staging environment before relying on it in production.
When a transfer shows "Unable to connect to subscription with id N", open Logs at the error's time: the code there names the cause.
6. Webhook endpoints: one per subscription, five per site
When the first Chargebee scope is set Active, the integration registers one webhook endpoint in Chargebee named "iPaaS.com subscription" followed by the subscription number, and adds or removes events on it as scopes change. Chargebee states that "you can create up to five webhook endpoints per site" (Chargebee webhook endpoints). Before it registers its endpoint, the integration counts the site's endpoints and, when all five are taken, stops with CHGB-EXTN-1004 instead of registering one.
Scope changes are not instant. The first scope set Active can take several minutes to reach Chargebee, and nothing in iPaaS.com shows when it has. CHGB-EXTN-1005, and by the same registration step CHGB-EXTN-1004, is written to the company's Logs. A new endpoint can also take more than ten minutes to appear in Chargebee's endpoint list; while it is missing from that list, the integration is designed to stop with CHGB-EXTN-1005 rather than register a second endpoint. Several scopes set inactive within a second or two of each other can leave an event on the endpoint that is no longer Active in iPaaS.com, and the endpoint is then not removed when the last scope is set inactive.
What this means for you:
After setting the first scope Active, wait several minutes, then check the site's webhooks in Chargebee for the endpoint named "iPaaS.com subscription" followed by your subscription number, with the events you expect, before you rely on webhooks.
If no endpoint appears, count the site's webhook endpoints in Chargebee. At five, delete one you no longer use, then set the scope Active again. If the endpoint was created but is not listed yet (CHGB-EXTN-1005), iPaaS.com retries the registration automatically while the error is active; after about half an hour, check that the endpoint carries the scope's event, and set the scope Active again if it does not. 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 check the endpoint's events afterwards and remove the scope's event in Chargebee if it was added.
Subscribers or their MiSP should validate webhook registration in a staging environment before relying on it in production.
Set scopes inactive one at a time. After setting the last one inactive, check in Chargebee that the subscription's endpoint is gone, and delete it there if it remains.
Before you delete an iPaaS.com subscription, set all of its Chargebee scopes inactive so its endpoint is removed. Otherwise the endpoint keeps one of the site's five slots until you delete it in Chargebee.
7. Chargebee's API limit counts every request to the site
Chargebee limits the API calls each site can make per minute. Chargebee applies the limit to all API requests made to the site, so every app and iPaaS.com subscription on the site counts toward it. Chargebee publishes 150 calls per minute for test sites, and for live sites a limit that depends on the Chargebee plan (Chargebee error handling and rate limits, as published on 2026-11-09). When Chargebee answers that the limit is exceeded, the integration asks iPaaS.com to hold the transfer until the limit resets (the wait Chargebee states, or 60 seconds) and to retry it then.
What this means for you:
If transfers seem slow, check what else calls your Chargebee site, and don't schedule the poll events more often than you need (every 30 minutes is recommended).
If you plan large loads or share the site with busy apps, validate the behaviour at the limit in a staging environment before relying on it in production.
The iPaaS.com platform throttle settings, including API Throttle Limit (To iPaaS) and API Throttle Seconds (To iPaaS), are described in Chargebee Connections and Settings.
8. Poll events read changes; the transaction polls need a Filter rule
Webhooks are the main way changes arrive. The scheduled poll events (customer_poll, item_price_poll, invoice_poll and credit_note_poll, each added as a scheduled event of the type Webhook (Poll Request); see Events) are a backstop that reads the records Chargebee marks as changed since the last poll. The two transaction polls read the same Chargebee documents: an event with no Filter rule reads both invoices and credit notes. Polls never send deleted records. The credit note poll reads every changed credit note in one run.
What this means for you:
On the invoice_poll event, add an Event Rule with the NAME Filter and the EXPRESSION invoice. On the credit_note_poll event, add an Event Rule with the NAME Filter and the EXPRESSION credit_note. With both events scheduled and no Filter rule, every invoice and credit note is sent twice.
customer_poll and item_price_poll need no Filter rule.
Keep the webhook scopes Active: a poll does not see every change (see Billing status follows the subscription scopes, and Item prices become one product each, below).
A large first window (a high Initial Poll Days) or a long outage makes the first credit note poll run long.
9. Setting warnings appear in the transfer's activity log
When Initial Poll Days (1 to 3650) or Poll Page Size (1 to 100) holds a value out of range or a fraction, the integration uses the nearest bound or the whole number and writes a warning naming the setting and the value it used, never the value entered. When Chargebee refuses the saved paging position of a poll, the poll reads again from the last saved time and writes the warning "Chargebee refused the saved paging cursor; reading again from the saved second." Both warnings appear in the transfer's activity log in Dashboard / Integration Monitoring, not in Logs, and neither stops the transfer. iPaaS.com refuses a value that is not a number in these settings, and saves a blank one as its default (7 days, 100 records per page).
What this means for you:
After changing either setting, open a poll transfer's activity log in Dashboard / Integration Monitoring and check for a warning that names it.
No action is needed for the paging warning: the poll continues on its own.
10. Customers TO iPaaS.com need an email and a name or company
iPaaS.com requires an email on every customer, and at least one of first name, last name or company. The template filter of Add/Update Chargebee Customer TO iPaaS.com skips a Chargebee customer with no email, without an error. It does not check names, so a customer with an email but no first name, last name or company is refused by iPaaS.com with VALD-1039 - Company, First Name, or Last Name must not be null or empty, and the transfer is retried and keeps failing until the customer has one.
What this means for you:
Add an email in Chargebee to any customer that should reach iPaaS.com; the next webhook or poll then sends it.
Add a first name, last name or company in Chargebee to a customer refused with VALD-1039, or extend the collection's filter to also require one of them. Validate a changed filter in a staging environment before relying on it in production.
11. Customers TO iPaaS.com are linked by email
Before a Chargebee customer that is not yet linked is sent, the integration looks for an iPaaS.com customer with the same email, ignoring letter case, and links the two instead of creating a second customer. Linking by email links only the customer: when that iPaaS.com customer already has a primary billing address, the Chargebee billing address is added as a separate address that is also marked as the primary billing address. When several iPaaS.com customers hold the email, the transfer stops with CHGB-BIZL-1002; when the match is already linked to a different Chargebee customer, it stops with CHGB-BIZL-1006. Chargebee allows several customers to share an email.
What this means for you:
After linking existing iPaaS.com customers this way, review their addresses and clear the primary billing flag on the address that should no longer be primary. Otherwise Add/Update Chargebee Customer Billing Address FROM iPaaS.com can pick up either address.
To keep an identical address from being added again, map a Static value of true to PreventDuplicate on Add/Update Chargebee Customer Billing Address TO iPaaS.com. iPaaS.com then skips a new address that matches an existing address in every mapped field, including the primary billing and primary shipping flags. Because a new Chargebee address is not marked as the primary shipping address, an existing address that is also the primary shipping address is never treated as a match. An address that differs in any field is still added.
For CHGB-BIZL-1002, merge the duplicate iPaaS.com customers (for example two whose emails differ only in letter case), then send the Chargebee customer again.
For CHGB-BIZL-1006, give one of the two Chargebee customers a different email, or merge them in Chargebee.
12. Billing status follows the subscription scopes
The four customer custom fields Chargebee Subscription Status, Chargebee Next Billing Date, Chargebee Monthly Recurring Revenue and Chargebee Active Subscriptions are worked out from the customer's Chargebee subscriptions each time the customer is sent. A change to a subscription reaches iPaaS.com through the subscription scopes (subscription_created through subscription_resumed); the customer poll catches it only when Chargebee also marks the customer itself as changed. Chargebee does not always list a subscription under its customer immediately after it is created, so a customer sent in that moment arrives without it, with no error: when it is the customer's only subscription, the status reads none, with 0 active subscriptions and 0 monthly recurring revenue. This is most likely on the transfer the subscription_created webhook starts, which arrives within seconds. The next transfer of the customer after Chargebee lists the subscription, such as a later customer or subscription webhook or a Manual Sync, writes the correct values. Chargebee Monthly Recurring Revenue is empty for a customer whose live subscriptions are billed in more than one currency.
What this means for you:
Keep the subscription scopes Active; they refresh billing status on later subscription changes.
If a customer with a new subscription shows none, send the customer again through Manual Sync a few minutes later, or wait for its next customer or subscription change.
Before you rely on these fields in another system, check a few customers with live subscriptions in iPaaS.com against Chargebee.
13. Deleted records are kept in iPaaS.com
The integration never deletes an iPaaS.com record. A Chargebee customer deleted while the customer_deleted scope is Active keeps its iPaaS.com customer, with Chargebee Subscription Status set to deleted. A deleted invoice or credit note already in iPaaS.com is set to Cancelled. A record deleted before it ever reached iPaaS.com is not sent. For a short time after a customer is deleted, Chargebee can still return it as if it were not deleted: a Manual Sync of that customer run right after the deletion treats it as not deleted, so a customer never sent to iPaaS.com is created in iPaaS.com and linked to the deleted Chargebee customer, and a linked one can read none instead of deleted; no error is raised. The customer_deleted webhook behaves correctly, and scheduled polls never send deleted customers.
What this means for you:
To remove a record from iPaaS.com, delete or deactivate it there after it is deleted in Chargebee.
Wait a few minutes after deleting a customer in Chargebee before running a Manual Sync for it. If a customer was created in iPaaS.com for a deleted Chargebee customer, delete or deactivate it in iPaaS.com.
14. Archive an item price before you delete it
An item price archived in Chargebee is sent only when it is already linked to an iPaaS.com product, and that product becomes Discontinued. Once Chargebee deletes an item price it can no longer be read, so nothing is sent, no error is raised, and the product keeps its last values and status (an active product stays Active). An item price archived before it ever reached iPaaS.com is not sent, so an invoice or credit note line that bills it has no product: the whole document stops with NFND-1003 - Product Id: [item price id] does not exist or can not be found. and keeps stopping on each retry until a product for that item price exists.
What this means for you:
To retire a product in iPaaS.com, archive the item price in Chargebee first, let the transfer mark the product Discontinued, and delete the item price in Chargebee afterwards if needed.
Transfer each item price to iPaaS.com (for example through Manual Sync) before archiving it while invoices or credit notes that bill it have not yet reached iPaaS.com.
For a document stopped with NFND-1003, follow the recovery steps under Archived and Deleted Item Prices in the Add/Update Chargebee Item Price TO iPaaS.com collection description.
15. Item prices become one product each
Each Chargebee item price becomes its own iPaaS.com product whose Sku is the item price id, so an item sold monthly and yearly, or in two currencies, becomes several products; Chargebee Item Id groups them, and item prices are not grouped as variants. Before a first transfer, the integration links an existing iPaaS.com product with the same SKU instead of creating a duplicate; when two products hold the SKU, or the product is linked to another item price, the transfer stops with CHGB-BIZL-1007. Editing the item an item price belongs to (its name, description or type) has no webhook of its own and is not seen by the item price poll. A flat-fee or per-unit item price that Chargebee sends with no price arrives with a DefaultPrice of 0.
What this means for you:
Keep each item price id unique as a product SKU in iPaaS.com. For CHGB-BIZL-1007, remove the duplicate product or give it a different SKU, then send the item price again.
After editing an item in Chargebee, send its item prices through Manual Sync, or wait for their next change.
If your catalog needs one product with variants per item, submit a feature request to your iPaaS.com partner channel.
16. Currencies, decimal pricing and tax
Chargebee states prices in the smallest unit of the currency, and the integration converts them to the normal amount (a USD price of 1999 becomes 19.99); invoice and credit note amounts stay in the document's own currency, with no conversion. The integration does not read the decimal price that Chargebee provides only when multi-decimal pricing is enabled on a site, so extra decimal places may not be carried, and a price Chargebee holds only as a decimal price may arrive as 0 or empty. Chargebee states zero-decimal currencies such as JPY as whole amounts, and the integration sends them unchanged. Each invoice and credit note tax and discount is matched to its iPaaS.com record by its position in Chargebee's list.
What this means for you:
If your Chargebee site bills in more than one currency, in a zero-decimal or three-decimal currency, uses multi-decimal pricing, or charges tax, validate the DefaultPrice and Chargebee Price Tiers of a few products, and the taxes and totals of a few invoices, in a staging environment before relying on them in production.
If Chargebee changes the order or number of taxes or discounts on a document already in iPaaS.com, check that document's taxes and discounts in iPaaS.com.
17. Invoices and credit notes follow Chargebee's lifecycle
Each invoice and credit note in iPaaS.com reflects how Chargebee records it:
Draft (pending) invoices wait. An invoice is sent once Chargebee closes it, even if you change the collection's filter: when Chargebee closes a draft it issues a new invoice, so a draft sent earlier would stay behind in iPaaS.com as a second transaction.
Written-off invoices read Complete. Chargebee marks a written-off invoice paid. Chargebee Write Off Amount holds the unpaid part, and the adjustment credit note for the write-off arrives as a Return with Chargebee Credit Note Reason write_off.
Refunded credit notes. Chargebee marks a credit note refunded when its whole amount is used, refunded or applied to other invoices. Money paid back appears as a refund record with the status Completed.
A payment applied to several invoices refreshes the invoice its webhook names. Any other invoice it paid is refreshed by its own next change.
Overpayments stay on the customer's account in Chargebee: each payment record carries only the part applied to that invoice.
What this means for you:
Use Chargebee Write Off Amount and Chargebee Credit Note Reason to tell written-off invoices apart in other systems.
If a payment covered several invoices, send the others through Manual Sync to refresh them at once.
If your Chargebee site processes chargebacks or payment reversals, validate how they appear on a few invoices in a staging environment before relying on them in production.
18. Transaction numbers are unique across your company
iPaaS.com allows each transaction number once in a company, across all of your systems. A Chargebee number made only of digits is sent as INV-1042 (invoice) or CN-17 (credit note), so it does not meet a plain number from another system. When another transaction in the company already holds the number (another system's, or one of this subscription whose link was cleared), the document is not linked to it: it is refused with NFND-1029 - Duplicate transaction found! Transaction Number: [number], retried, and the other transaction is not changed. Transactions TO iPaaS.com have no Collision Handling Method setting.
What this means for you:
If another system also writes INV- or CN- numbers, or a second Chargebee site sends to the same company, give these transactions 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, for example
return "CB-" + ChargebeeTransactionNumber(DocumentType, DocumentNumber);.The prefix changes only the number iPaaS.com holds, not the numbers in Chargebee.
Change the formula before the first transfer: changing it later renumbers the transactions already in iPaaS.com on their next update. Validate it in a staging environment before relying on it in production.
19. Every invoice needs a customer link or an email
Before an invoice or credit note is saved, its Chargebee customer is sent first through Add/Update Chargebee Customer TO iPaaS.com, whose filter skips a customer with no email. iPaaS.com refuses a transaction with no customer, company or email, so an invoice whose customer is skipped and that carries no email on its billing address stops with VALD-1002 - Required field (Customer Id, Email address, or Company Id) is null or empty in your request. and is retried automatically while the error is active. A credit note is sent after the invoice it credits, so a credit note whose invoice is refused stops with that invoice's error. A credit note that credits no invoice, or whose invoice the invoice collection's filter leaves out, arrives without a parent transaction.
What this means for you:
Give every invoiced Chargebee customer an email, then send the invoice again; the customer is sent first and linked.
Re-send the credit note after its invoice has arrived.
20. Failed prerequisites and errors keep retrying
When a record an invoice or credit note needs (its customer, an item price, or the invoice a credit note credits) cannot be sent first, the document stops with that record's own error, or with CHGB-NFND-1002 naming it, and nothing of the document is written. When Chargebee cannot be reached or has a temporary server problem, the transfer stops with CHGB-EXTN-1002 or CHGB-EXTN-1003. These errors appear in Dashboard / Integration Monitoring / Error Logs, and iPaaS.com retries them automatically while the error is active. Dismissing an active error stops its retry; an error that already shows Retry Pending has started reprocessing, and dismissing it then does not stop that.
What this means for you:
Fix the cause named in the error, for example the prerequisite record's own error, and the document follows on its next retry.
Dismiss an active error only when the record should not be retried. An error that already shows Retry Pending is reprocessed anyway; if that fails again, dismiss the error it raises.
Errors caused by Chargebee being unavailable usually clear once Chargebee recovers.
21. Updates TO iPaaS.com write every mapped field
The iPaaS.com API replaces the whole record on each update, so an update TO iPaaS.com writes every field its collection maps. The default templates map every field that can be overwritten; fields Chargebee does not hold use the DestinationValue function to write back the value iPaaS.com already holds. If you turn off or remove a mapping, the next update writes an empty value or 0 over that field, with no error. For example, an invoice update with the Total mapping removed, or a payment update with the Amount mapping removed, writes 0.
What this means for you:
Keep the default mappings in place. To stop Chargebee owning a field, replace its mapping with a Dynamic Formula that keeps the current value instead of removing it, for example
return DestinationValue != null ? DestinationValue.FirstName : FirstName;for a customer's first name.The Unmapped Field Overwrite Risk section of each mapping collection description lists the fields that collection does not map.
22. Updates FROM iPaaS.com send only what changed
An update FROM iPaaS.com sends only the values that differ from Chargebee's, so Chargebee fields with no mapping keep their values, and a blank value in iPaaS.com never clears a Chargebee value. The integration also 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 that would change it stops with CHGB-BIZL-1003, names the field, and writes nothing. The billing address state name is not mapped, so when an existing billing address gets a new state code, Chargebee keeps the old state name (for example, state code CA with state name Texas).
What this means for you:
To clear a value in Chargebee, clear it in Chargebee.
For CHGB-BIZL-1003, decide which value to keep: set the iPaaS.com field to Chargebee's value, or make the same change in Chargebee, then send the customer again. Dismissing the error alone does not settle it.
After a billing address moves to another state or province, check the state name on the Chargebee customer and correct it in Chargebee.
23. Duplicate handling for customers FROM iPaaS.com
Before it creates a Chargebee customer, the integration searches Chargebee for customers with the same email, the only match field. A single match is handed to the Collision Handling Method set on Add/Update Chargebee Customer FROM iPaaS.com; two or more matches stop the transfer with CHGB-BIZL-1001, because Chargebee allows several customers with one email. A matched customer has never been written by the integration, so under any method that updates it, the iPaaS.com values replace Chargebee's for every field the collection carries. With no method selected, a matching Chargebee customer is linked and nothing is sent to it. The billing address has no duplicate handling of its own: it goes with its customer and updates the linked Chargebee customer's billing address.
What this means for you:
Select a Collision Handling Method before enabling the collection, and validate it in a staging environment before relying on it in production. Choose Error to review each match yourself.
For CHGB-BIZL-1001, merge the Chargebee customers or give all but one a different email, then send the customer again.
24. A retried create can make a second Chargebee customer
A create is not protected against being repeated. If Chargebee creates the customer but iPaaS.com does not save the link to it (for example, the transfer fails after the create, or the link is removed), the next attempt treats the iPaaS.com customer as new. Chargebee's email search does not always return a customer created moments earlier, so that attempt can create a second Chargebee customer, and iPaaS.com links to the newer one.
What this means for you:
After a customer transfer FROM iPaaS.com has failed and been retried, or after a customer's Chargebee link has been removed, search Chargebee's customer list for the customer's email.
If two Chargebee customers hold it, keep the one iPaaS.com is linked to and merge or delete the other in Chargebee before billing starts on it.
25. Each write to Chargebee comes back once TO iPaaS.com
With the customer_created and customer_changed scopes Active, Chargebee reports every customer the integration creates or updates, and iPaaS.com runs a Customer TO iPaaS.com transfer of that customer. For a change to the customer's own fields, one returning transfer follows and then it stops; it does not start another FROM iPaaS.com transfer. A billing address change is written to Chargebee in more than one step and may come back more than once. The returning transfer brings Chargebee's values, including the billing status fields, to the same iPaaS.com customer.
What this means for you:
Expect at least one Customer TO iPaaS.com transfer in Dashboard / Integration Monitoring after each customer write FROM iPaaS.com; no action is needed.
Decide which system owns each customer field before enabling both directions, and validate in a staging environment that billing address changes settle before relying on it in production.
26. Translations: countries need a row, and changes apply once saved
Chargebee accepts only two-letter ISO country codes on a billing address. The Chargebee Country FROM iPaaS.com translation ships with rows for the United States, Canada and the United Kingdom, by name and by code. A customer whose billing country has no row stops with CHGB-VALD-1001, and nothing is written. A change to any translation row applies once the translation collection is saved.
What this means for you:
Before go-live, add a row to Chargebee Country FROM iPaaS.com for every other country your customers use, with the country exactly as iPaaS.com holds it on the left and its two-letter code on the right (for example, Australia to AU).
After editing translation rows, save the translation collection, then send the record again.
Placeholder Values to Replace Before Go-Live
The default templates carry a few values that stand in for something only your company can supply. Until each is replaced, the records that depend on it stop with an error or are not sent. Subscribers or their MiSP should work through this list during implementation. Each entry is also called out in its mapping collection description.
At a glance, grouped by where the value lives:
Add/Update Chargebee Invoice Line TO iPaaS.com
Sku (Dynamic Formula, ad-hoc charges)
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)
Payment Method (Lookup Translation, 33 rows)
Add/Update Chargebee Credit Note Line TO iPaaS.com
Sku (Dynamic Formula, ad-hoc charges)
Add/Update Chargebee Customer FROM iPaaS.com
Mapping filter (example billing-account category)
Placeholders in Add/Update Chargebee Invoice Line TO iPaaS.com
Invoice Line Sku (Dynamic Formula, ad-hoc charges)
Collection: Add/Update Chargebee Invoice Line TO iPaaS.com (child of Add/Update Chargebee Invoice TO iPaaS.com)
Shipped default: for a line that bills an ad-hoc charge, the text REPLACE with the SKU of your ad-hoc charge product; lines that bill an item price use the item price id
Why it's a placeholder: an ad-hoc charge has no item price in Chargebee, so it needs an iPaaS.com product chosen by your company. Until the text is replaced, an invoice with an ad-hoc charge stops with NFND-1003 - Product Id: REPLACE with the SKU of your ad-hoc charge product does not exist or can not be found. Invoices that bill only item prices are not affected.
Suggested action: before the first transfer, either (a) create a product in iPaaS.com for ad-hoc charges (for example, one named Chargebee one-time charge with the SKU CB-ADHOC) and put its SKU in place of the text, keeping the quotes, or (b) put in the SKU of an existing iPaaS.com product. Use the same SKU in the credit note line collection below.
Placeholders in the Chargebee Payment Method TO iPaaS.com translation
Payment Method (Lookup Translation, 33 rows)
Collection: used by Add/Update Chargebee Invoice Payment TO iPaaS.com and Add/Update Chargebee Credit Note Refund TO iPaaS.com
Shipped default: a row for each of 33 commonly used Chargebee payment methods (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 pointing to text of the form REPLACE with your iPaaS.com payment method for Chargebee card payments
Why it's a placeholder: each row must name a payment method that exists in your iPaaS.com company. A payment or refund whose row still holds the placeholder stops its invoice or credit note with VALD-1036; a Chargebee method with no row stops it with an iPaaS.com validation error for the missing payment method. Invoices with no payment yet are not affected.
Suggested action: before the first transfer, replace the placeholder in the row of every method your Chargebee site uses with the exact name of an iPaaS.com payment method (for example, Credit Card in the card row, if your company has a payment method with that name), and add a row for any other method your site uses. Several Chargebee methods can point to the same iPaaS.com payment method. Do not delete rows. Save the translation collection after editing it. Validate in a staging environment how a payment by a method with no row is reported before relying on it in production.
Placeholders in Add/Update Chargebee Credit Note Line TO iPaaS.com
Credit Note Line Sku (Dynamic Formula, ad-hoc charges)
Collection: Add/Update Chargebee Credit Note Line TO iPaaS.com (child of Add/Update Chargebee Credit Note TO iPaaS.com)
Shipped default: for a line that credits an ad-hoc charge, the text REPLACE with the SKU of your ad-hoc charge product
Why it's a placeholder: the same as the invoice line Sku above. Until it is replaced, a credit note with an ad-hoc charge line stops with NFND-1003.
Suggested action: put in the same SKU you chose for the invoice line Sku mapping, keeping the quotes.
Placeholders in Add/Update Chargebee Customer FROM iPaaS.com
Mapping filter (example billing-account category)
Collection: Add/Update Chargebee Customer FROM iPaaS.com
Shipped default: an example filter that sends only customers carrying the customer category REPLACE with the customer category that marks a billing account; the collection ships disabled
Why it's a placeholder: the filter decides which iPaaS.com customers become Chargebee billing accounts. No real customer carries the placeholder category, so nothing is sent until the filter is changed. A customer the filter skips logs no error.
Suggested action: adapt the filter to how your company marks billing customers, for example by replacing the text inside the quotes with the exact name of your own customer category (such as Chargebee Billing Account), by checking a customer custom field that flags billing customers, or by any other condition on the iPaaS.com customer. Test the changed filter with a few customers in a staging environment, then enable the collection.
This page covers 26 known limitations of the Chargebee integration, plus the placeholder values to replace before go-live. For the full behaviour of each mapping collection, see its mapping collection description and its mapping documentation in Chargebee Mapping Collections.