Menu

Mattering Automations Chargebee integration

Connect Chargebee to Mattering Automations: customers, the full subscription lifecycle, catalog items and item prices, invoices, credit notes, payment sources, hosted checkout pages, coupons, and the event stream as workflow steps, authenticated with one site-scoped API key.

The Mattering Automations Chargebee integration adds the Chargebee API v2 to your automation canvas, built on Product Catalog 2.0: manage customers, run the full subscription lifecycle (create, update, cancel, pause, resume, reactivate), maintain catalog items and their item prices, work invoices including void, delete, and collect payment, issue and refund credit notes, read transactions for reconciliation, manage stored payment sources, mint hosted checkout and payment-method pages plus customer portal sessions, poll the event stream, and manage coupons.

The credential is your Chargebee site name plus an API key. Chargebee authenticates with HTTP Basic auth, the API key as the username and an empty password, and the site name builds the API address itself, so the one credential selects the whole environment: every Chargebee account has a separate test site and live site, each with its own name, its own data, and its own API keys. That separation is the safety story of this integration, because the entire node surface, including every destructive node, runs on the test site with test money. This guide takes the test-site-first path and ends with the full node reference.

The safety modeling is stated on the nodes rather than buried, and in billing, destructive usually means money. Of the 48 nodes, 22 are safe reads, 14 are reversible writes, and 12 carry a destructive flag: Chargebee: Create Subscription, Chargebee: Update Subscription, Chargebee: Cancel Subscription, Chargebee: Reactivate Subscription, Chargebee: Collect Invoice Payment, Chargebee: Create Credit Note, Chargebee: Refund Credit Note, Chargebee: Void Invoice, Chargebee: Delete Invoice, Chargebee: Delete Customer, Chargebee: Delete Payment Source, and Chargebee: Delete Coupon. Some surfaces are deliberately absent: raw payment-source creation stays on Chargebee's hosted pages so card data never touches the canvas, legacy Product Catalog 1.0 is not covered, and webhook management lives in Chargebee's site settings rather than in this API surface.

Before you start

  • A Chargebee account. Every account includes a test site alongside the live site; the test site is a sandbox with its own API key and a test gateway, and it is the right place to build and run billing workflows first.
  • Your Chargebee site name: the first label of your site's domain, for example acme in acme.chargebee.com. The test site has its own name, for example acme-test, and its own keys.
  • An API key for the site you are connecting, created in the Chargebee admin console under Settings, then Configure Chargebee, then the API keys section. The key type decides how much of the integration works: a full-access key of the All type covers every node, while a Read-only: All key covers the 22 query nodes only.
  • A site on Product Catalog 2.0. The item, item price, subscription, and coupon nodes use Chargebee's item-based operations; sites still running the legacy Product Catalog 1.0 model (plans and addons) are not covered by this integration.
  • A Mattering workspace with access to the Automations app.

Get your Chargebee site name and API key

Chargebee authenticates API requests with HTTP Basic auth: the API key is the username and the password is left empty. The site name is the other half of the credential because it builds the API address, {site}.chargebee.com, and test and live are entirely separate sites with separate keys and separate data, so the site name you enter decides which environment your workflows touch. Start with the test site; swap to a live-site credential when the workflow is proven.

Sign in to Chargebee. To work against the test site, click your account name and choose Go to TEST site. Everything created there, customers, subscriptions, invoices, stays on the test site and bills test money through the test gateway.
Open Settings, then Configure Chargebee, then the API keys section. Chargebee's own documentation labels this entry API Keys and Events in its step list and API Keys and Webhooks in its overview, with the keys themselves on an API Keys tab, so expect either label depending on your site.
Click + Add API Key and choose the key type, which decides how much of this integration works. A full-access key of the All type can call every node, including the deletes; its Write key and Update key variants withhold delete or create rights respectively. On the read side, a Read-only: All key covers the 22 query nodes, while a Read-only: Restricted key covers only the data groups you select, transactional or Product Catalog or both, so a restricted key can fail on query nodes outside its selection. The 26 action nodes need write permission in every case.
Copy the key.
Test keys and live keys belong to different sites and are not interchangeable: a live key sent to the test site name, or the reverse, fails with a 401 no matter how correct the key is. When a credential that worked yesterday starts failing, check which site it names before rotating anything.
Note the site name. It is the first label of your Chargebee domain, for example acme for acme.chargebee.com, and the test site is its own name such as acme-test.
You can paste the full domain or even a URL into the site field; Mattering reduces it to the bare site name. What matters is that it names the same site the API key came from.

