Chargebee users sign in to the Chargebee app at:

Each Chargebee site also has its own address, made from the site name: https://[site].chargebee.com. For example, a site whose address is acme-test.chargebee.com has the site name acme-test. Chargebee gives test sites and live sites separate names and separate API keys, so a test site and a live site are two different sites to the integration.

The Chargebee integration uses the Chargebee API v2, a REST API that accepts form-encoded requests, answers in JSON, and authenticates with an API key. The integration is built for sites that use Product Catalog 2.0 (items and item prices). Chargebee's Product Catalog 1.0 API reference has no item price endpoints, so subscribers or their MiSP should confirm the site's catalog with Chargebee support before subscribing, and validate the connection in a staging environment before relying on it in production.

Base URL:

The [Chargebee Site] value is the Chargebee Site subscription setting. It accepts the bare site name (for example acme-test) or the full site address; both point the integration to the same site. There is no separate sandbox address: a test site uses the same base URL pattern with its own site name.

All calls go to the one site named in the setting. The subscription remembers the Chargebee site it first exchanged data with, and refuses a later, different site with CHGB-BIZL-1008, because each Chargebee site keeps its own numbering and another site's records could overwrite the ones already sent TO iPaaS.com.

Every endpoint below is shown with [Base URL] in place of the base URL above.

Table of Contents

Reads one item price. The integration makes this call each time it connects to Chargebee, which is at the start of every transfer, to prove that the API key works on the site and that the site answers item price requests. When Chargebee refuses this read as incompatible with the site's configuration, the integration treats the site as not using Product Catalog 2.0 and stops with CHGB-BIZL-1009.

Retrieves a single item price by its Chargebee item price id. Used during TO iPaaS.com product transfers (webhook, poll and Manual Sync) and when an invoice or credit note line needs its item price in iPaaS.com first. A deleted item price is no longer returned by Chargebee, so nothing is sent for it; an archived item price is sent only when it is already linked in iPaaS.com.

Retrieves the item prices changed since the last poll, oldest change first. Used by the scheduled item_price_poll event. See Pagination for how a poll pages through the results.

Query parameters:

Retrieves the item an item price belongs to (its type, name and description). Used during TO iPaaS.com product transfers, right after the item price is read.

Retrieves a single customer, with its billing address, by its Chargebee customer id. Used during TO iPaaS.com customer transfers, when an invoice or credit note needs its customer in iPaaS.com first, to read the customer's email for an invoice or credit note that has none, and before every FROM iPaaS.com update.

Chargebee no longer returns a deleted customer by id, so when that read finds nothing the integration asks the customer list for the same id with deleted customers included. Used during TO iPaaS.com customer transfers for the customer_deleted webhook and Manual Sync. A deleted customer is sent only when it is already linked in iPaaS.com, and it never deletes the iPaaS.com customer.

Query parameters:

Finds the Chargebee customers that already have the email of an iPaaS.com customer about to be created. Used during FROM iPaaS.com customer creates, for duplicate handling. Chargebee's list endpoints can take a short time to show a recent change, so the integration also reads the most recently created customers, which can find a customer created moments earlier, though not always (see Chargebee Integration Known Limitations).

Query parameters:

Retrieves the customers changed since the last poll, oldest change first. Used by the scheduled customer_poll event. See Pagination for how a poll pages through the results.

Query parameters:

Creates a Chargebee customer, with its billing address. Used during FROM iPaaS.com transfers when no Chargebee customer was matched by email, or the iPaaS.com customer has no email. A create is not protected against being repeated: if Chargebee creates the customer but iPaaS.com does not save the link to it (for example, the transfer fails after the create, or the link is removed), the next attempt treats the iPaaS.com customer as new and can create a second Chargebee customer (see Chargebee Integration Known Limitations for what to check). The request also stores a small iPaaS.com sync marker in the customer's meta_data, which the integration uses to recognise edits made in Chargebee.

Updates an existing Chargebee customer by its id. Used during FROM iPaaS.com transfers when the customer is already linked. Only the fields whose values changed are sent, together with the updated sync marker in meta_data (other meta_data keys are kept); when nothing changed, no update is sent. An update that would overwrite an edit made in Chargebee is stopped with CHGB-BIZL-1003 before this call.

Updates the billing address of an existing Chargebee customer. Used during FROM iPaaS.com updates, before the customer update, only when the billing address changed. The address sent combines the iPaaS.com values with the address fields Chargebee already holds, so fields the transfer does not carry are kept.

Retrieves the subscriptions of a customer, to work out the customer's billing status. Used during each TO iPaaS.com transfer of a customer that is not deleted, including the subscription webhooks, which refresh the customer.

Query parameters:

Reads the first page of the site's subscription list, in Chargebee's default order, and adds any subscriptions on it that belong to the customer to those found by the filtered list above. Used during the same customer transfers.

Retrieves each subscription found above by its id (up to 25 per customer), because a read by id always shows the subscription's current state while a list can lag a recent change. Used during the same customer transfers; a subscription that is no longer found is left out of the billing status.

Retrieves a single invoice, with its lines, taxes, discounts, addresses and linked payments, by its Chargebee invoice id. Used during TO iPaaS.com transaction transfers (webhook, poll and Manual Sync). A pending (draft) invoice is not sent; Chargebee issues it as a new invoice when it is closed.

