Summary

iPaaS.com Invoice transactions can be transferred from Chargebee invoices through webhook events, a scheduled poll or Manual Sync, using the Add/Update Chargebee Invoice TO iPaaS.com mapping collection. Each transfer also carries the invoice's lines, payments, taxes, discounts and billing and shipping addresses through five child collections: Add/Update Chargebee Invoice Line TO iPaaS.com, Add/Update Chargebee Invoice Payment TO iPaaS.com, Add/Update Chargebee Invoice Tax TO iPaaS.com, Add/Update Chargebee Invoice Discount TO iPaaS.com and Add/Update Chargebee Invoice Address TO iPaaS.com. Accounting, ERP and other systems connected to iPaaS.com can then post each invoice with its balance and payments. Chargebee owns billing, so invoices travel only TO iPaaS.com; draft invoices are held until Chargebee closes them.

ID Format

Manual Sync ID Format

Enter the Chargebee invoice id, which is the invoice number Chargebee shows on the invoice (example: 1042). Enter it as Chargebee shows it, without the INV- prefix that iPaaS.com shows in the transaction number. The invoice's lines, payments, taxes, discounts and addresses travel with it.

External ID Format

After a successful transfer, iPaaS.com saves the Chargebee invoice id (example: 1042) as the external ID on a dedicated external-ID record for the transaction. This is the primary match: later webhooks, polls and Manual Syncs for the same invoice update that transaction instead of adding a new one.

The default template also maps the invoice number into TransactionNumber through the ChargebeeTransactionNumber function, so invoice 1042 becomes INV-1042. That number makes the invoice easy to find on the transaction, but when another system already saved a transaction with the same number, iPaaS.com does not link the invoice to it and refuses the invoice instead (see Collision Handling).

Each child record is saved with its own external ID under the invoice's external ID:

Line: the invoice id, a vertical bar and the Chargebee line item id (example: 1042|li_AzqXVOVZF1mHMmEe).
Payment: the invoice id, a vertical bar and the Chargebee transaction id (example: 1042|txn_ABC123).
Tax: the invoice id, |tax| and the tax's position on the invoice, starting at 1 (example: 1042|tax|1).
Discount: the invoice id, |discount| and the discount's position (example: 1042|discount|1).
Address: the invoice id followed by |billing or |shipping (example: 1042|billing).

A credit note is saved with credit_note: in front of its id, so an invoice and a credit note with the same number in Chargebee never share a link.

Deleted Record Support

Deleting a transaction FROM iPaaS.com is not supported: no delete mapping is included in the default template, and a delete request from iPaaS.com fails with CHGB-BIZL-1005. Void or delete the invoice in Chargebee instead.

Deletions in Chargebee are reflected TO iPaaS.com as a status, never as a deletion. An invoice deleted in Chargebee that is already in iPaaS.com is sent with the status Cancelled, and its existing lines are kept; an invoice deleted before it ever reached iPaaS.com is not sent.

Mapping Collection Status

Status: Enabled. The filter passes closed invoices and holds back drafts (see Mappings).
Trigger Events: the Chargebee webhook scopes invoice_generated, invoice_updated, invoice_deleted, payment_succeeded, payment_failed and payment_refunded, set Active in the subscription's Inbound Data Flows section; the poll scope invoice_poll on a scheduled Webhook (Poll Request) event; and Manual Sync. No invoice transfers occur automatically until subscribers or their MiSP set the scopes Active.

Webhook scope	What it does
invoice_generated	An invoice is generated in Chargebee and is sent with its children.
invoice_updated	An invoice changes (part-paid, paid, voided, written off, its details edited) and is sent again.
invoice_deleted	An invoice deleted in Chargebee is sent with the status Cancelled, only when it is already in iPaaS.com.
payment_succeeded	A payment succeeds; the invoice it pays is sent again with the payment on it.
payment_failed	A payment fails; the invoice is sent again with the failed payment and its dunning status.
payment_refunded	A refund that names no credit note refreshes the invoice it was paid against. A refund made through a credit note is transferred by the Add/Update Chargebee Credit Note TO iPaaS.com collection.

Whether a transfer adds or updates the transaction depends on whether the invoice is already linked in iPaaS.com, not on which event arrived: an invoice_generated event for an invoice that is already linked updates it.

Duplicate or Conflicting Mappings