Connect Chargebee to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Chargebee from the list.
Click Create new credential, enter the site name, paste the API key, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection. Mattering asks the site for one customer over the API: success proves both the site name and the key together. A 401 with Chargebee's structured error body means the key is wrong for that site; a connection failure or 404 means the site name itself is wrong.
Click Connect. All 48 Chargebee nodes appear in your canvas palette.

Verify it works

After connecting, open any automation canvas and check the palette: a Chargebee section should list the query and action nodes. Drop Chargebee: List Customers onto the canvas and run a test step. It is the integration's health check: it needs no parameters and works for any key carrying transactional read access, and a fresh test site simply returns an empty list, which is a success, not a failure. If this node runs, the credential is healthy; anything failing after it is a permissions or parameters question, not an authentication one.

Next, run Chargebee: List Items and Chargebee: List Item Prices to see the catalog, because item price ids are what subscriptions actually bill on, and most lifecycle workflows start from one. Two shapes worth learning on this first read: list rows arrive wrapped per entity, so a customer's id lives at data.list[].customer.id rather than data.list[].id, and money amounts are integers in the currency's minor unit, cents for USD. Everything in this verify path is read-only; it cannot reach the twelve destructive nodes or bill anything, though the habit worth keeping is doing write experiments on the test site anyway.

Node reference

48 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 22

Chargebee: Get Coupon

chargebee_get_coupon

Fetch one coupon: discount, duration, applicability, validity, and how many times it has been redeemed.

Chargebee: Get Credit Note

chargebee_get_credit_note

Fetch one credit note: type, status, the invoice it credits, and how much is allocated, refunded, and still available.

Chargebee: Get Customer

chargebee_get_customer

Fetch one customer: contact details, billing address, auto collection setting, and credit balances (promotional, refundable, excess payments).

Chargebee: Get Event

chargebee_get_event

Fetch one event with its full content object (the affected customer, subscription, invoice, or other resources as of the event).

Chargebee: Get Hosted Page

chargebee_get_hosted_page

Fetch one hosted page: its state (a succeeded state means the customer completed it) and, once succeeded, the resulting subscription or customer content.

Chargebee: Get Invoice

chargebee_get_invoice

Fetch one invoice: status, line items, linked payments, applied credits, and the amounts due, paid, and adjusted.

Chargebee: Get Item

chargebee_get_item

Fetch one catalog item: type, family, applicability, and checkout/portal visibility.

Chargebee: Get Item Price

chargebee_get_item_price

Fetch one item price: pricing model, amount, currency, period, and trial settings.

Chargebee: Get Payment Source

chargebee_get_payment_source

Fetch one payment source: type, status, gateway, and masked instrument details (never the full number).

Chargebee: Get Subscription

chargebee_get_subscription

Fetch one subscription: status, current term window, next billing time, and the subscription_items it is billed on.

Chargebee: Get Transaction

chargebee_get_transaction

Fetch one transaction: type, status, amount, gateway reference, error details on failures, and the invoices or refunds it is linked to.

Chargebee: List Coupons

chargebee_list_coupons

List coupons with filters on name, discount type, duration type, and status. Rows arrive at data.list[].coupon with redemption counts.

Chargebee: List Credit Notes

chargebee_list_credit_notes

