Mattering Automations Recurly integration
Connect Recurly to Mattering Automations: accounts and billing info, subscriptions and pending changes, plans and add-ons, invoices, line items, transactions, coupons, credit payments, purchases and metered usage as workflow steps, authenticated with one site-scoped API key.
The Mattering Automations Recurly integration puts Recurly API v3 on your automation canvas: accounts, child accounts, balances and entitlements, billing info, subscriptions with their whole lifecycle and their pending changes, plans and add-ons, invoices including collection and refunds, line items, transactions, coupons and redemptions, credit payments, purchases with authorize and capture, and metered usage records.
The credential is a Recurly API key, created on the API Credentials page in the Recurly admin. Recurly authenticates with HTTP Basic where the key is the username and the password is empty, and Mattering builds that header from the key alone, so there is no password field on the Create new credential form. A key is scoped to a single Recurly site, which is why this integration asks for no site id: the key already chose the site. It does ask for one more thing, the site's data region, because Recurly serves US sites and EU sites from different hosts and nothing in the key reveals which.
Before you build anything against a site that bills real customers, use the sandbox. 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: plans, accounts, subscriptions and invoices all work. 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 the cheapest way to confirm which kind of site a credential is pointed at. Setup takes a few minutes, and this guide walks through each step and ends with the full node reference.
Before you start
- A Recurly site and an admin account that can create a private API key on the API Credentials page. Keys are scoped to one site, so one credential per site.
- The data region of that site. US sites and EU sites are served from different hosts and the key does not identify which, so the region is a field on the credential.
- A Recurly sandbox site if you are still designing. Recurly's sandbox is free, self-serve, needs no payment method and behaves like a real site, which makes it the right place to exercise Recurly: Refund Invoice, Recurly: Collect Invoice and the rest of the flagged nodes before a real customer is involved.
- A Mattering workspace with access to the Automations app.
- Worth knowing before you scope a workflow: Recurly gates some capabilities per feature rather than per plan tier, and it surfaces as a specific missing feature error rather than a permission error. The Wallet feature, Credit Invoices, decimal quantities and the item catalog are the documented examples. A workflow that hits that error needs the site's plan changed rather than the node reconfigured, and Recurly's own pricing and support pages are where to confirm what your site includes.
Create a Recurly API key
Mattering authenticates to Recurly with a private API key sent as the username of an HTTP Basic header with an empty password, which is Recurly's own documented form. The key belongs to one site, so the first decision is which site this credential should reach, and the second is which data region that site lives in.
Connect Recurly to Mattering
Verify it works
After connecting, open any automation canvas and check the palette: a Recurly section should list the read and action nodes. Drop Recurly: List Sites onto the canvas and run a test step. It is the integration's natural probe, because it needs no parameters and no id resolved first, and it answers the question that matters most before anything else runs: the site mode, sandbox, development or production. Confirm it says what you expect. If a credential you believed was a sandbox reports production, stop and fix that before running anything else.
Now try a real read. Drop Recurly: List Accounts onto the canvas and run it: rows come back inside Recurly's own list envelope, so the accounts sit one level deeper than usual, at data.data, with a flag saying whether more pages exist and a path to the next page beside it. Then open a node with a picker, for example Recurly: Get Subscription, and click the Subscription field: it should list subscriptions labelled by plan name with the account email underneath and grouped by state, which is what makes an opaque Recurly id legible. Everything in this verify path is read-only, so it cannot reach the 18 flagged nodes and is safe to re-run whenever you rotate the key.
Node reference
84 nodes, generated from the connector itself so this reference always matches what ships.
Read and query nodes 40
Recurly: Get Account
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
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
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
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
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
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
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
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
recurly_get_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
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
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
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
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
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
recurly_list_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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
recurly_list_usage
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
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
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
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
recurly_get_preview_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
recurly_apply_credit_balance
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
recurly_create_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
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
recurly_create_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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
recurly_mark_invoice_successful
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
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
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
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
recurly_create_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
recurly_create_coupon_redemption
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
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
recurly_remove_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
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
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
recurly_remove_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
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
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
recurly_remove_usage
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
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
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
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
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
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
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
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
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
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
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
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.
Using the integration
On the automation canvas
Recurly nodes chain with every other node in the workspace. A failed payment found by Recurly: List Invoices can open a Mattering task, write a row into a database and post to a channel in one run. A form submission can create an account with Recurly: Create Account. A nightly sweep can reconcile Recurly: List Account Entitlements against your own product's access list. Identifier fields are pickers sourced from the matching list node, and they are labelled to be readable rather than accurate-and-useless: Recurly ids are opaque strings with no type prefix, so a subscription shows its plan name with the account email underneath, and a credit payment, which has no name at all, shows its account. Two fields deliberately read a code rather than an id, account code and plan code, because those are the values Recurly expects nested in a request body and an opaque id there is rejected.
From AI assistants over MCP
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter, the assistant built into the platform, can drive the same surface. Billing splits unusually cleanly for this: the 40 read nodes answer nearly every question support actually asks, and the four preview nodes, Recurly: Preview Invoice, Recurly: Preview Purchase, Recurly: Preview Subscription Change and Recurly: Preview Subscription Renewal, answer the what if questions while changing nothing at all, even though two of them are technically creates. That is a genuinely useful assistant surface with no write risk. Keep the 18 flagged nodes off it, or route them through an approval task.
Preview before you charge
The single most useful pattern here is putting a preview and a condition in front of anything that moves money. Recurly: Preview Subscription Change returns the proration and the invoice a plan change would produce, so a workflow can check the number before committing to it. Recurly: Preview Invoice shows an invoice before it is posted. Recurly: Preview Purchase prices a whole checkout and, as Recurly documents, can do so with manual collection for an account that has no payment method stored yet. Recurly: Preview Subscription Renewal shows what the next renewal will bill. All four change nothing, so they are safe on any credential and safe in front of an approval task.
Idempotency keys, and why every write node has one
This is the difference between a retried workflow run charging a customer once and charging them twice, so it deserves a habit rather than a case by case decision. Every write node here carries an idempotency key field, and Recurly replays the stored response for an identical repeat instead of performing the operation again, marking the response as a replay. Recurly documents the stored response as lasting one hour, keys as 255 characters or fewer, and recommends a UUID. Set the key from something stable in the run, such as a task id or a source record id, because a freshly generated value on each attempt defeats the entire mechanism. Recurly also answers an in flight duplicate with a conflict status telling you the call should be retried, and deliberately does not cache rate limited responses, so a retry after a rate limit does what you want.
The date filters mean different things depending on the sort
Twenty of the list nodes accept a begin time and an end time, and this is the trap worth understanding once rather than debugging later: the window filters whichever timestamp the sort field names. Sort by creation and the range means created in this period. Sort by update and the same range means changed in this period. Those answer different questions, and a workflow that filters on one while bucketing rows by the other receives rows dated outside the window it asked for. Pick the sort deliberately on every windowed node. Recurly adds one warning of its own: sorting by update in the default descending order can miss records mid page as they move behind the cursor, so use ascending order when you sort by update. Two more constraints on the same fields: a list of ids cannot be combined with the date filters, and the page size is capped at 200 with a default of 20.
Paging through a list without inventing a cursor
Recurly's lists come back with a flag saying whether more pages exist and a path to the next page, cursor already included. There is no page number or cursor parameter to construct: every list node here carries a next path field, and filling it replaces the request path with the value Recurly returned. The loop is therefore read a page, check the more flag, feed the returned path into the next iteration, and stop when the flag goes false. Anything pasted into that field is stripped back to a path, so it cannot redirect the request somewhere else. One shape to expect while wiring it: because Recurly's own list envelope sits inside the connector's envelope, rows read at data.data rather than data.
Money movement, and the nodes whose method lies about it
Eighteen nodes are flagged destructive and the flags are the only reliable guide, because Recurly's verbs are not. Recurly: Collect Invoice runs a real payment attempt against the stored card right now. Recurly: Refund Invoice moves money out with no reverse anywhere in the API, and when the invoice was paid by credit the refund returns credit rather than money to a card. Recurly: Create Invoice posts pending charges and, with automatic collection, collects them. Recurly: Create Purchase and Recurly: Capture Purchase settle money. Recurly: Create Subscription is flagged 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 date, the first invoice is created and collected the moment it succeeds. Recurly: Create Subscription Change defaults to taking effect immediately, which prorates and invoices there and then, and it replaces the full add-on set, so sending only the additions silently removes the rest. Recurly: Terminate Subscription has two parameters worth setting explicitly rather than inheriting: the refund choice, which defaults to no refund and can be a full or prorated one, and the charge flag, which Recurly defaults to true so that unbilled usage in the current cycle lands on the final invoice. Recurly: Deactivate Account cancels the account's subscriptions and reactivating the account does not restore them. Recurly: Remove Billing Info moves no money, which is exactly why it is dangerous: every future renewal then fails and the stored token cannot be recovered.
Reporting on revenue, when the API has no revenue endpoint
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 returns links to generated files rather than computed metrics and is not built here. So revenue reporting from this integration means deriving it: Recurly: List Invoices and Recurly: List Transactions for what was billed and collected, Recurly: List Subscriptions for the recurring base, and Recurly: List Credit Payments for the credit side, written into a Mattering database on a schedule. One caution while designing that: which numbers can be added up depends on the window you chose. Invoice totals sum sensibly over a creation window and double count over an update window, because an invoice re-enters every window in which anything about it changed, and a subscription's amount is the current recurring price rather than a period's revenue, so summing it across a creation date range produces a figure that looks like revenue and is not.
Troubleshooting
Test Connection fails with a 401 error
Every call fails with a message about the API version
A date filtered list returns rows outside the range I asked for
A node fails with a missing feature error
A workflow retry charged a customer twice
An invoice reconciliation is missing line items
A subscription change removed add-ons nobody asked to remove
Terminating a subscription produced an unexpected final charge or refund
Reactivating an account did not bring its subscriptions back
A template reading a list resolves to nothing
Related
The Recurly MCP
What connecting Recurly 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.
Recurly 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.