The Add/Update Chargebee Credit Note TO iPaaS.com collection also writes iPaaS.com transactions from Chargebee, as Returns. The two collections receive documents of the same iPaaS.com data type and are kept apart only by their filters: keep the invoice condition in this collection's filter and the credit_note condition in the credit note collection's filter. There is no FROM iPaaS.com collection for invoices, so changes do not loop between systems. Chargebee is the source of truth for invoice data: an edit made to the transaction in iPaaS.com is replaced by the next transfer of the invoice.

Collision Handling

This collection has no Collision Handling Method setting. An invoice is matched by its external-ID record.

iPaaS.com allows each transaction number only once in a company, across all of the subscriber's systems. When another transaction in the company already holds the invoice's mapped TransactionNumber, whether another system's or one of this subscription whose link was cleared (for example, another system's order saved as INV-1042), iPaaS.com does not link the invoice to it: it refuses the invoice with NFND-1029 - Duplicate transaction found! Transaction Number: INV-1042, and the other transaction is not changed. The platform retries the transfer automatically while the error is active; dismissing an active error in Dashboard / Integration Monitoring / Error Logs stops its retry, but an error already showing Retry Pending is reprocessed anyway. Subscribers or their MiSP who also create transactions with the same numbers from another source should validate in a staging environment how iPaaS.com treats them before relying on it.

The INV- prefix lowers this risk: a plain Chargebee number such as 1042 does not clash with another system's order 1042, which keeps its own number and is not overwritten. It does not remove the risk, because another system can also use INV- numbers. When other systems write INV- numbers, one option is a prefix of your own in the TransactionNumber formula, for example return "CB-" + ChargebeeTransactionNumber(DocumentType, DocumentNumber); (which puts CB- in front of the INV- number). This is an option to validate in a staging environment before relying on it: change both collections together, and change it before the first transfer, because changing the number formula later renumbers the transactions already in iPaaS.com on their next update.

Unmapped Field Overwrite Risk

The iPaaS.com API uses PUT (full record replace) when updating transaction records, so any field a collection does not map is written empty on every update.

Invoice: every subscriber-writable transaction field is mapped in the default template. For the two fields Chargebee does not hold, ParentId and ShippingAmount, the default formulas use the DestinationValue function to write back the value iPaaS.com already holds.
Invoice Line: QtyShipped, Unit, OriginalUnitPrice, DiscountPercent and Weight are not mapped.
Invoice Payment: none; Method, Amount, Status and Description are all mapped.
Invoice Tax: OriginalAmount and TaxPercent are not mapped.
Invoice Discount: CouponId, DiscountTypeId, DiscountMethod and DiscountPercent are not mapped.
Invoice Address: PhoneNumber, Name, Type, ShippingMethod, ShippingMethodDescription, ShippingAmount and ShipDate are not mapped.

If another system sets any of these fields on the iPaaS.com record, or if subscribers or their MiSP remove one of the default mappings, the next update from Chargebee writes that field empty or 0, with no error. The recommended approach is to split the collection into separate Add and Update collections and use the DestinationValue function in the Update collection to carry the existing value forward. For example, a Dynamic Formula return DestinationValue != null ? DestinationValue.Unit : null; mapped to the line's Unit keeps the unit iPaaS.com already holds.

Supported Child Collections

Parent Collection: Add/Update Chargebee Invoice TO iPaaS.com. The children transfer only with their invoice; they have no webhook, poll or Manual Sync of their own. To re-send an invoice's children, run a Manual Sync of the parent invoice.

Add/Update Chargebee Invoice Line TO iPaaS.com: the invoice's lines, one per item price or ad-hoc charge billed, linked by the Chargebee line item id.
Add/Update Chargebee Invoice Payment TO iPaaS.com: every payment attempt Chargebee lists on the invoice, including failed and cancelled ones, linked by the Chargebee transaction id.
Add/Update Chargebee Invoice Tax TO iPaaS.com: one tax record per tax Chargebee applied, linked by its position on the invoice.
Add/Update Chargebee Invoice Discount TO iPaaS.com: the invoice's coupons, credits and manual discounts, linked by position on the invoice.
Add/Update Chargebee Invoice Address TO iPaaS.com: the invoice's billing address and, when it has one, its shipping address.

System Caveats

Chargebee Caveats

