Summary

iPaaS.com products can be transferred from Chargebee item prices (Add or Update) through webhook events, a scheduled poll, invoice and credit note transfers, or Manual Sync, using the Add/Update Chargebee Item Price TO iPaaS.com mapping collection. In Chargebee, an item price is one way of selling a plan, addon or charge: one currency and, for plans and addons, one billing period. Each item price becomes its own iPaaS.com product whose Sku is the Chargebee item price id, so the lines of Chargebee invoices and credit notes transferred TO iPaaS.com find their products by that SKU. The collection has no child collections, and item prices travel only TO iPaaS.com.

ID Format

Manual Sync ID Format

Enter the Chargebee item price id, exactly as Chargebee shows it on the item price (example: pro-plan-USD-Monthly). Do not enter the item id: one item usually has several item prices, one for each currency and billing period.

External ID Format

After a successful transfer, iPaaS.com saves the Chargebee item price id (example: pro-plan-USD-Monthly) as the external ID on a dedicated external-ID record for the product. This is the primary match: later transfers of the same item price update the same product instead of creating a new one.

The default mappings also write the item price id into the product's Sku. This makes the link visible on the product, and it is the fallback match: before an item price is transferred for the first time, the integration looks for an existing iPaaS.com product with that SKU and links to it instead of creating a duplicate (see SKU Matching and Duplicate Handling). Remapping Sku to a different source is supported, but it stops that SKU match, and invoice and credit note lines would no longer find their products.

Deleted Record Support

Deletes are not supported. The integration does not delete products in iPaaS.com, and the default template has no delete mapping for this collection.

Once an item price is deleted in Chargebee, Chargebee no longer returns it, so nothing is sent, no error is raised, and the iPaaS.com product keeps its last values and status: an Active product stays Active. To retire a product in iPaaS.com, archive the item price in Chargebee first and let the transfer mark the product Discontinued, then delete the item price in Chargebee afterwards if needed.

Mapping Collection Status

Status: Enabled
Trigger Events: the Chargebee webhook scopes item_price_created and item_price_updated, set Active in the subscription's Inbound Data Flows section, and the poll scope item_price_poll on a scheduled Webhook (Poll Request) event. No automatic transfers occur until these are set up. Item prices are also transferred as a prerequisite of an invoice or credit note, and Manual Sync is always available.

Trigger	What it does
item_price_created	Sends a new item price. Whether the transfer adds a product or updates one depends on whether the item price is already linked, not on which scope fired.
item_price_updated	Sends a changed item price, including one that was just archived.
item_price_poll	On each scheduled run, sends the item prices Chargebee reports as changed since the previous poll, so an item price whose webhook was missed still arrives. The first poll looks back the number of days in the Initial Poll Days subscription setting.
Invoice or credit note transfer	Sends any active item price billed on the document that is not yet in iPaaS.com, before the document itself.

Duplicate or Conflicting Mappings

This is the only mapping collection in the Chargebee integration that works with products. The integration does not send products FROM iPaaS.com to Chargebee: a Product FROM iPaaS.com collection added for Chargebee fails every transfer with CHGB-BIZL-1005.

If another integration in your iPaaS.com company also creates or updates products, subscribers or their MiSP should decide which system is the source of truth for each product field. This collection overwrites the fields it maps from Chargebee (Sku, Name, Type, TrackingMethod, Status, DefaultPrice, a non-empty Description, and the six Chargebee product custom fields) on every transfer, so an edit made to those fields in iPaaS.com or by another integration is replaced the next time the item price changes in Chargebee.

SKU Matching and Duplicate Handling

Before an item price that is not yet linked is transferred, the integration looks for an iPaaS.com product whose Sku equals the item price id, ignoring letter case:

No product with that SKU: a new product is created and linked.
One product with that SKU, not linked to another item price: the item price is linked to that product, and the transfer updates it instead of creating a duplicate.
More than one product with that SKU, or one product already linked to a different Chargebee item price: nothing is sent, and the transfer fails with CHGB-BIZL-1007. The same error can appear on an invoice or credit note whose item price is transferred first.

This matching is built into the integration. There is no Collision Handling Method setting to configure for this collection.

Unmapped Field Overwrite Risk

