Overview
The Chargebee integration provides three ready-made functions you can call when building mappings. They handle the lookups and conversions that invoices and credit notes need on their way TO iPaaS.com: finding the iPaaS.com customer linked to a Chargebee customer, finding the iPaaS.com transaction linked to a Chargebee invoice, and building a transaction number that is less likely to clash with the numbers of the other systems in your iPaaS.com company, so you don't have to write that logic yourself. The default invoice and credit note mapping collections already use all three.
Where you can use these functions
These functions are available anywhere you write a formula for the Chargebee integration:
Dynamic Formula mappings: where a destination field's value is produced by a formula rather than mapped directly from a source field.
Mapping collection filters: where a formula decides whether a record should be processed.
Error filters: a mapping collection's error filter, which sits alongside its collection filter. When the error filter's formula resolves to true, the transfer raises an error that is held in the Error Logs for review and, like other transfer errors, is retried automatically while it is active; dismiss it to stop the retry.
Translation collections: where a translation entry uses a formula as its source value.
How to use them
Call a function by name and pass the values it needs in parentheses, for example:
ChargebeeTransactionNumber(DocumentType, DocumentNumber).Each function's signature shows its name, the parameters it accepts (with their types), and the type of value it returns. Use it as the reference for exactly how to call the function.
Function names and formula syntax are case-sensitive, so type each name exactly as shown. Whether the values a function matches are treated as case-sensitive varies by function, and is called out in the relevant parameter's description.
These functions are synchronous, so you call them directly (no
awaitis required).Each function runs at sync time, against the data in your connected Chargebee site and your iPaaS.com subscription.
The functions are grouped below by the area of the integration they support.
Invoices and Credit Notes
Use these in the invoice and credit note mapping collections TO iPaaS.com. The integration sends a document's Chargebee customer, and for a credit note the invoice it credits, TO iPaaS.com before the document itself, so the links these functions read normally exist when the mapping runs.
ChargebeeCustomerIPaaSId
What it does: Returns the iPaaS.com customer ID that this subscription linked to a Chargebee customer. Use it to fill an invoice's or credit note's customer, so the transaction is attached to the customer this subscription brought in rather than to another iPaaS.com customer that happens to share the same email.
Signature: long? ChargebeeCustomerIPaaSId(string chargebeeCustomerId)
How to call it: ChargebeeCustomerIPaaSId(chargebeeCustomerId)
Parameter | Type | Required | Default | Description |
chargebeeCustomerId |
| Yes | N/A | The Chargebee customer ID of the invoice or credit note: map the document's CustomerId field. Pass the ID exactly as Chargebee holds it; leading and trailing spaces are ignored. |
Returns: long?. The iPaaS.com customer ID linked to that Chargebee customer by this subscription, or nothing (null) when the customer has no link or the ID is blank.
Example: For an invoice of Chargebee customer cust_ABC123, linked to iPaaS.com customer 4521, ChargebeeCustomerIPaaSId(CustomerId) returns 4521. The default Add/Update Chargebee Invoice TO iPaaS.com and Add/Update Chargebee Credit Note TO iPaaS.com collections fill the transaction's CustomerId with return ChargebeeCustomerIPaaSId(CustomerId);.
When to use it: When mapping the customer of an invoice or credit note TO iPaaS.com. A customer has no link when the customer mapping collection's filter left it out (the default filter skips a Chargebee customer with no email). The transaction is then saved without a customer if it still carries an email (the default mappings fill EmailAddress from the billing address email, else the customer's email). If it carries no email at all, iPaaS.com refuses the transaction, and the error stays in Dashboard / Integration Monitoring / Error Logs and is retried automatically while it is active. Subscribers or their MiSP should give every invoiced Chargebee customer an email before its invoices and credit notes are sent. If iPaaS.com cannot complete the lookup itself, the transfer stops with CHGB-INTL-1002 instead of saving the transaction without its customer, and the error appears in Dashboard / Integration Monitoring / Error Logs.
ChargebeeInvoiceIPaaSId
What it does: Returns the iPaaS.com transaction ID that this subscription linked to a Chargebee invoice. Use it to fill a credit note's parent, so the Return in iPaaS.com points at the invoice it credits.
Signature: long? ChargebeeInvoiceIPaaSId(string chargebeeInvoiceId)
How to call it: ChargebeeInvoiceIPaaSId(chargebeeInvoiceId)
Parameter | Type | Required | Default | Description |
chargebeeInvoiceId |
| Yes | N/A | The Chargebee invoice ID the credit note credits: map the credit note's ReferenceInvoiceId field. Pass the ID exactly as Chargebee holds it; leading and trailing spaces are ignored. |
Returns: long?. The iPaaS.com transaction ID linked to that Chargebee invoice by this subscription, or nothing (null) when the invoice has no link or the ID is blank.
Example: For a credit note against Chargebee invoice 1042, linked to iPaaS.com transaction 880, ChargebeeInvoiceIPaaSId(ReferenceInvoiceId) returns 880. The default Add/Update Chargebee Credit Note TO iPaaS.com collection fills the transaction's ParentId with return ChargebeeInvoiceIPaaSId(ReferenceInvoiceId);.
When to use it: When mapping the parent of a credit note TO iPaaS.com. A credit note that credits no invoice has a blank ReferenceInvoiceId, so the Return is saved without a parent. The same happens when the invoice has no link. If iPaaS.com cannot complete the lookup itself, the transfer stops with CHGB-INTL-1002 instead of saving the Return without its parent, and the error appears in Dashboard / Integration Monitoring / Error Logs.
ChargebeeTransactionNumber
What it does: Returns the transaction number for a Chargebee invoice or credit note. A number made only of digits gets INV- (invoice) or CN- (credit note) in front; a number with any other character in it, such as letters or a hyphen, is kept as it is.
Signature: string ChargebeeTransactionNumber(string documentType, string documentNumber)
How to call it: ChargebeeTransactionNumber(documentType, documentNumber)
Parameter | Type | Required | Default | Description |
documentType |
| Yes | N/A | The Chargebee document type, |
documentNumber |
| Yes | N/A | The Chargebee invoice or credit note number: map the document's DocumentNumber field. Leading and trailing spaces are removed. |
Returns: string. The transaction number to use in iPaaS.com. A blank number is returned unchanged.
Example: Invoice 1042 gives INV-1042, credit note 17 gives CN-17, and credit note SITE-CN-17 stays SITE-CN-17. The default Add/Update Chargebee Invoice TO iPaaS.com and Add/Update Chargebee Credit Note TO iPaaS.com collections fill the transaction's TransactionNumber with return ChargebeeTransactionNumber(DocumentType, DocumentNumber);.
When to use it: When mapping the transaction number of an invoice or credit note TO iPaaS.com. iPaaS.com allows each transaction number only once in a company, across all your systems, so a Chargebee number made only of digits could easily meet another system's order numbers, and the prefixes also keep invoices and credit notes with the same number apart. The prefix lowers the risk of a clash but cannot rule it out: if another system already holds the resulting number (for example INV-81), iPaaS.com refuses the document as a duplicate transaction, the error stays in Dashboard / Integration Monitoring / Error Logs, and the transfer is retried automatically while the error is active. The function makes no call to Chargebee or iPaaS.com.