Draft invoices: a pending (draft) invoice is never transferred, even if the filter is changed. When Chargebee closes a draft it issues the invoice under a new id, and that closed invoice is transferred once.
Written-off invoices: Chargebee itself marks a written-off invoice paid, so in iPaaS.com its Status reads Complete, the same as a paid invoice. It is told apart by Chargebee Write Off Amount, which holds the part that was never paid, and by the adjustment credit note Chargebee creates for the write-off, which arrives as a Return under the invoice with Chargebee Credit Note Type adjustment and Chargebee Credit Note Reason write_off. Chargebee Amount Paid stays the money actually received.
Overpayments and shared payments: each payment record's Amount is the part of the payment applied to this invoice. When a customer pays more than the invoice total, the invoice reads paid with an amount due of 0, and the excess stays on the customer's account in Chargebee and is not sent. The whole payment amount is not mapped by default (see the Payment collection in Mappings).
Credits applied: credits from a credit note reduce Chargebee Amount Due and appear in Chargebee Credits Applied. They are not payments, so no payment record is added for them.
Failed payments appear as payment records with the status Failed, and Chargebee Dunning Status shows where Chargebee's payment retries stand.
Edited invoices: editing an invoice's details in Chargebee updates the same transaction. Chargebee allows line changes only on a pending invoice, which is not sent.
A payment applied to several invoices: the payment webhook refreshes the invoice it names. Any other invoice the payment paid is refreshed by its own next change in Chargebee or by the poll.
Taxes: tax records come from the taxes Chargebee applied to the invoice. An invoice that Chargebee did not tax sends no tax records and a TaxAmount of 0.
Rate limiting: every app connected to the Chargebee site, and every iPaaS.com subscription on it, shares the site's API limit. When the limit is reached, the transfer waits and is rescheduled automatically after the limit resets, with no error and no subscriber action required. If transfers seem slow, check what else calls the Chargebee site, and do not schedule the poll more often than needed.
Currency and dates: all amounts are in the invoice's own currency, with no conversion; Chargebee Currency names it. Chargebee records dates as UTC timestamps, and they are sent as recorded.

iPaaS.com Caveats

Required fields: the iPaaS.com transaction API requires SystemId, TransactionNumber, Type and Status on every transaction, Type and Status on every line and Method on every payment. The default template maps all of them; keep them mapped.
Customer or email: iPaaS.com refuses a transaction with no customer, company or email, with VALD-1002 - Required field (Customer Id, Email address, or Company Id) is null or empty in your request. See Integration Flow step 2 for when an invoice has no customer.
Transaction numbers: iPaaS.com allows each transaction number once in a company. Keep the ChargebeeTransactionNumber mapping so plain Chargebee numbers carry the INV- prefix (see Collision Handling).
Products: every line's Sku must match an iPaaS.com product. Item price products are sent first automatically; the ad-hoc charge product must be created or chosen by subscribers or their MiSP (see Setup Requirements).
Payment methods: every row of the Chargebee Payment Method TO iPaaS.com translation must name a payment method that exists in the iPaaS.com company (see Setup Requirements).
Transaction custom fields: the eight custom fields the default mappings write must exist in the iPaaS.com company as Transaction custom fields with exactly these names: Chargebee Currency, Chargebee Subscription Id, Chargebee Amount Due, Chargebee Amount Paid, Chargebee Due Date, Chargebee Dunning Status, Chargebee Credits Applied and Chargebee Write Off Amount. To use one in another system, map it in that system's FROM iPaaS.com transaction collection.

Setup Requirements

The integration-wide setup (the Chargebee site, the API key and the subscription settings) is covered in the Chargebee Installation Instructions.

Chargebee Configuration

No setup is needed in Chargebee for invoices. When the first invoice scope is set Active, the integration registers a webhook endpoint in Chargebee named "iPaaS.com subscription" followed by the subscription id, and it adds or removes Chargebee events on that endpoint as scopes are set Active or inactive. It can take ten minutes or more after the first scope is set Active before Chargebee shows a new endpoint.

iPaaS.com Configuration

In the subscription's Inbound Data Flows section, set Active the invoice scopes listed under Mapping Collection Status.
Add a scheduled event of the type Webhook (Poll Request) for this subscription with the poll scope invoice_poll and an Event Rule named Filter with the Expression invoice. Without that Filter rule, either transaction poll reads both invoices and credit notes, so with both the invoice and credit note poll events scheduled every document is sent twice. Every 30 minutes is the recommended schedule. The first poll looks back the number of days in the Initial Poll Days subscription setting; each later poll picks up from the last change it saw.
Confirm that the eight Transaction custom fields listed under iPaaS.com Caveats exist.
Replace the two placeholder values below.

Values to Replace Before Go-Live