When the read by id finds nothing, the integration asks the invoice list for the same id with deleted invoices included. Used for the invoice_deleted webhook and Manual Sync. A deleted invoice is sent as deleted only when it is already linked in iPaaS.com.

Retrieves the invoices changed since the last poll, oldest change first. Used by the scheduled invoice_poll event. See Pagination for how a poll pages through the results.

Query parameters:

NOTE: The scheduled Webhook (Poll Request) event for invoice_poll needs an Event Rule named Filter with the Expression invoice. Without that rule, the invoice poll reads both invoices and credit notes, so with both transaction poll events scheduled every document is sent twice.

Retrieves a single credit note, with its lines, taxes, discounts, addresses and linked refunds, by its Chargebee credit note id. Used during TO iPaaS.com transaction transfers (webhook, poll and Manual Sync).

When the read by id finds nothing, the integration asks the credit note list for the same id with deleted credit notes included. Used for the credit_note_deleted webhook and Manual Sync. A deleted credit note is sent as deleted only when it is already linked in iPaaS.com.

Retrieves the credit notes changed since the last poll. Used by the scheduled credit_note_poll event. Chargebee sorts the credit note list only by document date, not by update time, so this request has no sort, and each credit note poll reads every page of changed credit notes in one run.

Query parameters:

NOTE: The scheduled Webhook (Poll Request) event for credit_note_poll needs an Event Rule named Filter with the Expression credit_note. Without that rule, the credit note poll reads both invoices and credit notes, so with both transaction poll events scheduled every document is sent twice.

Retrieves the Chargebee transactions linked to an invoice (its payments) or to a credit note (its refunds), by their ids. Used during TO iPaaS.com invoice and credit note transfers, only when the document has linked payments or refunds.

Query parameters:

The integration registers one Chargebee webhook endpoint for each iPaaS.com subscription, named "iPaaS.com subscription" followed by the subscription number, and keeps its events in step with the webhook scopes set Active in the subscription's Inbound Data Flows section. These calls run only when a webhook scope is set Active or inactive. Chargebee allows up to five webhook endpoints per site; when all five are taken, setting a scope Active fails with CHGB-EXTN-1004. Other webhook endpoints on the site are never changed.

Lists the site's webhook endpoints to find this subscription's endpoint and count the endpoints in use.

Retrieves this subscription's webhook endpoint by its id, to read the events it currently has.

Creates this subscription's webhook endpoint when the first webhook scope is set Active. The endpoint carries its name, the iPaaS.com webhook address for this subscription, API version v2, and the events of the Active scopes.

Adds or removes events on this subscription's webhook endpoint when a webhook scope is set Active or inactive, and corrects its address if it has changed.

Removes this subscription's webhook endpoint when its last webhook scope is set inactive (Chargebee treats an endpoint with no events as subscribed to every event), and removes a duplicate endpoint of the same subscription if two were created at the same moment.

Chargebee uses HTTP Basic authentication: the API key is the username and the password is empty. There is no separate authorization endpoint and no token exchange; the key is sent on every request.

The <API Key> value is the API Key subscription setting. Chargebee API keys belong to one site, and a test site and a live site have different keys. The integration needs a Full-Access Key, created in Chargebee under Settings > Configure Chargebee > API Keys and Webhooks, on the API Keys tab. A wrong key is refused with CHGB-AUTH-1002. A read-only or restricted key is refused with CHGB-AUTZ-1001 wherever it lacks permission, including customer writes FROM iPaaS.com and webhook endpoint registration. See Chargebee Installation Instructions for how to create the key and enter it.

Chargebee's list endpoints return one page at a time. The limit parameter sets the page size, from 1 to 100 (Chargebee's default is 10). When more records are available, the response carries a next_offset value, and the next page is requested by passing that value as offset; a page with no next_offset is the last page. The integration always passes an explicit limit.

How the polls page through changes:

Chargebee applies its API limits to the requests made to a Chargebee site: a 429 response, Chargebee states, means "the API requests for your Chargebee site have exceeded acceptable limits". Every app and integration connected to the site, and every iPaaS.com subscription on it, sends its requests to that same site. At the time this documentation was written, Chargebee published these default limits:

Chargebee also limits how many requests a site can have in progress at the same time: 50 for GET requests and 100 for POST requests. Chargebee raises these limits on request through Chargebee Support.

Chargebee states: "If you receive an HTTP 429 Too Many Requests error response to an API call, it means that the API requests for your Chargebee site have exceeded acceptable limits", and that it "may also send a Retry-After header" (Chargebee API: Error handling). The integration then writes a warning in the transfer's activity log, and the transfer is held and retried after that wait (60 seconds when Chargebee gives none). Subscribers or their MiSP should validate this behaviour in a staging environment before relying on it in production.

What uses the limit:

The subscription's iPaaS.com throttle settings (API Throttle Limit, API Throttle Seconds, API Throttle Limit (To iPaaS), API Throttle Seconds (To iPaaS), Concurrent Connections and Concurrent Batch Executions) default to 500 calls per 60 seconds for each pair, 2 concurrent connections and 10 concurrent batch executions. Those defaults allow more calls than Chargebee's 150 calls per minute on a test site or a Starter plan. If transfers often wait for the limit, subscribers or their MiSP should check what else uses the Chargebee site's API, schedule the poll events no more often than needed, and consider lowering the throttle settings and Concurrent Connections (see Chargebee Connections and Settings). Concurrent Batch Executions is not used by this integration.