Summary
iPaaS.com Return transactions can be transferred from Chargebee credit notes through webhook events, a scheduled poll or Manual Sync, using the Add/Update Chargebee Credit Note TO iPaaS.com mapping collection. iPaaS.com has no credit transaction type, so each credit note is saved as a Return whose parent is the transaction of the invoice it credits. Each transfer also carries the credit note's lines, refunds, taxes, discounts and addresses through five child collections: Add/Update Chargebee Credit Note Line TO iPaaS.com, Add/Update Chargebee Credit Note Refund TO iPaaS.com, Add/Update Chargebee Credit Note Tax TO iPaaS.com, Add/Update Chargebee Credit Note Discount TO iPaaS.com and Add/Update Chargebee Credit Note Address TO iPaaS.com. Accounting and ERP systems connected to iPaaS.com can then apply the credit or refund against that invoice. Chargebee owns billing, so credit notes travel only TO iPaaS.com.
ID Format
Manual Sync ID Format
Enter credit_note: followed by the Chargebee credit note id, with no spaces (example: credit_note:CN-17). The credit_note: prefix is required: a value without it is read as an invoice id. The credit note's lines, refunds, taxes, discounts and addresses travel with it.
External ID Format
After a successful transfer, iPaaS.com saves the same value (credit_note: plus the Chargebee credit note id, for example credit_note:CN-17) as the transaction's external ID on a dedicated external-ID record. This is the primary match: later changes to the credit note, such as a refund or a void, update the same Return instead of adding a new one. The prefix keeps credit note links apart from invoice links, because Chargebee numbers invoices and credit notes separately and the same number can appear in both.
The default template also maps the credit note number into TransactionNumber through the ChargebeeTransactionNumber function: a number made only of digits gets CN- in front (credit note 17 becomes CN-17), and a number that already contains letters, such as a site prefix (SITE-CN-17), is kept as it is. That number makes the credit note easy to find; iPaaS.com allows each transaction number once in a company (see Collision Handling).
Each child record is saved with its own external ID under the credit note's external ID:
Line: the credit note id, a vertical bar and the Chargebee line item id (example: credit_note:CN-17|li_AzqXVOVZF1mHMmEe).
Refund: the credit note id, a vertical bar and the Chargebee transaction id (example: credit_note:CN-17|txn_ABC123).
Tax: the credit note id, |tax| and the tax's position, starting at 1 (example: credit_note:CN-17|tax|1).
Discount: the credit note id, |discount| and the discount's position (example: credit_note:CN-17|discount|1).
Address: the credit note id followed by |billing or |shipping (example: credit_note:CN-17|billing).
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 credit note in Chargebee instead.
Deletions in Chargebee are reflected TO iPaaS.com as a status, never as a deletion. A credit note deleted in Chargebee that is already in iPaaS.com is sent with the status Cancelled; a credit note deleted before it ever reached iPaaS.com is not sent. Chargebee itself refuses to delete a credit note that has been allocated to an invoice.
Mapping Collection Status
Status: Enabled. The filter passes Chargebee credit notes (see Mappings).
Trigger Events: the Chargebee webhook scopes credit_note_created, credit_note_updated, credit_note_deleted and payment_refunded, set Active in the subscription's Inbound Data Flows section; the poll scope credit_note_poll on a scheduled Webhook (Poll Request) event; and Manual Sync. No credit note transfers occur automatically until subscribers or their MiSP set the scopes Active.
Webhook scope | What it does |
credit_note_created | A credit note is created in Chargebee and is sent with its children. |
credit_note_updated | A credit note changes, for example when it is refunded, applied or voided, and is sent again. |
credit_note_deleted | A credit note deleted in Chargebee is sent with the status Cancelled, only when it is already in iPaaS.com. |
payment_refunded | A refund made through a credit note sends that credit note again with the refund on it. A refund that names no credit note refreshes its invoice through the Add/Update Chargebee Invoice TO iPaaS.com collection instead. |
Whether a transfer adds or updates the Return depends on whether the credit note is already linked in iPaaS.com, not on which event arrived.
Duplicate or Conflicting Mappings
The Add/Update Chargebee Invoice TO iPaaS.com collection also writes iPaaS.com transactions from Chargebee, as Invoices, and the credit note's parent invoice is transferred through it. The two collections receive documents of the same iPaaS.com data type and are kept apart only by their filters: before changing either filter, make sure every credit note still matches this collection and no invoice does. There is no FROM iPaaS.com collection for credit notes, so changes do not loop between systems. Chargebee is the source of truth: an edit made to the Return in iPaaS.com is replaced by the next transfer of the credit note.
Collision Handling
This collection has no Collision Handling Method setting. A credit note 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. For invoices, a number another transaction in the company already holds, whether another system's or one of this subscription whose link was cleared, is not linked: the invoice is refused with NFND-1029 - Duplicate transaction found! and retried (see the Chargebee to iPaaS.com Invoice Mapping Documentation). Subscribers or their MiSP who also create transactions with CN- numbers from another source should validate in a staging environment how iPaaS.com treats a credit note whose number another transaction already holds.
The CN- prefix lowers the risk of a clash with a plain number. When other systems write CN- numbers, one option is a prefix of your own in the TransactionNumber formula of both this collection and the invoice collection, for example return "CB-" + ChargebeeTransactionNumber(DocumentType, DocumentNumber); (which puts CB- in front of the CN- 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.
Credit Note: every standard transaction field a Chargebee credit note can fill is mapped in the default template. ShippingAmount, which Chargebee does not hold, is mapped with a formula that keeps the value iPaaS.com already holds (0 on a new transaction).
Credit Note Line: QtyShipped, Unit, OriginalUnitPrice, DiscountPercent and Weight are not mapped.
Credit Note Refund: none; Method, Amount, Status and Description are all mapped.
Credit Note Tax: OriginalAmount and TaxPercent are not mapped.
Credit Note Discount: CouponId, DiscountTypeId, DiscountMethod and DiscountPercent are not mapped.
Credit Note 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, as the default ShippingAmount mapping does with return DestinationValue != null ? (object)DestinationValue.ShippingAmount : 0;.
Supported Child Collections
Parent Collection: Add/Update Chargebee Credit Note TO iPaaS.com. The children transfer only with their credit note; they have no webhook, poll or Manual Sync of their own. To re-send a credit note's children, run a Manual Sync of the parent with the credit note's id.
Add/Update Chargebee Credit Note Line TO iPaaS.com: one line per credited item price or ad-hoc charge, linked by the Chargebee line item id.
Add/Update Chargebee Credit Note Refund TO iPaaS.com: one payment record per refund issued from the credit note, including failed and cancelled ones, linked by the Chargebee transaction id.
Add/Update Chargebee Credit Note Tax TO iPaaS.com: one tax record per tax Chargebee applied, linked by its position.
Add/Update Chargebee Credit Note Discount TO iPaaS.com: one discount record per coupon, credit or manual discount, linked by its position.
Add/Update Chargebee Credit Note Address TO iPaaS.com: the credit note's billing address and, when it has one, its shipping address.
System Caveats
Chargebee Caveats
Credit note types: Chargebee issues adjustment, refundable and store credit notes. An adjustment credit note lowers the amount of an invoice that is still unpaid; refundable and store credit notes hold credit for the customer. The type is saved to Chargebee Credit Note Type.
Write-offs: writing off an invoice in Chargebee creates an adjustment credit note with the reason write_off. It arrives as a Return under the written-off invoice with Chargebee Credit Note Type adjustment and Chargebee Credit Note Reason write_off, so other systems can tell it apart from a refund. Chargebee itself marks the written-off invoice paid, so the invoice's own status reads Complete.
Refunded does not always mean money paid out: Chargebee marks a credit note refunded when its whole amount has been used, either refunded or applied to other invoices. Money paid back appears as a refund record with the status Completed; a credit applied to a later invoice adds no refund record and shows on that invoice's Chargebee Credits Applied instead.
Reason codes: Chargebee sets a reason on each credit note, for example write_off or chargeback. Reason codes created in the Chargebee app are case-sensitive and are saved exactly as Chargebee holds them.
Taxes: tax records come from the taxes Chargebee applied to the credit note. A credit note 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.
Currency and dates: all amounts are in the credit note'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 refund. 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 4.
Transaction numbers: iPaaS.com allows each transaction number once in a company. Keep the ChargebeeTransactionNumber mapping so plain Chargebee numbers carry the CN- 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).
Failed lookups stop the transfer: if iPaaS.com cannot look up the linked customer or invoice while the credit note is being mapped, the transfer stops with CHGB-INTL-1002 and is retried automatically, rather than saving the Return without its customer or parent.
Transaction custom fields: the four 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 Credit Note Type and Chargebee Credit Note Reason. 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 credit notes. When the first 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 credit note scopes listed under Mapping Collection Status.
Add a scheduled event of the type Webhook (Poll Request) for this subscription with the poll scope credit_note_poll and an Event Rule named Filter with the Expression credit_note. 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 four Transaction custom fields listed under iPaaS.com Caveats exist.
Replace the two placeholder values below. Both are shared with the invoice collections.
Values to Replace Before Go-Live
Placeholder value — replace during implementation: the ad-hoc charge SKU. The Sku formula of Add/Update Chargebee Credit Note Line TO iPaaS.com ships with the text REPLACE with the SKU of your ad-hoc charge product for lines that credit an ad-hoc charge, 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. Use the same product in Add/Update Chargebee Invoice Line TO iPaaS.com. Until then, a credit note with an ad-hoc charge line stops with NFND-1003 - Product Id: REPLACE with the SKU of your ad-hoc charge product does not exist or can not be found. Credit notes that credit only item prices are not affected.
Placeholder value — replace during implementation: the payment methods. The Chargebee Payment Method TO iPaaS.com translation, used by the Credit Note Refund collection and the Invoice Payment 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 refunds through, 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. Credit notes without refunds are not affected.
Integration Flow
When a webhook event arrives, the poll finds a changed credit note, or a Manual Sync is run, the integration processes the credit note in this order:
Read the credit note from Chargebee. The integration reads the full credit note by its id. A credit note deleted in Chargebee is sent as Cancelled only when it is already linked in iPaaS.com; otherwise nothing is sent, and no prerequisite is transferred for a deleted credit note.
Transfer the customer first, when it is not already linked. The credit note'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.
Transfer each item price on the lines, when it is not already linked. Each goes through the Add/Update Chargebee Item Price TO iPaaS.com collection. Ad-hoc charge lines have no item price and are not sent this way.
Transfer the invoice the credit note credits, when it is not already linked. The invoice goes through the Add/Update Chargebee Invoice TO iPaaS.com collection, with its own prerequisites. If that invoice is refused, the credit note stops with the invoice's error. For example, when the customer is skipped and the invoice has no email on its billing address or customer, the invoice is refused with VALD-1002, and the credit note stops with the same error even when the credit note itself carries an email. Give every invoiced Chargebee customer an email, then re-send the invoice and the credit note. No subscription setting turns any of these steps on or off.
Stop if a prerequisite failed. If the customer, an item price or the invoice cannot be transferred, the credit note 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 credit note is written.
Apply the filter and map the credit note. The collection's filter passes credit notes; each mapping then builds the Return, including ParentId (the invoice's transaction), TransactionNumber with its CN- prefix and the four Chargebee custom fields.
Map the children. Lines, refunds, taxes, discounts and addresses are mapped through the five child collections, each child under its own external ID (see ID Format).
Save the Return. A new credit note adds a Return and saves credit_note: plus its id as the external ID; a credit note already linked updates its Return 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 credit note is saved, and the error appears in Dashboard / Integration Monitoring / Error Logs.
Mappings
Add/Update Chargebee Credit Note TO iPaaS.com
iPaaS.com data type: Transaction
Mapping Filter
// Credit notes return DocumentType == "credit_note";
Filter Description. Only Chargebee documents whose DocumentType is credit_note are processed. Invoices fail the condition and are left to the Add/Update Chargebee Invoice TO iPaaS.com collection; a skipped document raises no error. Every credit note passes, whatever its status.
Description: Transfers each Chargebee credit note TO iPaaS.com as a Return transaction under the invoice it credits, adding it on the first transfer and updating it on every later one, with its totals, dates, status, customer and four Chargebee custom fields.
Mapping Type | Source Field (Chargebee) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| SystemId | Required. Records this Chargebee subscription as the system the transaction comes from. Do not change this formula. |
Dynamic Formula |
| TransactionNumber | Required. The Chargebee credit note number; a number that is only digits gets CN- in front (17 becomes CN-17). It is visible on the transaction; iPaaS.com allows each number once in a company (see Collision Handling). |
Static |
| Type | Required. iPaaS.com has no credit transaction type, so a credit note is a Return. Do not change this value. |
Lookup | Lookup Translation: Chargebee Document Status TO iPaaS.com | Status | Required. Chargebee's credit note status in iPaaS.com terms (see the translation table below). |
Dynamic Formula |
| ParentId | Recommended. The iPaaS.com transaction of the invoice this credit note credits; for example, a credit note against invoice 1042, linked to transaction 880, gives 880. Empty when the credit note credits no invoice or the invoice is not in iPaaS.com. If the lookup itself fails, the transfer stops with CHGB-INTL-1002 and retries. |
Dynamic Formula |
| CustomerId | Recommended. The iPaaS.com customer this subscription linked to the credit note's Chargebee customer. Empty when the customer has no link; see Integration Flow step 4 for a credit note whose invoice is refused. |
Field | CustomerEmail | EmailAddress | Recommended. The email on the credit note's billing address, else the Chargebee customer's email. iPaaS.com needs a customer, a company or an email on every transaction; keep it mapped. |
Field | SubTotal | Subtotal | Recommended. The credited 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 credit note. |
Field | TaxTotal | TaxAmount | Recommended. The total tax Chargebee applied; 0 for an untaxed credit note. |
Dynamic Formula |
| 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 credit note total, in its currency. |
Field | TotalQuantity | TotalQty | Recommended. The sum of the quantities on the credit note's lines. |
Dynamic Formula |
| TransactionCreatedDateTime | Recommended. The credit note date, as a UTC timestamp. |
Dynamic Formula |
| TransactionUpdatedDateTime | Recommended. When the credit note last changed in Chargebee, as a UTC timestamp. |
Field | CurrencyCode | Chargebee Currency (custom field) | Optional. The credit note's three-letter currency code; every amount is in this currency. |
Field | SubscriptionId | Chargebee Subscription Id (custom field) | Optional. The Chargebee subscription the credit note belongs to; empty when it belongs to none. |
Field | CreditNoteType | Chargebee Credit Note Type (custom field) | Recommended. adjustment, refundable or store. |
Field | ReasonCode | Chargebee Credit Note Reason (custom field) | Recommended. Chargebee's reason code, for example write_off or chargeback, exactly as Chargebee holds it. |
Lookup Translation Tables
Chargebee Document Status TO iPaaS.com (no change needed; shared with the invoice collection, so keep the invoice rows when changing it). The credit note rows:
Source Value | Destination Value | Notes |
adjusted | Complete | |
refund_due | Pending | |
refunded | Refunded | The whole amount has been used: refunded or applied to other invoices. |
voided | Cancelled | |
deleted | Cancelled | Sent only for a credit note already in iPaaS.com. |
The same translation maps the invoice statuses paid, posted, payment_due, not_paid and pending (see the Chargebee to iPaaS.com Invoice Mapping Documentation).
Add/Update Chargebee Credit Note Line TO iPaaS.com (Child)
iPaaS.com data type: Transaction Line
Description: Transfers each line of the credit note as a transaction line on the Return: one line per credited item price or ad-hoc charge. This child collection has no mapping filter.
Mapping Type | Source Field (Chargebee) | Destination Field (iPaaS.com) | Description |
Static |
| Type | Required. Every credited line is a product in iPaaS.com. Do not change this value. |
Static |
| Status | Required. A credit line has nothing left to fulfil. |
Dynamic Formula |
| Sku | Recommended. The Chargebee item price id, which is the product's SKU. 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 credit note with NFND-1003. |
Field | SequenceNumber | SequenceNumber | Recommended. The line's position on the credit note, starting at 1. |
Field | Description | Description | Recommended. The line's description in Chargebee, usually the item price or charge credited. |
Field | Quantity | Qty | Recommended. The quantity credited. |
Field | UnitAmount | UnitPrice | Recommended. The unit price, in the credit note'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 Credit Note Refund TO iPaaS.com (Child)
iPaaS.com data type: Transaction Payment
Description: Transfers every refund Chargebee lists on the credit note, including failed and cancelled ones, as payment records on the Return. Only a refund with the status Completed is money paid back. 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 refund applied to this credit note. |
Lookup | Lookup Translation: Chargebee Payment Status TO iPaaS.com | Status | Recommended. Chargebee's transaction status in iPaaS.com terms: success to Completed, failure and timeout to Failed, voided to Cancelled, in_progress and needs_attention to Pending. |
Dynamic Formula | The Description formula shown after this table | Description | Optional. Identifies the refund in Chargebee, for example "Chargebee refund txn_ABC123" for an offline refund with no reference. |
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 refund transaction is available in this collection as the source field TransactionAmount; Amount carries only this credit note's share. Subscribers or their MiSP who want the whole amount 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 credit note before relying on it.
The Chargebee Payment Status TO iPaaS.com and Chargebee Payment Method TO iPaaS.com translations are shared with the invoice payment collection; their rows are listed in the Chargebee to iPaaS.com Invoice Mapping Documentation. Chargebee also documents the status late_failure, which has no row; subscribers or their MiSP may add one, for example to Failed.
Add/Update Chargebee Credit Note Tax TO iPaaS.com (Child)
iPaaS.com data type: Transaction Tax
Description: Transfers one tax record per tax Chargebee applied to the credit note, with its name and amount. The parent's TaxAmount is the sum of these taxes; an untaxed credit note 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 credit note. |
Field | Amount | Amount | Recommended. The amount of this tax, in the credit note's currency. |
Each tax is matched to its iPaaS.com record by its position on the credit note, not by name.
Add/Update Chargebee Credit Note Discount TO iPaaS.com (Child)
iPaaS.com data type: Transaction Discount
Description: Transfers the credit note's coupons, credits and manual discounts as discount records, matched by position. This child collection has no mapping filter.
Mapping Type | Source Field (Chargebee) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| 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 prorated_credits or promotional_credits. No iPaaS.com coupon needs to exist. |
Field | Amount | DiscountAmount | Recommended. The discount amount, in the credit note's currency. |
Add/Update Chargebee Credit Note Address TO iPaaS.com (Child)
iPaaS.com data type: Transaction Address
Description: Transfers the credit note'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 |
| IsPrimaryBilling | Recommended. True for the billing address, false for the shipping address. |
Dynamic Formula |
| 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. |
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 credit note 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 credit note. The full catalog is in the Chargebee Error Messages article.
"NFND-1029 - Duplicate transaction found!": iPaaS.com allows each transaction number once in a company; for invoices, a number another transaction in the company already holds (another system's, or one of this subscription whose link was cleared) is refused with this error, not linked, and retried. Validate in a staging environment how a credit note behaves if another source writes CN- numbers (see Collision Handling).
"VALD-1002 - Required field (Customer Id, Email address, or Company Id) is null or empty in your request.": most often the credit note's invoice was refused because it has no linked customer and no email, and the credit note stops with the same error even when it carries an email. It is retried. Give the Chargebee customer an email, then re-send the invoice and the credit note.
"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 archived before it reached iPaaS.com, see Archived and Deleted Item Prices in the Add/Update Chargebee Item Price TO iPaaS.com collection description.
VALD-1036: a refund'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 credit note.
VALD-1024: expected when a refund's Chargebee method has no row in the Payment Method translation. Add the row, then re-send the credit note. 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 CHGB-BIZL-1002, CHGB-BIZL-1006 or CHGB-BIZL-1007): the customer, an item price or the invoice the credit note needs could not be sent first. The credit note is retried; open that record's own error, fix it, and the credit note follows on the next retry.
CHGB-INTL-1002: iPaaS.com could not look up the credit note's linked customer or invoice. 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 credit notes. Remove or turn off that collection.
After changing a translation row, save the translation collection, then re-send the credit note. After changing a mapping, re-send the credit note.
Testing & Validation
Test Scenarios
Create a refundable credit note against an invoice that is not yet in iPaaS.com, and confirm that the invoice arrives first and that the credit note arrives as a Return whose parent is the invoice's transaction, with its lines.
Refund the credit note in money and confirm a refund record with the refunded amount and the status Completed.
Create an adjustment credit note and confirm Chargebee Credit Note Type reads adjustment; void it and confirm the Return becomes Cancelled.
Write off an invoice and confirm that the adjustment credit note arrives with the reason write_off under the written-off invoice.
Apply a credit note to a later invoice and confirm that the credit note's status updates to Refunded with no refund record, and that the later invoice's Chargebee Credits Applied shows the credit.
Confirm that an invoice and a credit note with the same number in Chargebee become two distinct transactions.
Run a Manual Sync with credit_note: plus the credit note id and confirm that the existing Return updates without a duplicate.
Credit 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.
If the Chargebee site applies tax, create a taxed credit note and confirm one tax record per tax and a matching TaxAmount.
Validation Checklist
The credit note scopes are Active in Inbound Data Flows, and a Webhook (Poll Request) event runs with the poll scope credit_note_poll.
The ad-hoc charge SKU is replaced in both the Credit Note Line and Invoice Line collections, and that product exists in iPaaS.com.
Every Payment Method translation row the site refunds through names an existing iPaaS.com payment method.
The four Chargebee Transaction custom fields exist in the iPaaS.com company.
Every invoiced Chargebee customer has an email.
The invoice collection is set up as well, so credit notes find their parent invoice.
Additional Notes
Out of Scope
Credit notes FROM iPaaS.com: credit notes are created and changed only in Chargebee. A FROM iPaaS.com transaction collection for credit notes fails with CHGB-BIZL-1005.
Initialization: there is no initialization for credit notes. History arrives through the first credit_note_poll run, which looks back Initial Poll Days, or one at a time through Manual Sync. To bring in a larger history, raise Initial Poll Days before the first poll, or use bulk sync using Postman.
Operational Notes
A credit note with no invoice in iPaaS.com: when a credit note credits no invoice, or its invoice is excluded by the invoice collection's filter, the Return arrives without a parent.
Changes in iPaaS.com are not written back: editing the Return in iPaaS.com does not change Chargebee, and the next transfer of the credit note replaces the edit.
Related Documents
Related Mapping Documentation