List credit notes with filters on customer, subscription, the invoice they credit, type (adjustment or refundable), and status. Rows arrive at data.list[].credit_note with allocated, refunded, and available amounts.

Chargebee: List Customers

chargebee_list_customers

List customers with filters on email, name, and created or updated time. Needs no parameters and works for every API key (a fresh site returns an empty list), so this is the credential health check to run first in any Chargebee automation. Rows arrive wrapped per entity at data.list[].customer; pass data.next_offset back as offset for the next page.

Chargebee: List Events

chargebee_list_events

List events (the same stream webhooks deliver): subscription_created, invoice_generated, payment_succeeded, and the rest, filtered by type, source, and occurrence time. Each row's content object carries the affected resources; poll this to drive automations without a webhook endpoint.

Chargebee: List Hosted Pages

chargebee_list_hosted_pages

List hosted pages with filters on type (checkout_new, checkout_existing, manage_payment_sources, and others) and state (created, requested, succeeded, cancelled, acknowledged). Rows arrive at data.list[].hosted_page.

Chargebee: List Invoices

chargebee_list_invoices

List invoices with filters on customer, subscription, status, and invoice or updated date. Rows arrive at data.list[].invoice with line items, payments, and amounts in the currency's minor unit.

Chargebee: List Item Prices

chargebee_list_item_prices

List item prices (the sellable price points of items: currency, period, and pricing model). Rows arrive at data.list[].item_price; filter by item_id to see one item's price points.

Chargebee: List Items

chargebee_list_items

List catalog items (Product Catalog 2.0: plans, addons, and charges are all items). Rows arrive at data.list[].item.

Chargebee: List Payment Sources

chargebee_list_payment_sources

List stored payment sources with filters on customer, type (card, paypal_express_checkout, direct_debit, and others), and status (valid, expiring, expired, invalid, pending_verification). Rows arrive at data.list[].payment_source; card entries carry masked details only.

Chargebee: List Subscriptions

chargebee_list_subscriptions

List subscriptions with filters on customer, status, item price, and created or updated time. Rows arrive at data.list[].subscription with subscription_items showing each item price on the subscription.

Chargebee: List Transactions

chargebee_list_transactions

List payment transactions with filters on customer, subscription, payment source, type (authorization, payment, refund, payment_reversal), status, gateway, and date. Rows arrive at data.list[].transaction with linked invoices and refunds for reconciliation.

Action nodes 26

Chargebee: Cancel Subscription

chargebee_cancel_subscription_for_items

DESTRUCTIVE: cancel a subscription, immediately by default or at end of term. Immediate cancellation ends service now and can issue prorated credits or schedule refunds for the unused term per the options below. Chargebee CAN reactivate a cancelled subscription, but reactivation normally starts a fresh billing term and invoices immediately (the one documented exception is a subscription cancelled by dunning and reactivated inside its original term, which keeps that term and raises no invoice), so cancel plus reactivate is not a clean undo. Prefer Pause Subscription for a temporary stop.

Chargebee: Checkout Change Subscription Page

chargebee_checkout_existing_for_items

Create a hosted checkout page URL for changing an EXISTING subscription (upgrade, downgrade, quantity change). Nothing changes until the customer completes the page; the URL expires 3 hours after creation.

Chargebee: Checkout New Subscription Page

chargebee_checkout_new_for_items

Create a hosted checkout page URL for a NEW subscription on the given item prices. Nothing is billed by creating the page; the customer pays only if they complete checkout. Per the vendor docs the URL expires 3 hours after creation. Send data.hosted_page.url to the customer.

Chargebee: Collect Invoice Payment

chargebee_collect_invoice_payment

DESTRUCTIVE (moves real money): charge the customer's payment source for an invoice in payment_due, posted, or not_paid status. Per the vendor docs it collects the invoice's full amount_to_collect unless a smaller amount is given, and returns the updated invoice plus the payment transaction.