The iPaaS.com API replaces the whole product record on every update, so any product field this collection did not map would be written empty each time an item price is transferred. The default template maps every product field. Fields that Chargebee does not hold are mapped with formulas that write back the value iPaaS.com already holds, so they are preserved:

AllowBackorders
AllowDiscounts
Barcode
Depth
Height
InStockThreshold
MSRP
SalePrice
TaxClass
Unit
Weight
Width
Description, when Chargebee has no description for the item price or its item

Keep these mappings in place. If one is turned off or removed, the next update writes that field empty in iPaaS.com, with no error. These mappings use the DestinationValue function in a Dynamic Formula: for example, the Barcode mapping reads DestinationValue.Barcode, the value the iPaaS.com product currently holds, and writes it back. Use the same pattern for any field you want to keep with your own mappings. On a new product there is no current value, so these fields start empty. Product categories are a separate list on the product and are not changed by this collection.

Supported Child Collections

This collection has no child collections. Each item price is one product with no variants.

System Caveats

Chargebee Caveats

Product Catalog 2.0: The integration is built for Chargebee sites that use Product Catalog 2.0 and reads items and item prices. When Chargebee refuses the integration's item price check as incompatible with the site's configuration, every transfer fails and Logs shows CHGB-BIZL-1009. If your site uses another catalog model, validate the connection in a staging environment before relying on it in production.
Rate limits: Chargebee limits the API requests your Chargebee site can make, across every app that uses it. When the limit is reached, the transfer is rescheduled automatically and runs again after the limit resets. No action is required.
Prices in the smallest currency unit: Chargebee states item prices in the smallest unit of the currency (cents for USD), and the integration converts each price to the normal amount, so a USD price of 1999 becomes 19.99. Chargebee states amounts in zero-decimal currencies such as JPY as whole amounts, and the integration sends them unchanged.
Other currencies: For a currency that is not a two-decimal or zero-decimal currency (for example a three-decimal currency such as KWD or BHD), subscribers or their MiSP should check the DefaultPrice and Chargebee Price Tiers of a few transferred products in a staging environment before relying on them in production.
Multi-decimal pricing: The integration reads Chargebee's standard price. It does not read the decimal price that Chargebee provides only when multi-decimal pricing is enabled on the site, so decimal places beyond what the currency normally uses may not be carried, and a price that Chargebee holds only as a decimal price may arrive as 0 or empty. If your Chargebee site uses multi-decimal pricing, subscribers or their MiSP must check the DefaultPrice and Chargebee Price Tiers of transferred products in a staging environment before relying on them in production.
Tiered, volume and stairstep pricing: Chargebee holds these prices only in tiers, so DefaultPrice is the first tier's price: the per-unit price of the first tier for tiered and volume pricing, and the total price of the first tier for stairstep pricing. Every tier is recorded in Chargebee Price Tiers.
No price: A flat-fee or per-unit item price that Chargebee returns with no price is sent with a DefaultPrice of 0.
One product per currency and billing period: An item sold monthly and yearly, or in two currencies, has one item price for each in Chargebee and so becomes several iPaaS.com products. Chargebee Item Id groups them.
Reused item price ids: Chargebee allows the id of a deleted item price to be used again. A new item price created with that id is linked to the existing iPaaS.com product and updates it.
Archived item prices: An archived item price is sent only when it is already linked to an iPaaS.com product, and the default Status mapping marks that product Discontinued. The product is kept, with its SKU and link. An item price archived before it was ever transferred is not sent, no product is created for it, and no error is raised.

iPaaS.com Caveats

Product custom fields: The default mappings write the Product custom fields Chargebee Item Id, Chargebee Item Type, Chargebee Currency, Chargebee Billing Frequency, Chargebee Pricing Model and Chargebee Price Tiers. The template adds these Product custom fields. Keep their names unchanged: if one is deleted or renamed, its mapping stops storing a value.
Unique SKUs: Keep each item price id unique as a product SKU in iPaaS.com. Duplicates stop the transfer with CHGB-BIZL-1007.
Invoice and credit note lines need their products: Every invoice or credit note line must find an iPaaS.com product. A line that bills an item price archived before it reached iPaaS.com has no product, so the whole invoice or credit note stops (see Error Handling).

Setup Requirements

