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.
Connect Chargebee to Mattering
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
Test Connection passes but action nodes are refused
Test Connection fails without ever reaching Chargebee
Item, item price, or subscription nodes fail on an older Chargebee site
An update removed items from a subscription
Chargebee: Void Invoice or Chargebee: Delete Invoice is refused
Chargebee: Collect Invoice Payment fails or the charge does not go through
A checkout or portal link does not work when the customer opens it
A lister returns rows but downstream steps read empty values
Nodes start returning 429 during a large sweep
Related
The Chargebee MCP
What connecting Chargebee unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
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.