Chargebee: Create Coupon

chargebee_create_coupon_for_items

Create a coupon for Product Catalog 2.0 items: a fixed amount or percentage deduction applied to the invoice or to specific item prices. Item constraints (which items the coupon covers) go through extra_body per the documented item_constraints shape.

Chargebee: Create Credit Note

chargebee_create_credit_note

DESTRUCTIVE (creates money owed): issue a credit note against an invoice. Type refundable creates real money owed back to the customer (retained as credits, applied to unpaid invoices, or refunded); type adjustment reduces an unpaid invoice. Classed destructive per the refund precedent because a refundable credit is a liability on the books the moment it exists.

Chargebee: Create Customer

chargebee_create_customer

Create a customer record. Nothing is billed by creating a customer; subscriptions and invoices are separate steps. Chargebee generates the id when you leave it blank.

Chargebee: Create Item

chargebee_create_item

Create a catalog item (a plan, addon, or charge in Product Catalog 2.0). Items carry no price; create item prices for each currency and period afterwards.

Chargebee: Create Item Price

chargebee_create_item_price

Create a price point for an item: one currency, period, and pricing model combination, for example silver-USD-monthly. period and period_unit are required for plan and addon items.

Chargebee: Create Portal Session

chargebee_create_portal_session

Create a customer portal session and its pre authenticated access_url, so a customer manages their own subscriptions, payment methods, and invoices. Per the vendor docs the access_url must be used within one hour and works once; mint a fresh session per visit.

Chargebee: Create Subscription

chargebee_create_subscription_for_items

DESTRUCTIVE (moves real money): create a subscription for an existing customer on the given item prices. With auto collection on and a stored payment source, Chargebee generates the first invoice and charges it immediately at creation; use start_date or trial_end for a subscription that must not bill now. The response carries the subscription, the customer, and the first invoice when one was generated.

Chargebee: Delete Coupon

chargebee_delete_coupon

DESTRUCTIVE: permanently delete a coupon. The code stops being redeemable and there is no undelete; archive via the Chargebee UI is the reversible alternative when the code might return.

Chargebee: Delete Customer

chargebee_delete_customer

DESTRUCTIVE: permanently delete a customer. The customer is marked deleted and their subscriptions, unpaid invoices, and stored payment methods go with them per site settings; there is no undelete. Optionally also deletes the payment method at the gateway.

Chargebee: Delete Invoice

chargebee_delete_invoice

DESTRUCTIVE: permanently delete an invoice. The vendor's preconditions are effectively those of Void Invoice (no successful or in-progress linked payments, amount_adjusted zero, no refunded or refund_due credit notes, no withheld taxes) plus a bar on gift subscriptions, so the real difference from voiding is what survives the call, not which invoices are accepted. The vendor's own docs recommend voiding instead because voiding preserves the audit trail; a deleted invoice is only reachable again via List Invoices with include_deleted.

Chargebee: Delete Payment Source

chargebee_delete_payment_source

DESTRUCTIVE: permanently delete a stored payment source, including the copy at the payment gateway where the gateway supports deletion. A customer whose only payment source is deleted cannot be auto-collected until a new one is added; there is no undo.

Chargebee: Manage Payment Sources Page

chargebee_manage_payment_sources_page

Create a hosted page URL where a customer adds or updates their payment methods without card data ever touching your systems. Per the vendor docs this page type's URL stays valid for 5 days.

Chargebee: Pause Subscription

chargebee_pause_subscription

Pause an active subscription so billing stops until it is resumed. Resume Subscription is the documented inverse, which is what makes this the reversible alternative to cancelling.

Chargebee: Reactivate Subscription

chargebee_reactivate_subscription