Chargebee: No setup is needed on the Chargebee side. When the first Chargebee scope is set Active, the integration registers its own webhook endpoint in Chargebee.
iPaaS.com: Set the item_price_created and item_price_updated scopes Active in the subscription's Inbound Data Flows section, and add a scheduled Webhook (Poll Request) event with the item_price_poll scope. The connection, the Initial Poll Days setting and the recommended poll schedule are described in the Chargebee Installation Instructions.

Integration Flow

Trigger: A Chargebee item price webhook, a scheduled poll, an invoice or credit note transfer that needs the item price, or a Manual Sync with the item price id starts the transfer.
Read the item price: The integration reads the item price from Chargebee.
- When Chargebee no longer returns it (it was deleted), nothing is sent and the transfer ends without an error.
- When it is archived and not yet linked to an iPaaS.com product, nothing is sent and the transfer ends without an error.
- Otherwise the integration also reads the item the price belongs to, for its type, name and description.
Match an existing product: When the item price is not yet linked, the integration looks for an iPaaS.com product with the item price id as its SKU, ignoring letter case, and links to it when exactly one free match exists. Two or more matches, or a match linked to another item price, stop the transfer with CHGB-BIZL-1007.
Map the fields: The mappings in this collection build the product: SKU, name, description, type, tracking method, status, default price, the six Chargebee product custom fields, and the fields kept from iPaaS.com.
Save the product: A linked item price updates its product; an unlinked one creates a product. iPaaS.com saves the item price id as the product's external ID, so later transfers update the same product.

Mappings

Add/Update Chargebee Item Price TO iPaaS.com

iPaaS.com data type: Product

Description: Transfers each Chargebee item price TO iPaaS.com as one product, created on the first transfer and updated on every later one, with no mapping filter.