Placeholder value — replace during implementation: the ad-hoc charge SKU. The Sku formula of Add/Update Chargebee Invoice Line TO iPaaS.com ships with the text REPLACE with the SKU of your ad-hoc charge product for lines that bill an ad-hoc charge (a charge with no item price), and that text is not a real SKU. Subscribers or their MiSP MUST either (a) create a product in iPaaS.com to stand 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 in quotes, keeping the quotes, OR (b) put in the SKU of an existing iPaaS.com product. Make the same change in Add/Update Chargebee Credit Note Line TO iPaaS.com. Until then, 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. Like any iPaaS.com product, the ad-hoc charge product reaches every system that receives products FROM iPaaS.com; if one of them should not show it, have that system's filter leave it out.

Placeholder value — replace during implementation: the payment methods. The Chargebee Payment Method TO iPaaS.com translation, used by the Invoice Payment collection and the Credit Note Refund collection, ships with 33 rows. The left side of each row is Chargebee's code for a payment method; the right side ships as placeholder text of the form REPLACE with your iPaaS.com payment method for Chargebee card payments, which is not a payment method. For each method the Chargebee site uses, subscribers or their MiSP MUST either (a) create an iPaaS.com payment method and put its name in place of the placeholder, OR (b) put in the name of an existing iPaaS.com payment method. For example, a company whose iPaaS.com payment methods include Credit Card and Check would put Credit Card in the card row and Check in the check row. Several Chargebee methods may point to the same iPaaS.com payment method. If it is not known which methods the site uses, fill every row; do not delete rows, and add a row for any other Chargebee method the site uses. Invoices with no payment yet are not affected.

Integration Flow

When a webhook event arrives, the poll finds a changed invoice, or a Manual Sync is run, the integration processes the invoice in this order:

Read the invoice from Chargebee. The integration reads the full invoice by its id. A pending (draft) invoice stops here and is not sent. An invoice deleted in Chargebee is sent as Cancelled only when it is already linked in iPaaS.com; otherwise nothing is sent.
Transfer the customer first, when it is not already linked. The invoice's Chargebee customer goes through the Add/Update Chargebee Customer TO iPaaS.com collection, so that collection's filter applies; for example, it skips a customer with no email. Subscribers or their MiSP do not need to sync customers first. When the customer is not sent:
- an invoice whose billing address carries an email is saved without a customer, with that email;
- an invoice with no email on its billing address or customer is refused with VALD-1002; the platform retries it automatically while its error is active; dismissing an active error stops its retry, but an error already showing Retry Pending is reprocessed anyway. Give every invoiced Chargebee customer an email, then re-send the invoice.
Transfer each item price billed on the lines, when it is not already linked. Each goes through the Add/Update Chargebee Item Price TO iPaaS.com collection and becomes the iPaaS.com product whose SKU the line uses. Ad-hoc charges have no item price and are not sent this way. An item price archived in Chargebee before it ever reached iPaaS.com is not sent, so a line that bills it stops the invoice with NFND-1003. To recover, see Archived and Deleted Item Prices in the Add/Update Chargebee Item Price TO iPaaS.com collection description.
Stop if a prerequisite failed. If the customer or an item price cannot be transferred, the invoice transfer stops with that record's own error or with CHGB-NFND-1002 and is retried automatically while its error is active; dismissing an active error stops its retry, but an error already showing Retry Pending is reprocessed anyway. Nothing of the invoice is written.
Apply the filter and map the invoice. The collection's filter passes closed invoices; each mapping then builds the transaction, including TransactionNumber with its INV- prefix and the eight Chargebee custom fields.
Map the children. Lines, payments, taxes, discounts and addresses are mapped through the five child collections, each child under its own external ID (see ID Format).
Save the transaction. A new invoice adds a transaction and saves the Chargebee invoice id as its external ID; an invoice already linked updates its transaction and children. If iPaaS.com refuses the transaction (a number already in use, a missing customer and email, a SKU or payment method that does not exist), nothing of the invoice is saved, and the error appears in Dashboard / Integration Monitoring / Error Logs.

Mappings

Add/Update Chargebee Invoice TO iPaaS.com

iPaaS.com data type: Transaction

Mapping Filter

// Closed invoices: a pending (draft) invoice still changes before Chargebee closes it
return DocumentType == "invoice" && Status != "pending";

Filter Description. Only Chargebee documents whose DocumentType is invoice and whose Status is not pending are processed. Credit notes fail the first condition and are left to the Add/Update Chargebee Credit Note TO iPaaS.com collection. Pending invoices fail the second condition: Chargebee describes a pending invoice as one that is "yet to be closed", and it can still change, so it is held back and transferred once Chargebee closes it. A skipped document raises no error. The integration also never sends a pending invoice even if this filter is changed.