DESTRUCTIVE (moves real money): reactivate a CANCELLED subscription. Per the vendor docs the subscription returns to active or in_trial, a new billing term starts, and charges raised at execution are invoiced (and collected when auto collection is on) unless invoice_immediately is false or trial_end puts it back in trial. One documented exception: a subscription cancelled by dunning and reactivated inside its original billing term keeps that term and generates no new invoice. Only cancelled subscriptions can be reactivated.

Chargebee: Refund Credit Note

chargebee_refund_credit_note

DESTRUCTIVE (moves real money): refund a refundable credit note's available amount to the customer through the original payment method. Money leaves the account and there is no API undo; the response carries the updated credit note and the refund transaction.

Chargebee: Resume Subscription

chargebee_resume_subscription

Resume a paused subscription, immediately or at a specific date; the pause pair's documented inverse. Note that normal billing restarts on resumption, and charges pending from the pause can be invoiced immediately per charges_handling.

Chargebee: Update Coupon

chargebee_update_coupon_for_items

Update a coupon's name, discount value, validity, or redemption cap. Only the fields you fill are changed; changes apply to future redemptions, not to subscriptions already carrying the coupon.

Chargebee: Update Customer

chargebee_update_customer

Update a customer's contact and collection settings. Only the fields you fill are changed. Billing address changes use Chargebee's separate update_billing_info endpoint (not built); switching auto_collection to on makes future invoices charge the stored payment method automatically.

Chargebee: Update Item

chargebee_update_item

Update a catalog item's names, description, applicability, or visibility. Only the fields you fill are changed; the item's type cannot be changed after creation.

Chargebee: Update Item Price

chargebee_update_item_price

Update an item price's names, amount, or trial. Per the vendor docs, once subscriptions or invoices exist for an item price its pricing_model, period, period_unit, currency_code, and billing_cycles become immutable; changing the price only affects future invoices.

Chargebee: Update Subscription

chargebee_update_subscription_for_items

DESTRUCTIVE (can move real money): change a subscription's item prices, quantities, or term. The subscription_items array REPLACES the complete list of items on the subscription, so pass every item that should remain, not just the changes. With proration on, upgrade charges can be invoiced and collected immediately against the stored payment method.

Chargebee: Void Invoice

chargebee_void_invoice

DESTRUCTIVE: void an invoice in payment_due, posted, or not_paid status. The vendor's preconditions are the same list Delete Invoice enforces: no successful or in-progress linked payments, amount_adjusted must be zero, no refunded or refund_due credit notes, and no withheld taxes. The status becomes voided permanently: no un-void exists, applied promotional credits return to the customer, and per the vendor docs Chargebee will not issue prorated credits later for the term the voided invoice covered. Voiding preserves the record for audit; prefer it over Delete Invoice.

Using the integration

On the automation canvas

Chargebee nodes chain with every other node: a scheduled run can poll Chargebee: List Events for payment failures and open a task in Mattering Productivity with the invoice from Chargebee: Get Invoice attached, a form submission can flow through Chargebee: Create Customer into a checkout link, and a nightly sweep can write Chargebee: List Subscriptions and Chargebee: List Invoices results into a Mattering database for reporting. Pagination is uniform: pass a response's next_offset back as offset for the next page, with limit up to 100 rows per call.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter can drive the same surface. The 22 query nodes are the safest thing to hand an agent: Chargebee: List Subscriptions with status filters, Chargebee: List Invoices for what is due, Chargebee: List Transactions for reconciliation, and Chargebee: List Payment Sources for cards going expiring or expired. Keep the twelve destructive nodes behind conditions or approval steps; in this connector, destructive is not a figure of speech, most of them can move real money.

The subscription lifecycle, honestly labeled