Mapping Type	Source Field (Chargebee)	Destination Field (iPaaS.com)	Description
Field	Id	Sku	Required. The Chargebee item price id (example: pro-plan-USD-Monthly). Invoice and credit note lines find their products by this SKU, and it is the fallback match for an existing product before the first transfer. Keep this mapping as it is.
Field	DisplayName	Name	Required. The name customers see for the item price in Chargebee: its external name, or its internal name when no external name is set. To use the internal Chargebee name instead, map the source field Name.
Dynamic Formula	`return !string.IsNullOrEmpty(Description) ? Description : (DestinationValue != null ? DestinationValue.Description : null);`	Description	Recommended. The item price's description, or its item's description when the item price has none. When neither has one, the description iPaaS.com already holds is kept. Any HTML in the Chargebee description is transferred as it is.
Static	`"Virtual"`	Type	Required. Allowed values: Physical, Virtual. Every product is Virtual, because a plan, addon or charge is billed, never shipped.
Field	Price	DefaultPrice	Required. The item price's price, converted to the normal amount for its currency (USD 1999 becomes 19.99). For tiered, volume and stairstep pricing, the first tier's price. 0 for a flat-fee or per-unit item price with no price. The currency is in Chargebee Currency.
Dynamic Formula	`return IsInactive ? "Discontinued" : "Active";`	Status	Required. Allowed values: Preorder, Active, Disabled, Discontinued. Active for an active item price; Discontinued for an archived item price that is already linked to a product.
Static	`"Product"`	TrackingMethod	Required. Allowed values: Product, Variant. Keep Product: each item price is its own product, and this collection does not create variants.
Field	ItemId	Chargebee Item Id	Recommended. The id of the Chargebee item (plan, addon or charge) the item price belongs to. It groups the products that sell the same item in different currencies or billing periods.
Field	ItemType	Chargebee Item Type	Optional. plan, addon or charge, as Chargebee sends it; taken from the item when the item price does not carry it.
Field	CurrencyCode	Chargebee Currency	Recommended. The three-letter currency code of the item price (for example, USD), which is the currency of DefaultPrice. Without it, the price carries no currency in iPaaS.com.
Field	BillingFrequency	Chargebee Billing Frequency	Optional. How often the item price is billed, in words: for example Every month, Every 3 months, or One time when the item price has no billing period (as for a one-off charge).
Field	PricingModel	Chargebee Pricing Model	Optional. flat_fee, per_unit, tiered, volume or stairstep, as Chargebee sends it. For the last three, DefaultPrice is only the first tier's price.
Field	Tiers	Chargebee Price Tiers	Optional. The price tiers of a tiered, volume or stairstep item price as a JSON list, each with its starting unit, ending unit and price converted in the same way as DefaultPrice. Empty for flat-fee and per-unit item prices.
Dynamic Formula	`return DestinationValue != null ? (object)DestinationValue.AllowBackorders : null;`	AllowBackorders	Optional. Chargebee has no backorder setting: the value iPaaS.com holds is kept. A new product starts empty.
Dynamic Formula	`return DestinationValue != null ? (object)DestinationValue.AllowDiscounts : null;`	AllowDiscounts	Optional. Chargebee has no product-level discount setting: the value iPaaS.com holds is kept. To make every Chargebee product allow discounts, replace this formula with a Static value of true.
Dynamic Formula	`return DestinationValue != null ? (object)DestinationValue.Barcode : null;`	Barcode	Optional. Chargebee has no barcode: the value iPaaS.com holds is kept. A new product starts empty.
Dynamic Formula	`return DestinationValue != null ? (object)DestinationValue.Depth : null;`	Depth	Optional. Chargebee has no product dimensions: the value iPaaS.com holds is kept. A new product starts empty.
Dynamic Formula	`return DestinationValue != null ? (object)DestinationValue.Height : null;`	Height	Optional. Chargebee has no product dimensions: the value iPaaS.com holds is kept. A new product starts empty.
Dynamic Formula	`return DestinationValue != null ? (object)DestinationValue.InStockThreshold : null;`	InStockThreshold	Optional. Chargebee has no stock threshold: the value iPaaS.com holds is kept. A new product starts empty.
Dynamic Formula	`return DestinationValue != null ? (object)DestinationValue.MSRP : null;`	MSRP	Optional. Chargebee has no manufacturer's suggested retail price: the value iPaaS.com holds is kept. A new product starts empty.
Dynamic Formula	`return DestinationValue != null ? (object)DestinationValue.SalePrice : null;`	SalePrice	Optional. Chargebee has no sale price: the value iPaaS.com holds is kept. A new product starts empty.
Dynamic Formula	`return DestinationValue != null ? (object)DestinationValue.TaxClass : null;`	TaxClass	Optional. Chargebee's tax settings are not transferred to the product: the value iPaaS.com holds is kept. A new product starts empty.
Dynamic Formula	`return DestinationValue != null ? (object)DestinationValue.Unit : null;`	Unit	Optional. Chargebee has no unit of measure: the value iPaaS.com holds is kept. A new product starts empty.
Dynamic Formula	`return DestinationValue != null ? (object)DestinationValue.Weight : null;`	Weight	Optional. Chargebee has no product weight: the value iPaaS.com holds is kept. A new product starts empty.
Dynamic Formula	`return DestinationValue != null ? (object)DestinationValue.Width : null;`	Width	Optional. Chargebee has no product dimensions: the value iPaaS.com holds is kept. A new product starts empty.

For a tiered price with a first tier of 1250 (units 1 to 10) and a second tier of 999 (from unit 11) in USD, DefaultPrice is 12.50 and Chargebee Price Tiers holds [{"starting_unit":1,"ending_unit":10,"price":12.5},{"starting_unit":11,"ending_unit":null,"price":9.99}].

The default mappings contain no values that subscribers or their MiSP must replace, and the collection uses no lookup translations.

Error Handling

Failed transfers appear in Dashboard / Integration Monitoring / Error Logs. The Chargebee Error Messages article lists every code with its cause and fix. The errors subscribers are most likely to see with item prices:

CHGB-BIZL-1007 (duplicate or taken SKU): Two or more iPaaS.com products have the item price id as their SKU, or the one product with that SKU is already linked to a different Chargebee item price, so nothing is sent. Remove the duplicate products in iPaaS.com, or give one of them a different SKU, then re-sync the item price. iPaaS.com retries the transfer automatically, and it succeeds once the duplicate SKU is fixed.
NFND-1003 - Product Id: [item price id] does not exist or can not be found. This appears on an invoice or credit note, not on the item price: a line bills an item price that was archived in Chargebee before it ever reached iPaaS.com, so the line has no product. Nothing of that invoice or credit note is saved, and iPaaS.com retries it automatically, but the document keeps stopping until a product for that line's item price exists in iPaaS.com. Chargebee does not document a way to make an archived item price active again. It does document that activating an archived plan activates all of the plan's price points (this applies to a plan's price points only, not to addons or charges); once the item price is active, transfer it (for example through Manual Sync with its item price id) and the invoice or credit note can then be transferred, on its next retry or through Manual Sync. Otherwise, subscribers or their MiSP should contact Chargebee about the archived item price before deciding how to bring that invoice or credit note in. To avoid this, transfer each item price to iPaaS.com before archiving it.
CHGB-BIZL-1005 (operation not supported): A Product FROM iPaaS.com collection was run for Chargebee. Item prices are set up in Chargebee, never FROM iPaaS.com: remove or turn off the Product FROM iPaaS.com collection.
CHGB-BIZL-1009 (site not built for this integration): Chargebee refused the integration's item price check as incompatible with the site's configuration. Confirm with Chargebee support that the site uses Product Catalog 2.0 (items and item prices), or connect a site that does.

Testing & Validation

Test Scenarios

Create a plan item price in Chargebee and confirm that one iPaaS.com product is created with the item price id as its Sku, the expected Name, DefaultPrice and Status Active, and the six Chargebee product custom fields filled.
Create a second item price for the same item with another billing period and confirm it becomes a separate product with the same Chargebee Item Id.
Create a tiered item price and confirm that DefaultPrice is the first tier's price and that Chargebee Price Tiers lists every tier in the normal currency amount.
Change the price and external name of an item price in Chargebee and confirm the same product is updated, with no second product, and that a barcode or weight entered in iPaaS.com is kept.
Archive an item price that is already in iPaaS.com and confirm its product becomes Discontinued and is kept.
Archive a new item price before it is ever transferred, send it, and confirm no product is created and no error is raised.
Manually sync an item price by its id from the iPaaS.com Manual Sync page and confirm the transfer completes.
On a site that uses currencies other than two-decimal currencies, or multi-decimal pricing, transfer a few item prices in a staging environment and compare DefaultPrice and Chargebee Price Tiers with Chargebee.

Validation Checklist

The item_price_created and item_price_updated scopes are Active in Inbound Data Flows.
A scheduled Webhook (Poll Request) event with the item_price_poll scope exists.
The six Chargebee Product custom fields exist in iPaaS.com with their names unchanged.
No two iPaaS.com products share a Chargebee item price id as their SKU.
Every default mapping, including the ones that keep iPaaS.com values, is still turned on.

Additional Notes

Out of Scope

Products FROM iPaaS.com: The integration never creates or changes item prices in Chargebee. A Product FROM iPaaS.com collection fails with CHGB-BIZL-1005.
Deletes: The integration does not delete products in iPaaS.com or item prices in Chargebee. Deleting an item price in Chargebee sends nothing; archive item prices instead.
Variants: Each item price is a separate product. Item prices are not grouped as variants of one product.
Initial data load: The integration does not support Initialize for item prices. The first poll brings in item prices changed within Initial Poll Days, and older item prices arrive when they next change, through Manual Sync, or with the first invoice or credit note that bills them. For a large one-time load, see Syncing a Large Dataset Using iPaaS.com and Postman Runner.

Operational Notes

Deleting an item price leaves its product unchanged: At the time this documentation was written, deleting an item price in Chargebee does not change its iPaaS.com product, which keeps its last values and status. Archive the item price first so its product becomes Discontinued, then delete it in Chargebee if needed.
Archiving a price before it reaches iPaaS.com: At the time this documentation was written, an item price archived before it was ever transferred is not sent, and an invoice or credit note that bills it keeps stopping with NFND-1003 until a product for that item price exists in iPaaS.com (see Error Handling). Transfer each item price before archiving it.
Editing the item does not send its item prices: At the time this documentation was written, editing the item an item price belongs to (for example its description or type) is not a trigger for this collection. The change reaches iPaaS.com the next time the item price itself is transferred, for example through Manual Sync.
Changes made in iPaaS.com are not sent to Chargebee: Editing a mapped field on the product in iPaaS.com does not change Chargebee, and the next transfer from Chargebee replaces the edit.

Chargebee to iPaaS.com Item Price Mapping Documentation