Description: Transfers each closed Chargebee invoice TO iPaaS.com as an Invoice transaction, adding it on the first transfer and updating it on every later one, with its totals, dates, status, customer and eight Chargebee custom fields.

Mapping Type	Source Field (Chargebee)	Destination Field (iPaaS.com)	Description
Dynamic Formula	`return SpaceportSystemId;`	SystemId	Required. Records this Chargebee subscription as the system the transaction comes from. Do not change this formula.
Dynamic Formula	`return ChargebeeTransactionNumber(DocumentType, DocumentNumber);`	TransactionNumber	Required. The Chargebee invoice number; a number that is only digits gets INV- in front (1042 becomes INV-1042), and a number that already contains letters is kept as it is. It is visible on the transaction; a number another transaction in the company already holds (another system's, or one of this subscription whose link was cleared) is not linked and stops the invoice with NFND-1029 (see Collision Handling).
Static	`"Invoice"`	Type	Required. Every Chargebee invoice is saved as an Invoice. Do not change this value.
Lookup	Lookup Translation: Chargebee Document Status TO iPaaS.com	Status	Required. Chargebee's invoice status in iPaaS.com terms (see the translation table below). A written-off invoice reads Complete because Chargebee marks it paid.
Dynamic Formula	`return ChargebeeCustomerIPaaSId(CustomerId);`	CustomerId	Recommended. The iPaaS.com customer this subscription linked to the invoice's Chargebee customer. Returns nothing when the customer has no link; the invoice is then saved only if it carries an email. If the lookup itself fails, the transfer stops with CHGB-INTL-1002 and retries.
Field	CustomerEmail	EmailAddress	Recommended. The email on the invoice's billing address, else the Chargebee customer's email. Keep it mapped: it is what lets an invoice whose customer is not in iPaaS.com be saved.
Dynamic Formula	`return DestinationValue != null ? DestinationValue.ParentId : null;`	ParentId	Optional. A Chargebee invoice has no parent; on an update the parent iPaaS.com already holds is kept, and on a new transaction nothing is written. Keep the mapping.
Field	SubTotal	Subtotal	Recommended. The line amounts less line-item discounts; excludes tax unless the site uses tax-inclusive pricing.
Field	DiscountTotal	DiscountAmount	Recommended. The total of the discounts on the invoice (each is also sent through the Discount child).
Field	TaxTotal	TaxAmount	Recommended. The total tax Chargebee applied; 0 for an untaxed invoice.
Dynamic Formula	`return DestinationValue != null ? (object)DestinationValue.ShippingAmount : 0;`	ShippingAmount	Optional. Chargebee bills no shipping; on an update the amount iPaaS.com holds is kept, and a new transaction gets 0. Keep the mapping.
Field	Total	Total	Recommended. The invoice total, in the invoice's currency.
Field	TotalQuantity	TotalQty	Recommended. The sum of the quantities on the invoice's lines.
Dynamic Formula	`return string.IsNullOrEmpty(Date) ? (DateTimeOffset?)null : DateTimeOffset.Parse(Date);`	TransactionCreatedDateTime	Recommended. The invoice date, as a UTC timestamp; nothing is written when Chargebee sends no date.
Dynamic Formula	`return string.IsNullOrEmpty(UpdatedAt) ? (DateTimeOffset?)null : DateTimeOffset.Parse(UpdatedAt);`	TransactionUpdatedDateTime	Recommended. When the invoice last changed in Chargebee, as a UTC timestamp.
Field	CurrencyCode	Chargebee Currency (custom field)	Optional. The invoice's three-letter currency code; every amount is in this currency, with no conversion. Keep it mapped if the site bills in more than one currency.
Field	SubscriptionId	Chargebee Subscription Id (custom field)	Optional. The Chargebee subscription the invoice belongs to; empty for a one-time charge.
Field	AmountDue	Chargebee Amount Due (custom field)	Optional. What is still owed; it falls as payments succeed and credits are applied, and is 0 once paid.
Field	AmountPaid	Chargebee Amount Paid (custom field)	Optional. The payments Chargebee collected; credits applied and amounts written off are not included.
Dynamic Formula	`return string.IsNullOrEmpty(DueDate) ? (DateTimeOffset?)null : DateTimeOffset.Parse(DueDate);`	Chargebee Due Date (custom field)	Optional. The invoice's due date, as a UTC timestamp; nothing is written when there is none.
Field	DunningStatus	Chargebee Dunning Status (custom field)	Optional. Where Chargebee's payment retries stand: in_progress, exhausted, stopped or success; empty when no retries have run.
Field	CreditsApplied	Chargebee Credits Applied (custom field)	Optional. Credits applied against the invoice, for example from a credit note; they reduce the amount due and add no payment record.
Field	WriteOffAmount	Chargebee Write Off Amount (custom field)	Optional. The amount Chargebee wrote off; this is how a written-off invoice, which reads Complete, is told apart from a paid one.

Lookup Translation Tables

Chargebee Document Status TO iPaaS.com (no change needed; shared with the credit note collection):

Source Value	Destination Value	Notes
paid	Complete	Also a written-off invoice, which Chargebee marks paid.
posted	Pending
payment_due	Awaiting Payment
not_paid	Awaiting Payment
pending	Draft	Never reached on an invoice: pending invoices are not sent.
voided	Cancelled
deleted	Cancelled	Sent only for an invoice already in iPaaS.com.
adjusted	Complete	Credit notes.
refunded	Refunded	Credit notes.
refund_due	Pending	Credit notes.

Add/Update Chargebee Invoice Line TO iPaaS.com (Child)

iPaaS.com data type: Transaction Line

Description: Transfers each line of the invoice as a transaction line. A line bills one item price (a plan, addon or charge at one price point) or an ad-hoc charge. This child collection has no mapping filter: every line is processed.

Mapping Type	Source Field (Chargebee)	Destination Field (iPaaS.com)	Description
Static	`"Product"`	Type	Required. Every Chargebee line bills a plan, addon, charge or ad-hoc charge, all of which are products in iPaaS.com. Do not change this value.
Static	`"Complete"`	Status	Required. A billing line has nothing left to fulfil. Subscribers or their MiSP may change the value if downstream systems expect another line status.
Dynamic Formula	`return IsAdhoc ? "REPLACE with the SKU of your ad-hoc charge product" : Sku;`	Sku	Recommended. The Chargebee item price id, which is the SKU of the product the integration creates for it. An ad-hoc charge takes the SKU in quotes, which is a placeholder to replace (see Values to Replace Before Go-Live). A SKU that matches no iPaaS.com product stops the invoice with NFND-1003.
Field	SequenceNumber	SequenceNumber	Recommended. The line's position on the invoice, starting at 1.
Field	Description	Description	Recommended. The line's description in Chargebee, for example the plan or charge name.
Field	Quantity	Qty	Recommended. The quantity billed.
Field	UnitAmount	UnitPrice	Recommended. The unit price, in the invoice's currency.
Field	Amount	ExtendedPrice	Recommended. The line amount before discounts; excludes tax unless the site uses tax-inclusive pricing.
Field	DiscountAmount	DiscountAmount	Recommended. The discounts on this line; 0 when there are none.
Field	TaxRate	TaxPercent	Recommended. The tax rate on the line, in percent; empty when the line is not taxed.
Field	TaxAmount	EstimatedTaxAmount	Recommended. The tax on this line; 0 when the line is not taxed.

Add/Update Chargebee Invoice Payment TO iPaaS.com (Child)

iPaaS.com data type: Transaction Payment

Description: Transfers every payment attempt Chargebee lists on the invoice, including failed, cancelled and pending ones, as payment records on the transaction. Only a payment with the status Completed is money received. This child collection has no mapping filter.

Mapping Type	Source Field (Chargebee)	Destination Field (iPaaS.com)	Description
Lookup	Lookup Translation: Chargebee Payment Method TO iPaaS.com	Method	Required. Chargebee's payment method as an iPaaS.com payment method. Every row ships with a placeholder to replace (see Values to Replace Before Go-Live).
Field	Amount	Amount	Recommended. The part of the payment applied to this invoice, not the whole payment.
Lookup	Lookup Translation: Chargebee Payment Status TO iPaaS.com	Status	Recommended. Chargebee's transaction status in iPaaS.com terms (see the translation table below).
Dynamic Formula	The Description formula shown after this table	Description	Optional. Identifies the payment in Chargebee: "Chargebee payment", the Chargebee transaction id, "via" and the gateway when there is one, and ", reference" and the reference number (such as a check number) when there is one.

The Description formula:

return "Chargebee " + Kind + " " + TransactionId + (string.IsNullOrEmpty(Gateway) || Gateway == "not_applicable" ? "" : " via " + Gateway) + (string.IsNullOrEmpty(ReferenceNumber) ? "" : ", reference " + ReferenceNumber);

Transaction Amount is not mapped by default. The whole amount of the Chargebee payment is available in this collection as the source field TransactionAmount; Amount carries only this invoice's share. Subscribers or their MiSP who want the whole amount on the payment record can append it to the Description formula, for example by adding + " of " + TransactionAmount before the closing semicolon. Validate the changed formula in a staging environment on one invoice before relying on it.

Lookup Translation Tables

Chargebee Payment Status TO iPaaS.com (no change needed; shared with the credit note refund collection):

Source Value	Destination Value	Notes
success	Completed	Money received.
failure	Failed
timeout	Failed
voided	Cancelled
in_progress	Pending
needs_attention	Pending

Chargebee also documents the status late_failure, for a successful payment that the gateway later reports as failed. It has no row; subscribers or their MiSP may add one (for example, late_failure to Failed) if their gateways report late failures.

Chargebee Payment Method TO iPaaS.com (placeholder rows to replace): it ships with one row for each of these 33 Chargebee methods, every destination set to REPLACE with your iPaaS.com payment method for Chargebee followed by the method and payments: 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. Example rows once replaced, in a company whose payment methods include Credit Card, Check and Bank Transfer:

Source Value	Destination Value	Notes
card	Credit Card	Example: use a payment method name from the subscriber's own iPaaS.com company.
check	Check	Example.
bank_transfer	Bank Transfer	Example.

Add/Update Chargebee Invoice Tax TO iPaaS.com (Child)

iPaaS.com data type: Transaction Tax

Description: Transfers one tax record per tax Chargebee applied to the invoice, with its name and amount. The parent's TaxAmount is the sum of these taxes. An untaxed invoice sends no tax records. This child collection has no mapping filter.

Mapping Type	Source Field (Chargebee)	Destination Field (iPaaS.com)	Description
Field	Name	Authority	Recommended. The tax's name as Chargebee shows it on the invoice. The tax's description is also available as a source field.
Field	Amount	Amount	Recommended. The amount of this tax, in the invoice's currency.

Each tax is matched to its iPaaS.com record by its position on the invoice. If Chargebee ever lists a transferred invoice's taxes in a different order or number, a later transfer updates the records by position, not by name.

Add/Update Chargebee Invoice Discount TO iPaaS.com (Child)

iPaaS.com data type: Transaction Discount

Description: Transfers the invoice's coupons, credits and manual discounts as discount records. The parent's DiscountAmount is the sum of these amounts. This child collection has no mapping filter.

Mapping Type	Source Field (Chargebee)	Destination Field (iPaaS.com)	Description
Dynamic Formula	`return !string.IsNullOrEmpty(CouponId) ? CouponId : EntityType;`	CouponCode	Recommended. The Chargebee coupon id for a coupon, or Chargebee's discount id for a manual discount; when Chargebee gives a discount no id, the kind of discount, such as promotional_credits or prorated_credits. No iPaaS.com coupon needs to exist.
Field	Amount	DiscountAmount	Recommended. The discount amount, in the invoice's currency.

Discounts are matched by position on the invoice, in the same way as taxes.

Add/Update Chargebee Invoice Address TO iPaaS.com (Child)

iPaaS.com data type: Transaction Address

Description: Transfers the invoice's billing address and, when it has one, its shipping address. This child collection has no mapping filter.

Mapping Type	Source Field (Chargebee)	Destination Field (iPaaS.com)	Description
Dynamic Formula	`return Type == "Billing";`	IsPrimaryBilling	Recommended. True for the billing address, false for the shipping address.
Dynamic Formula	`return Type == "Shipping";`	IsPrimaryShipping	Recommended. True for the shipping address, false for the billing address.
Field	FirstName	FirstName	Recommended. The first name on the address.
Field	LastName	LastName	Recommended. The last name on the address.
Field	Company	Company	Recommended. The company name on the address.
Field	Line1	Address1	Recommended. The first street line.
Field	Line2	Address2	Optional. The second street line, empty when there is none.
Field	Line3	Address3	Optional. The third street line, empty when there is none.
Field	City	City	Recommended. The city.
Field	StateCode	Region	Recommended. The state or province code, for example CA. The full name is available as the source field State.
Field	Country	Country	Recommended. The two-letter ISO country code Chargebee stores, for example US or GB.
Field	Zip	PostalCode	Recommended. The postal or ZIP code.

Error Handling

Errors appear in Dashboard / Integration Monitoring / Error Logs, and nothing of the invoice is saved while one stands. Where an entry below says the transfer is retried, the platform retries it automatically while its error is active; dismissing an active error stops its retry, but an error already showing Retry Pending is reprocessed anyway. Fix the cause so a retry can succeed, or re-send the invoice. The full catalog is in the Chargebee Error Messages article.

"NFND-1029 - Duplicate transaction found! Transaction Number: INV-1042": another transaction in the company already holds the invoice's number (another system's, or one of this subscription whose link was cleared). The invoice is not linked to it and is retried. Free the number on the other transaction, or change the number formula (see Collision Handling).
"VALD-1002 - Required field (Customer Id, Email address, or Company Id) is null or empty in your request.": the invoice has no linked customer and no email. It is retried. Give the Chargebee customer an email, then re-send the invoice.
"NFND-1003 - Product Id: ... does not exist or can not be found.": a line's SKU matches no iPaaS.com product. When the SKU is REPLACE with the SKU of your ad-hoc charge product, replace the ad-hoc charge SKU; when it is an item price id, the item price was archived in Chargebee before it reached iPaaS.com, and the invoice is retried; see Archived and Deleted Item Prices in the Add/Update Chargebee Item Price TO iPaaS.com collection description to recover.
VALD-1036: a payment's method translates to a value that is not an iPaaS.com payment method, usually a row still holding its placeholder. Replace the row, then re-send the invoice.
VALD-1024: expected when a payment's Chargebee method has no row in the Payment Method translation. Add the row, then re-send the invoice. Validate in a staging environment how iPaaS.com treats a method with no row before relying on it in production.
CHGB-NFND-1002 (or the prerequisite record's own error, such as a customer refused by iPaaS.com): the customer or an item price the invoice needs could not be sent first. The invoice is retried; open that record's own error, fix it, and the invoice follows on the next retry.
CHGB-INTL-1002: iPaaS.com could not look up the invoice's linked customer. The transfer is retried; if it keeps failing, contact iPaaS.com Support.
CHGB-BIZL-1005: a FROM iPaaS.com collection, or a delete, was set up for invoices. Remove or turn off that collection.

After changing a translation row, save the translation collection, then re-send the invoice. After changing a mapping, re-send the invoice.

Testing & Validation

Test Scenarios

Close an invoice in Chargebee for a new customer and a new item price, and confirm that the customer and the product arrive first and that one Invoice transaction arrives with its lines, payments, discounts and addresses.
Record a part payment, then the rest, and confirm that the same transaction updates: the payments accumulate, Chargebee Amount Due falls to 0 and the status moves from Awaiting Payment to Complete.
Create a draft (pending) invoice and confirm that nothing is sent; close it and confirm that it arrives once, under the number Chargebee gives it.
Void an invoice and confirm that its transaction becomes Cancelled; delete an invoice already in iPaaS.com and confirm that it becomes Cancelled and keeps its lines.
Write off an invoice and confirm that it reads Complete, that Chargebee Write Off Amount holds the written-off part, and that the adjustment credit note arrives as a Return with the reason write_off.
Record a payment larger than the invoice total and confirm that the payment record's Amount is the applied amount and the excess is not sent.
Run a Manual Sync with the Chargebee invoice id and confirm that the existing transaction updates without a duplicate.
Bill an ad-hoc charge with the SKU still set to REPLACE and confirm the NFND-1003 error; replace the SKU and confirm that the line lands.
Send an invoice whose INV- number another system's transaction already holds and confirm the NFND-1029 error and that the other transaction is unchanged.
Send an invoice of a customer with no email, once with a billing-address email (saved without a customer) and once with no email anywhere (refused with VALD-1002).
If the Chargebee site applies tax, close a taxed invoice and confirm one tax record per tax and a matching TaxAmount.

Validation Checklist

The invoice scopes are Active in Inbound Data Flows, and a Webhook (Poll Request) event runs with the poll scope invoice_poll.
The ad-hoc charge SKU is replaced in both the Invoice Line and Credit Note Line collections, and that product exists in iPaaS.com.
Every Payment Method translation row the site uses names an existing iPaaS.com payment method.
The eight Chargebee Transaction custom fields exist in the iPaaS.com company.
Every invoiced Chargebee customer has an email.
No other system writes transaction numbers that Chargebee invoices can carry, or Chargebee documents have a prefix of their own.

Additional Notes

Out of Scope

Invoices FROM iPaaS.com: invoices are created and changed only in Chargebee. A FROM iPaaS.com transaction collection for invoices fails with CHGB-BIZL-1005.
Initialization: there is no initialization for invoices. 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.
Changes in iPaaS.com are not written back: editing the transaction in iPaaS.com does not change Chargebee, and the next transfer of the invoice replaces the edit.

Chargebee to iPaaS.com Invoice Mapping Documentation