Chargebee: Create Subscription creates server-side against a stored payment source: with auto collection on, Chargebee generates the first invoice and charges it at creation, and start_date or trial_end are the documented ways to create one that must not bill now. Chargebee: Update Subscription carries two warnings on the node itself: the subscription_items array replaces the complete item list, so pass every item that should remain, and prorated upgrade charges can be invoiced and collected immediately. Chargebee: Pause Subscription and Chargebee: Resume Subscription are the documented reversible pair for a temporary stop. Chargebee: Cancel Subscription can cancel immediately or at end of term, and immediate cancellation can issue prorated credits or schedule refunds; Chargebee: Reactivate Subscription exists for cancelled subscriptions but generates an invoice for a new term, so cancel plus reactivate is not a clean undo. The single documented exception is narrow: a subscription cancelled by dunning and reactivated inside its original billing term keeps that term and generates no new invoice.

Money movement is explicit

Chargebee: Collect Invoice Payment charges the customer's payment source for an invoice in payment_due, posted, or not_paid status, collecting the invoice's full collectible amount unless a smaller amount is given. Chargebee: Create Credit Note issues a credit against an invoice, and the type matters: adjustment reduces an unpaid invoice, while refundable creates real money owed back to the customer the moment it exists. Chargebee: Refund Credit Note then sends the available amount back through the original payment method, with no API undo. All three carry the destructive flag, which makes the right workflow shape natural: the request lands as an approval task, and the money moves only after a person confirms.

Hosted pages keep card data off the canvas

Chargebee: Checkout New Subscription Page and Chargebee: Checkout Change Subscription Page mint hosted checkout URLs for new subscriptions and for changes to existing ones; nothing is billed by minting the page, the customer pays only if they complete it, and per the vendor docs checkout URLs expire 3 hours after creation, so mint at send time. Chargebee: Manage Payment Sources Page gives a customer a page to add or update payment methods, valid for 5 days, and Chargebee: Create Portal Session mints a portal access URL that must be used within one hour and works once, so create a fresh session per visit. Chargebee: Get Hosted Page closes the loop: a succeeded state means the customer completed the page and carries the resulting subscription or customer. This is also why the integration deliberately ships no raw card or bank-account nodes; the hosted pages are the PCI-clean path.

Void before delete, and events as the change stream

For a wrongly generated invoice, Chargebee: Void Invoice is the vendor-recommended call: it works on invoices in payment_due, posted, or not_paid status, the voided status is permanent with no un-void, applied promotional credits return to the customer, and the record survives for audit. Chargebee: Delete Invoice removes the invoice permanently under a near-identical precondition list and is the one to avoid unless you truly need the record gone. For driving automations, Chargebee: List Events reads the same stream webhooks deliver, subscription and invoice and payment events with the affected resources embedded in each event's content, filtered by type and occurrence time, so a schedule plus an occurred-after filter gives you webhook-like behavior without hosting an endpoint.

Troubleshooting

