A Recurly MCP for subscription billing, with the money-moving nodes marked
Connect one Recurly API key and 84 nodes land on the canvas: accounts and billing info, subscriptions and pending changes, plans and add-ons, invoices, line items, transactions, coupons and redemptions, credit payments, purchases and metered usage. Eighteen of them move money or cannot be undone, and every one is flagged, so an agent can read the whole billing picture while a person still approves the refund.
What the Recurly MCP connector does
The Recurly connector for Mattering Automations is 84 nodes on Recurly API v3, pinned to the 2021-02-25 release: 40 read nodes and 44 action nodes. Accounts, child accounts, balances and entitlements. Billing info, including verification and removal. Subscriptions with their whole lifecycle, pending changes and renewal previews. Plans and add-ons. Invoices with collection, refunds, voiding and credit application. Line items, transactions, coupons and redemptions, unique coupon codes, credit payments, purchases including authorize and capture, and metered usage records.
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and any MCP-capable assistant can use them, alongside Matter, the AI assistant built into the platform. That combination is unusually useful on a billing system, because most of what people ask a billing system is a read: an assistant handling a customer question can find the account with Recurly: List Accounts, read the current state with Recurly: Get Subscription, check the balance with Recurly: Get Account Balance and look at the last invoice with Recurly: Get Invoice, and answer completely without anyone opening the Recurly admin.
The reason this connector is comfortable to build against is Recurly's sandbox. Recurly offers a free, self-serve sandbox site with no payment method and no sales conversation, and it is not a reduced environment: a sandbox site can create plans, accounts, subscriptions and invoices. There is no separate sandbox host, because the credential selects the site, which means a workflow proven against a sandbox key runs identically against a production key. Recurly: List Sites reports the mode, sandbox, development or production, which makes a useful first step in any workflow that is about to charge someone. Note that Recurly documents a tighter rate limit on sandbox sites than on production ones, and counts all methods there rather than only reads, so a full rehearsal run needs pacing that production would not.
The safety modeling is the part worth reading twice, because Recurly's HTTP verbs say almost nothing about blast radius. Collecting an invoice is an ordinary update that charges a card right now. Terminating a subscription is a delete that can refund money. Previewing a purchase is a create that changes nothing. So nodes are classed by what they do rather than by their method: 18 are flagged destructive, including Recurly: Refund Invoice, Recurly: Collect Invoice, Recurly: Create Invoice, Recurly: Create Purchase, Recurly: Capture Purchase, Recurly: Create Subscription, Recurly: Create Subscription Change, Recurly: Cancel Subscription, Recurly: Terminate Subscription, Recurly: Convert Trial, Recurly: Void Invoice, Recurly: Mark Invoice Paid Successfully, Recurly: Mark Invoice Failed, Recurly: Apply Credit Balance to Invoice, Recurly: Deactivate Account, Recurly: Remove Billing Info, Recurly: Remove Plan and Recurly: Remove Plan Add-on. Creating a subscription is on that list deliberately: it bills against billing info the customer already authorized, so unless the plan carries a trial or the call sets manual collection or a future start, the first invoice is created and collected the moment the call succeeds.
One connection, three surfaces
- Visual automations. Drag Recurly nodes onto the canvas and wire them to triggers, conditions, and other apps.
- AI agents, yours or ours. These nodes speak MCP, the open protocol, so Claude, ChatGPT, and any MCP-capable assistant can use them, and Matter, the agent built into the platform, uses them natively.
- The whole platform. Combine with native tasks, projects, and other connectors, no middleware in between.
Every Recurly node, ready to drop on the canvas
84 nodes, generated from the connector itself so this list always matches what ships. Expand a category to browse.
Read and query nodes 40
Recurly: Get Account
Read one customer account: contact details, billing address, preferred locale and time zone, tax exemption, parent account and the has_live_subscription / has_past_due_invoice flags that tell a workflow whether this customer is currently paying and currently in trouble.
Recurly: Get Account Balance
Read an account's outstanding balance and available credit, broken down per currency, plus a past_due flag. Use it before a dunning or win-back workflow: past_due says the customer owes money, and available_credit_amount says how much of the next invoice can be paid from credit already on the account.
Recurly: Get Add-on
Read one add-on in full: pricing per currency, tier structure, default quantity, whether it is optional, and for usage add-ons the measured unit and usage calculation type.
Recurly: Get Billing Info
Read the payment method stored on an account: card type, last four digits, expiry, billing address, and a valid flag. Card numbers are never returned in full. The expiry fields are what a card-expiry outreach workflow reads; valid is what a pre-renewal health check reads.
Recurly: Get Coupon
Read one coupon in full: the discount (percent, fixed amount per currency, or free trial), how long it lasts, how many times it can be redeemed in total and per account, which plans and items it applies to, and its redeem-by date.
Recurly: Get Credit Payment
Read one credit payment: its action, amount, currency, the original credit invoice it came from, the invoice it was applied to, and any gateway refund transaction attached to it.
Recurly: Get Invoice
Read one invoice in full, including its line items, its transactions and any credit payments applied to it. refundable_amount is the number a refund workflow must respect, and balance is what the customer still owes. Watch has_more_line_items: on a large invoice the embedded line_items array is truncated and List Invoice Line Items is the complete source.
Recurly: Get Line Item
Read one line item: its description, currency, quantity, unit amount, discount, tax and total, plus the invoice, subscription, plan and add-on it belongs to and the service period it covers.
Recurly: Get Pending Subscription Change
Read the change already scheduled on a subscription: the new plan, quantity, unit amount and add-ons, and the activate_at timestamp when it takes effect. Recurly returns 404 when nothing is pending, which is the cheap way for a workflow to ask "is an upgrade already queued for this customer" before queueing another one.
Recurly: Get Plan
Read one plan in full: per-currency unit amounts and setup fees, billing interval, trial length and whether the trial requires billing info, total billing cycles, revenue schedule and hosted page URLs.
Recurly: Get Subscription
Read one subscription in full: plan, add-ons, quantity, unit amount, subtotal, tax and total, the current period and term boundaries, trial dates, pause state, and any pending change already scheduled at pending_change. Read this before any cancel, pause or change so the workflow knows what it is about to alter.
Recurly: Get Transaction
Read one transaction in full, including the gateway's response: status, status_code, gateway_message, customer_message, approval code, AVS and CVV check results, and the payment method used. customer_message is the string safe to show an end user; gateway_message is for the support team.
Recurly: List Account Coupon Redemptions
List every coupon redemption in an account's history, active and removed, with the discount each one delivered. This is the promotion history behind a lifetime-discount or margin analysis. Note this endpoint takes NO limit or order parameter, unlike the other listers here.
Recurly: List Account Credit Payments
List one customer's credit payments, newest first. Rows have the same shape as List Credit Payments. Pair it with Get Account Balance, which reports the CURRENT available credit, when a workflow needs both the number and how it got there.
Recurly: List Account Entitlements
List the privileges a customer currently holds through the plans and items they have purchased, each with the subscription that granted it. This is the endpoint an application calls to answer "is this customer allowed to use this feature" without reimplementing plan logic. Rows land at data.data[].
Recurly: List Account Invoices
List one customer's invoices, newest first. Rows have the same shape as List Invoices. This is the billing history a support or renewal workflow shows next to the account.
Recurly: List Account Subscriptions
List one customer's subscriptions, newest first. Rows have the same shape as List Subscriptions. Use state=live to see everything the customer still has access to, including cancelled subscriptions that have not yet expired.
Recurly: List Account Transactions
List one customer's payment transactions, newest first. Rows have the same shape as List Transactions. This is the payment history a support workflow shows when a customer says they were charged twice, or the evidence a dunning workflow reads before deciding whether to retry.
Recurly: List Accounts
List the site's customer accounts, newest first, with each account's code, email, billing address and a set of has_* flags summarising its subscription and dunning state. This is the source node behind every account picker in this connector. Filter by exact email, by whether the account has a live subscription, or by whether it has a past due invoice. Rows land at data.data[] and the next page path at data.next.
Recurly: List Active Coupon Redemptions
List the coupon redemptions currently DISCOUNTING an account, with the coupon behind each one and how much it has discounted so far. This is the read that answers "is this customer already on a promotion" before a workflow offers them another. Rows land at data.data[].
Recurly: List Add-ons
List every add-on across every plan on the site, each with its code, name, add_on_type (fixed or usage), per-currency pricing and owning plan_id. This is the source node behind the add-on pickers, including the usage nodes: usage can only be recorded against an add-on whose add_on_type is usage, and this is the only lister that shows that field across plans. Rows land at data.data[].
Recurly: List Child Accounts
List the accounts whose parent_account_id is this account, which is how Recurly models hierarchical billing (a parent company paying for its subsidiaries' subscriptions). Rows have the same shape as List Accounts.
Recurly: List Coupons
List the site's coupons with their codes, discounts, redemption limits, duration and state. This is the source node behind every coupon picker in this connector. The state field (redeemable, maxed_out, expired) is what a campaign workflow checks before offering a code, and coupon_type separates single codes from bulk coupons that generate unique codes. Rows land at data.data[].
Recurly: List Credit Payments
List the site's credit payments: the movements of customer credit, as opposed to gateway money. Each row's action says what happened - payment (credit spent on an invoice), refund (credit returned as cash), write_off or reduction - and links the invoice the credit came from to the invoice it was applied to. This is the source node behind the credit payment picker and the ledger a credit reconciliation reads. Note this endpoint takes no ids filter. Rows land at data.data[].
Recurly: List Invoice Line Items
List the line items on one invoice. This is the COMPLETE source: Get Invoice embeds a line_items array but truncates it on large invoices and says so through has_more_line_items, so anything that has to reconcile an invoice line by line should read it here. These ids are also what a line-item refund takes.
Recurly: List Invoices
List the site's invoices, newest first, each with its number, state, account, currency, subtotal, tax, total, paid and balance. This is the source node behind every invoice picker in this connector. Filter state=past_due for a dunning workflow, state=failed for recovery, or type=credit to see only credit invoices. Rows land at data.data[].
Recurly: List Line Items
List the site's line items: every individual charge and credit that makes up an invoice, with its description, quantity, unit amount, tax and the subscription, plan or add-on it came from. This is the source node behind the line item picker. state=pending shows charges that have not been invoiced yet, which is the set Create Invoice would post. Rows land at data.data[].
Recurly: List Plan Add-ons
List the add-ons belonging to one plan. Rows have the same shape as List Add-ons. This is the dependent source behind the add-on picker on Remove Plan Add-on, which is scoped to the plan already chosen on that form.
Recurly: List Plans
List the site's plans with their codes, names, per-currency pricing, billing interval, trial settings and state. This is the source node behind every plan picker in this connector and the catalog a signup or upgrade workflow reads before it offers anything. Rows land at data.data[].
Recurly: List Sites
List the Recurly sites this API key can reach, with each site's subdomain, mode and enabled features. An API key is scoped to one site, so this normally returns exactly one row, which is what makes it the cheapest authenticated read on the whole API and the Gate 1 auth probe: no path parameters, no required filters, and every credential can call it. The mode field (sandbox, development or production) is the reliable way to confirm a workflow is pointed at test data before it starts charging anyone. Rows land at data.data[].
Recurly: List Subscription Coupon Redemptions
List the coupon redemptions attached to one subscription, which is where subscription-level coupons live (as opposed to account-level ones). Rows have the same shape as the account listers. This endpoint also takes no limit or order parameter.
Recurly: List Subscription Invoices
List the invoices raised for one subscription, newest first: its signup invoice, every renewal, and any proration invoices produced by plan changes. Rows have the same shape as List Invoices. This is how a churn or expansion analysis reconstructs what one subscription actually billed over time.
Recurly: List Subscriptions
List the site's subscriptions, newest first, each with its account, plan, lifecycle state, current period and term dates, unit amount and total. This is the source node behind every subscription picker in this connector, and the current_term_ends_at field is what a renewal-reminder workflow keys off. Rows land at data.data[].
Recurly: List Transactions
List the site's payment transactions, newest first: what the gateway was asked to do and what it said. Each row carries the type (purchase, refund, authorization, capture or verify), the amount, the status, the gateway's decline message and codes, and the invoice and account it belongs to. This is the source node behind the transaction pickers and the raw material for a failed-payment recovery workflow: filter success=false to find declines. Rows land at data.data[].
Recurly: List Unique Coupon Codes
List the individual codes generated from a BULK coupon, each with its own state and redeemed_at timestamp. Filter redeemed=false to pull the next batch of unused codes to hand out, which is the read a partner or campaign distribution workflow lives on. Rows land at data.data[].
Recurly: List Usage Records
List the usage recorded against one usage-based add-on on one subscription, with each record's amount, merchant tag, usage timestamp and whether it has been billed yet. billing_status=unbilled (Recurly's default) is the set that will land on the next invoice, which is what a usage reconciliation compares against the merchant's own metering. Rows land at data.data[].
Recurly: Preview Invoice
Work out what invoicing the account's PENDING line items would produce - totals, tax and credits - without creating anything and without charging anyone. Nothing is posted and no money moves; it is a POST only because it needs a request body. Run it before Create Invoice so the workflow can check the number, or show it, before committing.
Recurly: Preview Purchase
Work out exactly what a checkout would cost - subscriptions, one-time charges, coupons, tax and total - WITHOUT creating anything and without charging anyone. Nothing is created and no money moves; it is a POST only because it needs a request body. This is the node an order-summary or quote workflow calls before Create Purchase. Set collection_method to manual to preview for an account that has no payment method stored yet.
Recurly: Preview Subscription Change
Work out exactly what an upgrade, downgrade or quantity change would cost, WITHOUT applying it. Nothing is created, nothing is scheduled and no money moves; it is a POST only because it needs a request body. The response carries the proration under invoice_collection, which is what an in-product upgrade screen or an approval workflow should show the customer before they commit.
Recurly: Preview Subscription Renewal
Preview the invoice that the subscription's NEXT renewal will produce, with its line items, discounts, tax and total, without creating anything. This is the read a renewal-notice or revenue-forecast workflow wants: it answers "what will this customer be charged next" exactly, including add-ons and coupons. The result comes back as an invoice collection at data.charge_invoice.
Action nodes 44
Recurly: Apply Credit Balance to Invoice
DESTRUCTIVE: this SPENDS the customer's money. It applies the account's available credit balance against an open invoice, consuming credit that the customer could otherwise have had refunded or spent on something else. Credit payments cannot be unapplied. Get Account Balance reports available_credit_amount, which is the ceiling on what this will consume.
Recurly: Authorize Purchase
Authorize a purchase without capturing it: the gateway holds the funds on the customer's card, but NOTHING is settled and the merchant receives no money until Capture Purchase runs. That separation is why this is a reversible write while Create Purchase is not - an authorization that is never captured expires on its own, typically within about a week depending on the gateway and card network. Use it to reserve funds while a fulfilment step runs. The transaction ID in the response is what Capture Purchase takes.
Recurly: Cancel Subscription
DESTRUCTIVE: this ends a paying customer relationship. The subscription moves to canceled and stops renewing. It is not generally undoable: Reactivate Subscription only works while the subscription is still inside its current term, so once the term ends the subscription expires and a new one must be created. No refund is issued and the customer keeps access until the period ends - for an immediate end, and for refunds, use Terminate Subscription instead.
Recurly: Capture Purchase
DESTRUCTIVE: this SETTLES the money. Capture takes a previous authorization and turns the hold on the customer's card into a real payment that lands in the merchant account. There is no un-capture, only a refund, which leaves a permanent credit invoice behind. The transaction_id must be an AUTHORIZATION transaction, which is why its picker is pinned to that type.
Recurly: Collect Invoice
DESTRUCTIVE: this CHARGES the customer. It runs a real payment attempt for an unpaid invoice against the account's stored payment method, right now, and a successful attempt cannot be undone - only refunded, which leaves a permanent credit invoice behind. This is the node a dunning recovery workflow calls, and it is exactly the node a blind endpoint matrix must never call. A decline comes back as an error with the gateway's own codes under error.transaction_error.
Recurly: Convert Trial
DESTRUCTIVE: this CHARGES the customer. Ending a free trial early converts the subscription to paid immediately, which raises and collects the first real invoice against the stored payment method. There is no un-convert; the trial cannot be given back. Use it when a customer explicitly asks to start paying, never as a bulk sweep over trialists.
Recurly: Create Account
Create a customer account. No money moves: an account is just the customer record that subscriptions, invoices and billing info hang off, which is why this is a reversible write while creating a subscription is not. The code is the merchant's own identifier, cannot be changed afterwards, and is what every other endpoint accepts in place of the opaque ID. Passing billing_info here stores a payment method at the same time, which does run a gateway verification.
Recurly: Create Coupon
Create a coupon. Catalog work only: nobody is charged or discounted until the coupon is actually redeemed on an account or a subscription. Set coupon_type to bulk with a unique_code_template to make a coupon that mints individual single-use codes, which Generate Unique Coupon Codes then produces.
Recurly: Create Invoice
DESTRUCTIVE: this can CHARGE the customer. It posts the account's pending line items as a real invoice, and with collection_method automatic (the default when the account has a payment method) Recurly collects it from the stored card immediately. An invoice cannot be un-posted; the only way back is Void Invoice or a refund, both of which leave a permanent record. Set collection_method to manual to bill without taking money. Run Preview Invoice first.
Recurly: Create Line Item
Add a one-time charge or credit to an account. It is created PENDING, which means it sits on the account until the next invoice picks it up: nothing is billed at call time and the line item can be deleted again with Remove Line Item, which is why this is a reversible write. Set type to credit to give the customer money back rather than charge them. Post it immediately with Create Invoice.
Recurly: Create Plan
Create a plan: a catalog entry saying how often and how much to charge. No customer is touched and no money moves, which is why this is a reversible write. Note that a plan with no subscriptions can be removed, but a plan that has ever been subscribed to can only be deactivated.
Recurly: Create Plan Add-on
Add an add-on to a plan: an extra charge billed alongside the plan's base price each period. Catalog work only, so nothing is charged and nobody's subscription changes - existing subscribers do not get the add-on until a subscription change puts it on them. Set add_on_type to usage to create a metered add-on that the usage nodes can record against.
Recurly: Create Purchase
DESTRUCTIVE: this CHARGES the customer. A purchase is a complete checkout - subscriptions plus one-time charges plus coupons - billed on ONE invoice and collected with ONE transaction against the stored payment method. It is the most direct way to take money through this connector, and the charge cannot be undone, only refunded. Run Preview Purchase first, and always send an idempotency key: a retried workflow run without one bills the customer twice. Set collection_method to manual to invoice without charging.
Recurly: Create Subscription
DESTRUCTIVE: this CHARGES the customer. A Recurly subscription bills against billing info the customer has already authorised, so unless the plan has a trial or you set collection_method to manual or a future starts_at, the first invoice is created and collected the moment this call succeeds. Nothing stands between the API call and a real payment, and cancelling later refunds nothing already taken. That is why this is classed destructive while creating an account or a plan is not. Returns the new subscription with its period dates and the id of the invoice it just raised.
Recurly: Create Subscription Change
DESTRUCTIVE: with the default timeframe of now, this prorates and INVOICES the difference immediately, collecting it from the stored payment method on an upgrade and issuing a credit on a downgrade. Either way real money moves and the previous plan, price and add-on set are gone. Scheduling the change for renewal or term_end instead defers all of that, but the node is classed destructive because its DEFAULT charges. Run Preview Subscription Change first and show the customer the number. Any change already pending is replaced by this one.
Recurly: Deactivate Account
DESTRUCTIVE. Deactivate a customer account, which also CANCELS the account's subscriptions. Reactivate Account puts the account itself back to active, but it does not bring the cancelled subscriptions back, so the paid relationship has to be rebuilt by hand. The vendor's redact query parameter, which permanently erases the customer's personal data to satisfy a GDPR or CCPA erasure request and cannot be undone, is deliberately NOT exposed on this node: that decision belongs to a human in the Recurly dashboard, not to an unattended workflow.
Recurly: Deactivate Coupon
Expire a coupon so it cannot be redeemed again. Redemptions already on customer accounts keep discounting as agreed, so no customer is charged more than they expected, and unlike plans and add-ons this IS undoable: Restore Coupon puts it back to redeemable. That combination is why this is a reversible write.
Recurly: Generate Unique Coupon Codes
Mint new single-use codes from a bulk coupon and get them back in the response, ready to hand out. Nothing is charged or discounted until someone redeems one, and codes that are never used cost nothing, which is why this is a reversible write. This is the SYNCHRONOUS variant, deliberately: the async endpoint returns a job to poll instead of the codes, which is useless inside a workflow step. Up to 200 codes per call.
Recurly: Mark Invoice Failed
DESTRUCTIVE. Mark a processing invoice as failed. Recurly then treats the payment as declined, which starts dunning and can cause the associated subscription to be cancelled by the site's dunning campaign. The state change is terminal and rewrites the accounting record of a real invoice, so use it only to reconcile a payment you KNOW did not clear.
Recurly: Mark Invoice Paid Successfully
DESTRUCTIVE. Record an offline payment: mark a manual invoice as paid in full without any money passing through the gateway. This is how a cheque or bank transfer is reconciled, and it CREDITS the customer's ledger for the full balance, so getting it wrong writes off real revenue. It also closes the invoice and stops dunning. There is no undo.
Recurly: Pause Subscription
Pause a subscription for a number of billing cycles: billing stops, the subscription stays alive, and it resumes automatically afterwards. This is the retention move a cancellation workflow should try first, and it is reversible at any time with Resume Subscription. The pause begins at the end of the current billing period, so nothing is refunded and nothing is charged right now.
Recurly: Reactivate Account
Put a deactivated account back into the active state so it can hold subscriptions and invoices again. This does NOT restore the subscriptions that deactivation cancelled and it charges nothing; recreate the subscription separately.
Recurly: Reactivate Subscription
Undo a cancellation: put a canceled subscription back to active so it renews normally at the end of the current period. It charges nothing now, because the customer has already paid for the period they are in. This only works while the subscription is still canceled - once it has EXPIRED the relationship is gone and Create Subscription is the only way back.
Recurly: Record Usage
Record metered usage against a usage-based add-on. Nothing is charged now: Recurly bills usage in arrears at the end of the billing period, and until then the record can be deleted with Remove Usage Record, which is why this is a reversible write. It is still the input that DECIDES what the customer pays, so always send a merchant_tag carrying your own record id and an idempotency key: a retried workflow run without them silently doubles the customer's bill.
Recurly: Redeem Coupon on Account
Apply a coupon to a customer. Nothing is charged, credited or invoiced at call time: the discount lands on the NEXT invoice the account or subscription generates, and it can be taken off again with Remove Coupon Redemption before that happens, which is why this is a reversible write. It does consume one of the coupon's redemptions against its max_redemptions cap.
Recurly: Refund Invoice
DESTRUCTIVE: MONEY LEAVES the merchant account and there is no un-refund. Refund a whole invoice, a fixed amount, a percentage, or specific line items. The refund_method decides whether the customer gets cash back through the gateway or account credit: all_credit issues credit only, all_transaction returns money to the card, and the credit_first / transaction_first pair use credit or the gateway first and fall back to the other. Recurly caps the total at the invoice's refundable_amount, which Get Invoice reports. Returns the resulting CREDIT invoice.
Recurly: Remove Active Coupon Redemption
Take the active coupon off an account so future invoices are charged at full price. Invoices already issued are untouched, so nothing is refunded or re-billed, and the coupon can be redeemed again - which is why this is a reversible write even though the customer's next bill goes up. Returns the removed redemption with its removed_at timestamp.
Recurly: Remove Billing Info
DESTRUCTIVE. Delete the payment method stored on an account. No money moves at call time, and that is exactly why it is dangerous: every future automatic renewal on that account fails from this moment on, the subscriptions enter dunning, and the stored token cannot be recovered - the customer has to re-enter their card. Returns HTTP 204 with an empty body.
Recurly: Remove Line Item
Delete a PENDING line item so it never reaches an invoice. Only pending line items can be removed - an invoiced one returns an error, which is why this is a reversible write and not a destructive one: no money has moved, nothing is reversed at a gateway, and the charge can simply be created again. To undo an INVOICED charge, refund the invoice instead. Returns HTTP 204 with an empty body.
Recurly: Remove Pending Subscription Change
Cancel a subscription change that has been SCHEDULED but has not activated yet, leaving the subscription exactly as it is today. Nothing is charged or refunded, because a pending change has not billed anything, and the change can simply be created again - which is why this is a reversible write. Returns HTTP 204 with an empty body.
Recurly: Remove Plan
DESTRUCTIVE. Deactivate a plan so nothing new can subscribe to it. Existing subscriptions keep billing, so no customer is cut off, but the v3 API ships NO restore endpoint for plans (unlike coupons, which have one), so the only way back is to create the plan again - and its code may still be taken. The plan's add-ons are deactivated with it.
Recurly: Remove Plan Add-on
DESTRUCTIVE. Deactivate an add-on on a plan so no new subscription can take it. Existing subscribers keep being billed for it, so nobody is cut off, but the v3 API ships NO restore endpoint for add-ons - recreating it means a new add-on, and any usage history stays attached to the old one.
Recurly: Remove Usage Record
Delete a usage record so it is not billed. Only UNBILLED usage can be removed - once the period has closed and the record has a billed_at timestamp it is part of an invoice and the invoice has to be credited instead. Because nothing has been charged and the record can simply be posted again, this is a reversible write. Returns HTTP 204 with an empty body.
Recurly: Restore Coupon
Bring an expired coupon back to redeemable, optionally raising its limits or pushing out its redeem-by date at the same time. This is the endpoint plans and add-ons do not have, which is why deactivating a coupon is classed as a reversible write and removing a plan is not.
Recurly: Resume Subscription
End a pause early and put the subscription back on its normal billing schedule. The next invoice is raised at the next bill date rather than immediately, so this call itself charges nothing.
Recurly: Terminate Subscription
DESTRUCTIVE, and the most consequential node in this connector. Terminate ends the subscription IMMEDIATELY - the customer loses access now, not at the end of the period - and the refund parameter decides whether money leaves the merchant account with it. refund=none (this node's default, and Recurly's) terminates WITHOUT a refund. refund=full refunds the last invoice of the current term. refund=partial prorates a refund for the unused part of the cycle. All three are irreversible; only the last two move money. The separate charge parameter decides what happens to unbilled usage: Recurly's default of true BILLS it on the final invoice, while false writes a negative usage record that zeroes it out, so leaving charge blank can produce a final charge the caller did not ask for. For a gentler end, use Cancel Subscription.
Recurly: Update Account
Update a customer account. Only the fields you fill are sent, so an empty field leaves the stored value alone. The account CODE cannot be changed and is therefore not offered here. No money moves, unless you pass billing_info, which replaces the stored payment method and runs a gateway verification.
Recurly: Update Billing Info
Replace the payment method stored on an account. Nothing is captured, but Recurly does run a gateway verification against the new payment method, so this touches the customer's real card even though it charges nothing. Prefer token_id from Recurly.js or a gateway_token: raw card numbers are accepted by the API but put this workflow in PCI scope, which is why they are reachable only through extra_body here.
Recurly: Update Coupon
Update the parts of a coupon Recurly allows changing: name, redemption limits, redeem-by date and the two descriptions. The discount itself, the code and what it applies to are immutable once created, because customers may already have redeemed it - to change those, deactivate this coupon and create a new one.
Recurly: Update Invoice
Edit the presentational parts of an invoice: purchase order number, customer notes, terms and conditions, VAT reverse charge notes, payment window and billing address. It cannot change any amount, so no money moves and nothing about what the customer owes changes - which is why this is a reversible write while everything else in the invoice family is not.
Recurly: Update Plan
Update a plan's name, pricing, trial or settings. Only the fields you fill are sent. Changing currencies affects only NEW subscriptions and renewals; existing subscribers keep the price recorded on their subscription until a subscription change moves them. The billing interval cannot be changed and is therefore not offered here.
Recurly: Update Subscription
Update a subscription's SETTINGS: auto renew, remaining billing cycles, next bill date, collection method, purchase order and notes. This endpoint deliberately cannot change the plan, price, quantity or add-ons - anything that would alter what the customer is charged goes through Create Subscription Change instead, which is why this one is a reversible write and that one is not. Turning auto_renew off here is the gentle alternative to cancelling: the subscription simply expires at the end of its term.
Recurly: Verify Billing Info
Ask the gateway to verify the account's stored payment method, and get back the resulting verify transaction. It captures and settles nothing, which is why it is a reversible write rather than a destructive one, but it DOES touch the customer's real card: the gateway may place a temporary authorization that the customer can see on their statement. Run it before a renewal or a win-back, not on a schedule.
Recurly: Void Invoice
DESTRUCTIVE. Void an unpaid invoice: the customer no longer owes it and it is struck from the receivables. Only an invoice with an outstanding balance can be voided, and the voided state is terminal - there is no un-void, so the charge has to be raised again from scratch if this was a mistake. This rewrites the accounting record of a real invoice, which is why it is destructive even though no money moves at the gateway.
Connecting Recurly takes one credential
Recurly authenticates with HTTP Basic where the API key is the username and the password is empty, which is Recurly's own documented form. Mattering builds that header from the key alone, so there is no password field to fill in wrongly. Keys are created on the API Credentials page in the Recurly admin and are scoped to a single site, which is why this connector never asks for a site id: the key already chose the site, and Recurly: List Sites will tell you which one and whether it is a sandbox. The credential also carries the data region, because Recurly serves two hosts, one for US sites and one for EU sites, and nothing in the key reveals which one your site lives on. Mattering additionally pins Recurly's version header on every request, because Recurly requires a version to be named and answers a request without one with an error listing the acceptable values rather than a sensible default. Plan gating on Recurly works per feature rather than per node family, and it surfaces as a specific error type: the Wallet feature, Credit Invoices, decimal quantities and the item catalog are features a site may or may not have, and a workflow that hits that error needs the site's plan changed rather than the node reconfigured. Recurly's own pricing and support pages are the place to confirm which features your site includes.
Sign in to Recurly and open the API Credentials page for the site you want to reach. Create a private API key and copy the value.
Note the site's data region. US sites and EU sites are served from different hosts, and the key does not say which, so you supply it once on the credential and every node uses the right host.
In Mattering Automations, open Connectors, click Add Connector, choose Recurly, and create a credential with the key and the region.
Click Test Connection. Mattering calls Recurly's sites endpoint, which needs no parameters and no ids to resolve first, so even a brand new empty sandbox answers. A 401 means the key is wrong or no longer valid.
All 84 Recurly nodes appear in the canvas palette. Run Recurly: List Sites first: it reports the site mode, so you can see at a glance whether this credential is pointed at a sandbox or at the site that bills real customers.
Common uses for the Recurly MCP
Answer billing questions without opening the admin
Recurly: List Accounts finds a customer by email, Recurly: Get Account and Recurly: Get Account Balance give the state and what is owed, Recurly: List Account Subscriptions shows what they pay for, Recurly: List Account Invoices and Recurly: Get Invoice cover the history, and Recurly: List Account Transactions shows what the gateway did. That is one read chain that answers most of what support asks a billing system, and every node in it is a read, which makes it the right surface to expose to an assistant or to a self-serve internal tool.
Dunning that opens a task instead of an email nobody reads
A failed payment is the highest value signal a billing system produces. Recurly: List Invoices and Recurly: List Transactions find the failures, Recurly: Get Account fills in who the customer is, and Mattering does the part Recurly cannot: open a task for the account owner, write a row into a database, post to a channel, and only escalate to the customer when a person has looked. When the fix is on your side, Recurly: Update Billing Info and Recurly: Verify Billing Info are there, though verification runs a real transaction at the gateway and can leave a temporary authorization on the customer's card, so it is not a free check.
Provision and deprovision from the subscription state
Recurly: List Subscriptions and Recurly: Get Subscription tell you who should have access, Recurly: List Account Entitlements answers the same question in the shape an application usually wants, and Recurly: Get Pending Subscription Change shows what is about to change at renewal. A scheduled sweep can reconcile that against your own product's access list and open a task when the two disagree. Reading the pending change matters more than it sounds: it is the difference between provisioning what the customer has and provisioning what they will have next cycle.
Preview the money before anything moves
Three nodes exist purely to answer expensive questions for free, and they are all classed as reads because they change nothing. Recurly: Preview Subscription Change shows the proration and the invoice a plan change would produce, Recurly: Preview Invoice shows what an invoice would look like before it is posted, and Recurly: Preview Purchase prices a whole checkout, including for an account with no payment method stored. Recurly: Preview Subscription Renewal shows what the next renewal will bill. Put a preview and a condition in front of any node that charges, and the charging node becomes the end of a decision rather than the start of a support ticket.
Coupons and promotions on a schedule
Recurly: Create Coupon, Recurly: Update Coupon, Recurly: Deactivate Coupon and Recurly: Restore Coupon turn a promotion into workflow steps, and Recurly: Generate Unique Coupon Codes produces the single use codes a campaign needs in one call. Recurly: Redeem Coupon on Account applies one to a specific customer, which is the retention gesture support usually wants to make immediately. Deactivating a coupon is reversible here, which is unusual on this connector and worth knowing: Recurly ships a restore endpoint for coupons, and redemptions already on customer accounts keep discounting, so nobody is charged more than they expected.
Metered usage, reported from wherever it is measured
Recurly: Record Usage writes a usage record against a subscription add-on, Recurly: List Usage Records reads back what was reported for a period, and Recurly: Remove Usage Record corrects a mistake before it is billed. For a usage priced product this is the node that closes the loop between the system that measures the work and the system that charges for it, and because it is an ordinary canvas step it can run on the same schedule as the aggregation that produces the number.
Example: A refund that a person approves and the workflow cannot repeat
Built on the Automations canvas in a few minutes, or described in plain language to Matter and built for you.
Trigger: a support form or an inbound email arrives asking for a refund, carrying an email address or an invoice number.
Recurly: List Accounts finds the account by email, and Recurly: List Account Invoices plus Recurly: Get Invoice read the invoice in question: what was billed, what was paid, and what is still refundable.
A condition checks the refundable amount against the request. Anything inside policy continues, anything outside it routes to a different approver, and nothing has moved yet.
A Mattering task opens for the finance owner with the invoice, the amounts and the customer history attached. This is the approval step, and it exists because the next one cannot be taken back.
On approval, Recurly: Refund Invoice runs with an idempotency key set from the task id. Money leaves the merchant account here and there is no un-refund, so the idempotency key is what makes a retried run replay the original result instead of refunding twice.
Recurly: Get Account Balance reads the account back, the outcome is written into a Mattering database, and the task closes with the transaction id recorded next to the request that started it.
Recurly MCP questions, answered
What Recurly operations are supported?
84 nodes on Recurly API v3 at the 2021-02-25 version: 40 read nodes and 44 action nodes. Sites, accounts (list, get, create, update, deactivate, reactivate, balance, child accounts, entitlements), billing info (get, update, remove, verify), subscriptions (list, get, per account, create, update, cancel, reactivate, pause, resume, terminate, convert trial, renewal preview) and subscription changes (get, preview, create, remove), plans and plan add-ons, invoices (list, get, per account, per subscription, preview, create, update, collect, refund, void, mark paid, mark failed, apply credit balance), line items, transactions, coupons and redemptions, unique coupon codes, credit payments, purchases (preview, create, authorize, capture) and usage records. Deliberately not included: the app management family for reconciling app store billing, the Wallet billing infos family, dashboard level configuration such as dunning campaigns and general ledger accounts, gift cards, the item catalog, and account redaction, which permanently erases a data subject's personal data and belongs with a person in the Recurly admin rather than in an unattended workflow.
Does this work with Claude, ChatGPT, or other AI assistants?
Yes. Mattering exposes these nodes over MCP, an open protocol for connecting AI assistants to tools, so any MCP-capable assistant, including Claude and ChatGPT, can connect to your workspace and use them. Matter, the assistant built into the platform, uses the same nodes natively. On a billing system the split is unusually clean: the 40 read nodes answer nearly every question anyone actually asks, and the four preview nodes answer the what if questions without changing anything, so an assistant can be genuinely useful on a read-only surface. Keep the 18 flagged nodes behind a condition or an approval task.
Can I try this without touching real customers?
Yes, and this is the best thing about automating Recurly. Recurly offers a free self-serve sandbox site with no payment method and no sales conversation, and it is a full environment rather than a demo: it can hold plans, accounts, subscriptions and invoices, so much of the connector can be exercised without touching a real customer. There is no separate sandbox host to configure, because the credential selects the site, so a workflow proven on a sandbox key runs identically on a production key. Recurly: List Sites reports the mode, which is a good first node in any workflow that is about to charge someone. One practical difference: Recurly documents a tighter rate limit on sandbox sites than on production ones and counts every method there rather than only reads, so pace a full rehearsal run.
Which nodes can charge or refund a customer?
Eighteen nodes are flagged destructive, and Recurly's HTTP methods are no guide at all, which is why the flags exist. Recurly: Collect Invoice is an ordinary update that runs a real payment attempt against the stored card right now. Recurly: Refund Invoice moves money out with no un-refund anywhere in the API. Recurly: Create Invoice posts pending charges and, with automatic collection, collects immediately. Recurly: Create Purchase and Recurly: Capture Purchase settle money. Recurly: Create Subscription is on the list deliberately: it bills against billing info the customer already authorized, so unless the plan has a trial or the call sets manual collection or a future start date, the first invoice is created and collected the moment the call succeeds. Recurly: Create Subscription Change defaults to taking effect now, which prorates and invoices immediately. Recurly: Cancel Subscription, Recurly: Terminate Subscription and Recurly: Convert Trial end or accelerate the paid relationship. Recurly: Void Invoice, Recurly: Mark Invoice Paid Successfully, Recurly: Mark Invoice Failed and Recurly: Apply Credit Balance to Invoice rewrite the accounting record. Recurly: Deactivate Account cancels the account's subscriptions and reactivating the account does not bring them back. Recurly: Remove Billing Info moves no money, and that is precisely why it is dangerous: every future renewal then fails and the stored token cannot be recovered. Recurly: Remove Plan and Recurly: Remove Plan Add-on have no restore endpoint.
How do I stop a retried workflow from charging someone twice?
Use the idempotency key field, which every write node in this connector carries. Recurly honours an idempotency key on writes and, for an identical repeat, replays the stored response instead of performing the operation again, flagging the response as a replay. Recurly documents that the stored response lasts one hour and that keys must be 255 characters or fewer, and recommends a UUID. Set it from something stable in the workflow, such as the task id or the source record id, rather than generating a fresh value on each attempt, since a new key on a retry is exactly what an idempotency key exists to prevent. Recurly also answers an in flight duplicate with a conflict status that says the call should be retried, and it deliberately does not cache rate limited responses.
Can I get MRR or churn from these nodes?
Not directly, and it is worth saying plainly because it is the first thing anyone expects from a subscription billing connector. Recurly's v3 API publishes no MRR endpoint and no churn rate endpoint: those live in Recurly's analytics and exports product, whose API surface hands back generated export files rather than computed metrics and is not built here. What you can do is derive the numbers from the underlying records, which is what these 84 nodes are for: Recurly: List Subscriptions with their plans and amounts, Recurly: List Invoices and Recurly: List Transactions for what was actually billed and collected, and Recurly: List Credit Payments for the credit side. Write those into a Mattering database on a schedule and the trend is yours to compute, on your definitions rather than someone else's.
What are Recurly's rate limits?
Recurly documents them by site type, and the production numbers are unusually generous. A sandbox site is limited to 400 requests per minute with all methods counted. A production site is limited to 1,000 requests per minute, and Recurly counts only GET requests towards it, so write volume is not what pushes a production site into the limit. The limit is calculated over a sliding five minute window, which means a production site can burst well above the per minute figure if the preceding minutes were quiet, and Recurly returns the limit, the remaining count and the reset time in response headers, answering with a rate limited status when the ceiling is reached. Recurly also states that a business needing a higher limit should contact support, so treat these as documented defaults rather than as fixed ceilings.
Why does the credential ask for a region?
Because Recurly serves US sites and EU sites from different hosts, and nothing in the API key reveals which one your site lives on. That makes the region a property of the credential rather than something the connector can discover, so you set it once when you create the credential and every node builds the right host from it. Common spellings are normalized and leaving it blank means the US host. If you run sites in both regions, create one credential per site, which you would want anyway, since a Recurly key is scoped to a single site.
Which API version does the connector use, and why does that matter?
Recurly API v3 at the 2021-02-25 release, pinned on every request. This matters more than usual with Recurly because the version is chosen by a request header and there is no default: a request that names no version, or misspells one, is refused with a message listing the acceptable values rather than being served something sensible. Recurly also keeps a previous v3 release supported and still hosts the older XML API v2, whose request and response shapes and field names are different, so any example copied from a v2 page is wrong here in both format and naming. Recurly echoes the version it served on every response, which is the cheapest confirmation that the pin took effect. Moving the connector forward means re-sampling the catalog against the newer release, not editing a number.
Put Recurly to work inside your workspace
Connect once, then use every node in visual automations and AI agent workflows across the Mattering platform.
All product names, logos, and brands are property of their respective owners and are used for identification purposes only. Use of these names, logos, and brands does not imply endorsement or affiliation. Recurly is a product of its respective owner; Mattering is an independent platform.