Menu

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.

Sign in to Recurly and open the API Credentials page for the site you want this credential to reach.
Create a private API key and copy the value.
Note the site's data region, US or EU. You will enter it on the credential, and every node builds the right host from it.
There is no password to supply and no site id to look up. Recurly's Basic header carries the key as the username with nothing after the separator, Mattering assembles it for you, and the key already selects the site.
This key can charge and refund real customers. With it, one call can collect an invoice against a stored card, issue a refund that has no reverse, terminate a subscription or remove billing info so every future renewal fails. Create a sandbox site and a sandbox key for anything you are still designing, and keep the production key in a workspace whose members you would trust with the billing admin itself.

Connect Recurly to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Recurly from the list.
Click Create new credential, paste the API key, set the Region to match the site, and save. Name the credential for its site, for example Recurly Sandbox and Recurly Production, because a key gives no clue which is which once it is stored.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs. Mattering also pins Recurly's API version header on every request, because Recurly requires a version to be named and refuses a request that does not name one.
Click Test Connection. Mattering calls Recurly's sites endpoint, which needs no parameters and no ids resolved first, so even a brand new empty sandbox answers it. A 401 means the key is wrong or no longer valid.
Click Connect. All 84 Recurly nodes appear in your canvas palette.
Eighteen of those nodes are flagged destructive, and Recurly's HTTP methods are no guide to which: Recurly: Collect Invoice is an ordinary update that charges a card immediately, and Recurly: Terminate Subscription is a delete that can refund money. Read the flagged list in the node reference before you attach anything to a trigger.

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
Recurly answers an invalid or missing key with 401 and an error type naming the key rather than the request. Check for whitespace picked up in the copy, and confirm the key still exists on the API Credentials page for that site. One more cause is specific to this integration: the connection test is made against the US host, so a credential for a site in the EU data region can fail the test while every node works correctly, because the nodes build the host from the region on the credential and the test does not. If the region is set to EU and the nodes run fine, that 401 on the test alone is expected rather than a fault.
Every call fails with a message about the API version
Recurly requires the request to name an API version and has no default, so a request without one is refused with a message listing the acceptable values rather than being served something sensible. Mattering pins the version on every call, so seeing this usually means a node was given an overriding header of its own, or a workflow is calling Recurly through a generic HTTP node instead of a Recurly node. Use the connector's nodes, or copy the version header exactly. Recurly echoes the version it served on every response, which is the quickest way to confirm what actually went out. Note this is not an authentication failure: a version problem and a key problem produce different statuses, so read the error type before changing the key.
A date filtered list returns rows outside the range I asked for
This is the sort dependent window, and it is Recurly's design rather than a fault. The begin time and end time filter whichever timestamp the sort field names: sorting by creation makes the range mean created in this period, sorting by update makes the same range mean changed in this period. If the workflow then buckets rows by creation date while filtering on updates, rows will legitimately fall outside the window. Set the sort explicitly on every windowed node so the filter and the reporting agree. Two related constraints: a list of ids cannot be combined with the date filters at all, and Recurly warns that sorting by update in descending order can miss records mid page as they move behind the cursor, so use ascending order when sorting by update.
A node fails with a missing feature error
That is plan gating rather than a bug, and it is worth recognising because the fix is not in the workflow. Recurly gates certain capabilities per feature, and names the Wallet feature, Credit Invoices, decimal quantities and the item catalog as examples. A node hitting this error needs the site's plan or feature set changed in Recurly, not a different configuration. Check Recurly's pricing and support pages, or ask your Recurly contact which features the site includes, before redesigning around the error. It is distinct from a permissions error, which points at the API key instead.
A workflow retry charged a customer twice
The idempotency key was either not set or was regenerated on the retry. Every write node here carries the field, and Recurly replays the stored response for an identical repeat rather than performing the operation again, for one hour, with keys of 255 characters or fewer. The value has to be stable across attempts to work, so derive it from something the run already has, such as a task id, an invoice id or a source record id, rather than generating a new value each time. If two calls raced instead, Recurly answers with a conflict status telling you the call should be retried: retry it, with the same key.
An invoice reconciliation is missing line items
Recurly truncates the line items embedded in a single invoice response on large invoices, and signals it with a flag saying more line items exist. So anything reconciling an invoice line by line has to read them from Recurly: List Invoice Line Items rather than from the invoice payload. Check that flag on the invoice before trusting the embedded array, and treat the embedded list as a preview rather than the record.
A subscription change removed add-ons nobody asked to remove
Recurly: Create Subscription Change replaces the full add-on set rather than merging it, so sending only the additions removes everything omitted. Read the subscription first, build the complete add-on list you intend to end up with, and send that. Two more defaults on the same node are worth setting explicitly: the change takes effect immediately unless told otherwise, which prorates and invoices right away, and Recurly: Preview Subscription Change will show you exactly what that produces before anything commits.
Terminating a subscription produced an unexpected final charge or refund
Two parameters decide that, and both have defaults that surprise people. The refund choice defaults to no refund, with full and prorated as the alternatives, and only those two move money out of the merchant account. The charge flag defaults to true, which means the current cycle's unbilled usage is billed on the final invoice, so leaving it blank produces a charge the caller did not ask for. Set both explicitly on Recurly: Terminate Subscription rather than inheriting the defaults. One nuance Recurly documents: when the most recent invoice was paid entirely by credit, a refund returns credit to the customer's account rather than money to a card.
Reactivating an account did not bring its subscriptions back
That is documented behaviour. Recurly: Deactivate Account cancels the account's subscriptions, and Recurly: Reactivate Account restores the account without restoring them. If the intent was a pause rather than a removal, Recurly: Pause Subscription and Recurly: Resume Subscription are the reversible pair, and Recurly: Reactivate Subscription works within the current term after a cancellation. Rebuild the subscriptions explicitly with Recurly: Create Subscription if they are genuinely needed again, remembering that creating one bills immediately unless the plan has a trial or the call sets manual collection or a future start date.
A template reading a list resolves to nothing
Recurly wraps every list in its own envelope, which sits inside the connector's envelope, so list rows read at data.data rather than data. Single records are flat, so a single account reads at data.id and data.email. If a path with one level of data works on a get node and fails on a list node, that doubled path is why. The same envelope also carries the paging fields: a flag saying whether more pages exist, and the path of the next page, which is the value the node's next path field takes.

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.

Start Free Explore our Products