Test Connection fails with a 401
The key and the site do not match. Chargebee API keys are per-site, and test and live are separate sites, so the most common cause is a live key entered with the test site name or the reverse; check which site the credential names and which site the key came from. Also check for whitespace picked up in the copy, and confirm the key was not deleted in the Chargebee admin console. A read-only key with transactional read access passes this test, since the probe is a read; if the 401 appears later on action nodes instead, see the next entry.
Test Connection passes but action nodes are refused
The credential likely holds a read-only API key. The connection test reads one customer, which a read-only key can do, but the 26 action nodes need a key with write permission. Create a full-access key under Settings, then Configure Chargebee, then the API keys section on the same site, and update the credential. Note that the narrower full-access variants are not equivalent: an Update key cannot create records and a Write key cannot delete them, so the deletes need the All type. If only some action calls fail with Chargebee's error body while others work, read the message field: Chargebee's errors carry an api_error_code and a human-readable message that usually names the offending parameter or state.
Test Connection fails without ever reaching Chargebee
A connection failure or 404 means the site name is wrong, because the site name builds the API address itself. Use the bare site name, for example acme rather than a full URL, though pasted domains are reduced automatically, and remember the test site is its own name, typically ending in -test. If workflows run but the data never shows up where you look, this is the same confusion in a different coat: the workflow wrote to one site while you were reading the other, because test and live data are fully separate.
Item, item price, or subscription nodes fail on an older Chargebee site
This integration is built on Product Catalog 2.0, where plans, addons, and charges are items with item prices, and the subscription and coupon operations use the item-based endpoints. A site still running the legacy Product Catalog 1.0 model refuses those operations. Check which catalog version the site uses in the Chargebee admin console; Chargebee documents the migration path from 1.0 to 2.0. The customer, transaction, and payment source nodes are unaffected, because Chargebee's upgrade guide does not list those endpoints as changing between catalog versions. Invoices are a different case: they do change across versions, and a Product Catalog 1.0 site returns invoice responses in the legacy format by default, so invoice field paths can differ from what the node documentation describes.
An update removed items from a subscription
That is the documented replace semantics of the update operation, not data loss from the integration: the subscription_items array on Chargebee: Update Subscription replaces the complete list of items on the subscription, so a call passing only the changed item silently drops every other item. Always pass the full set that should remain. The recovery is the same node: read the subscription's previous items from Chargebee: Get Subscription output captured in the run history, and update again with the complete list.
Chargebee: Void Invoice or Chargebee: Delete Invoice is refused
Both have strict preconditions, and they are almost the same ones. Void requires the invoice to be in payment_due, posted, or not_paid status, with no linked payments in success or in_progress state, amount_adjusted at zero, no applied or issued credit notes in refunded or refund_due state, and no withheld taxes; a paid invoice therefore cannot be voided, and the path for money already collected is a credit note. Delete adds only that the invoice must not belong to a gift subscription. So the choice between them is not about which one a given invoice will accept, it is about what you want to survive: when the goal is correcting a wrongly generated invoice, void is the vendor-recommended operation because it preserves the audit record, while deletion leaves the invoice reachable only through List Invoices with include_deleted.
Chargebee: Collect Invoice Payment fails or the charge does not go through
First check the invoice status: collection works on invoices in payment_due, posted, or not_paid status, so an invoice that is already paid or voided is refused outright. Then check the customer's payment sources with Chargebee: List Payment Sources; a customer whose stored sources are expired or invalid has nothing to charge. When the gateway declines, the response carries a transaction with error details, and Chargebee: Get Transaction retrieves them for the follow-up. On the test site, declines can be simulated deliberately through the test gateway, which is the right place to build the failure branch of a dunning workflow.
A checkout or portal link does not work when the customer opens it
Hosted page URLs are short-lived by design, with different clocks per type: checkout page URLs expire 3 hours after creation, the manage payment sources page stays valid for 5 days, and a portal session's access URL must be used within one hour and works exactly once. A link minted at workflow build time and sent hours later, or a portal link reused for a second visit, fails for that reason alone. Mint the URL in the same workflow run that sends it, and mint a fresh portal session per visit. Chargebee: Get Hosted Page shows a page's current state if you are unsure whether the customer completed it.
A lister returns rows but downstream steps read empty values
Chargebee wraps every list row in its entity name: customers arrive at data.list[].customer, subscriptions at data.list[].subscription, invoices at data.list[].invoice, and so on, so a path like data.list[].id reads nothing while data.list[].customer.id reads the id. Single-object responses are wrapped the same way, and write responses can carry sibling objects, for example a created subscription arriving with its customer and first invoice side by side. Two more shapes to expect: amounts are integers in the currency's minor unit, and timestamps are UNIX epoch seconds.
Nodes start returning 429 during a large sweep
Chargebee's API documents HTTP 429 for excessive requests with the guidance to retry after a delay, and the nodes report the 429 on their output rather than silently retrying. Reduce the requests first: list with limit 100 and page with next_offset instead of re-listing, use the listers' filters (status, customer, created and updated time) rather than fetching everything and filtering on the canvas, and spread scheduled sweeps apart. A wait step between pages is the blunt fix when a sweep genuinely needs the volume.

Chargebee is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products