The Recurly connector links your Recurly account to Recurly Engage, so you can sync subscription data and run billing actions right from your prompts. Apply coupons, switch plans, pause or resume subscriptions, and more — without leaving the prompt interface.

Available on all Recurly Engage plans

1Definition 2Key benefits 3Key details

Prerequisites

Company or App Administrator permissions in Recurly Engage
A Recurly account with API access and a valid API key
The Integrations role in Recurly Subscription Management to configure Automated Exports — some exports also require the Admin role

NoteIf your application uses custom user IDs (Account Codes), turn on "Use Account Code" in the connector settings.

Definition

The Recurly connector imports subscription traits from your Recurly account into Recurly Engage every night, and gives you 1-Click actions for managing subscriptions — applying coupons, switching plans, pausing, and resuming — directly from your prompts.

Key benefits

Billing without leaving the prompt Apply coupons, switch plans, pause, and resume subscriptions right from the prompt interface.

Data that stays current Nightly imports keep your segments and prompts aligned with the latest subscription state.

Flexible configuration Map your own account codes and choose from a range of subscription actions.

Key details

Activation

Generate an API key

In the Recurly console, generate an API key for the connector to use.

Add the key to Recurly Engage

Go to Settings → Integrations → Recurly and paste your API key.

Set Use Account Code

Toggle Use Account Code to On if you map your own user IDs to Recurly account codes.

Activate the connector

Toggle Active to On.

For help generating a key, see the API key instructions.

Configure automated exports in Recurly Subscription Management

The connector's nightly sync depends on four exports being enabled on the Recurly Subscription Management side.

WarningWithout these four exports enabled, the connector still shows as Active in Recurly Engage — but no traits will populate.

In Recurly Subscription Management, go to Integrations → Automated Exports and enable each of the following, filtered on Modified Yesterday:

Export	Version	Filter
Billing Info	v6	Modified Yesterday
Invoices — Summary	v5	Modified Yesterday
Subscriptions	v5	Modified Yesterday
External Subscriptions	v5	Modified Yesterday — only if you use App Management

The Modified Yesterday filter keeps each export scoped to the previous day's changes, which is what lets Recurly Engage stay in sync on its nightly cadence. For general setup steps, see Automated exports.

Verify the connection

Once exports are enabled in Recurly Subscription Management and the connector is active in Recurly Engage, confirm both sides are set up correctly:

Check the connector status

In Recurly Engage, go to Settings → Integrations → Recurly and confirm the connector shows Active.

Confirm the exports

In Recurly Subscription Management, go to Integrations → Automated Exports and confirm all four exports are enabled with a recent successful run.

Check your user traits

In Recurly Engage, go to Settings → User Traits and confirm the imported attributes are populating.

If traits aren't appearing after the first nightly cycle, check that:

All four exports are still enabled and haven't been superseded by a newer version. Recurly doesn't auto-upgrade export versions, so when a new version is released you'll need to delete and recreate the export configuration manually.
The API key in the connector hasn't expired or been regenerated on the Recurly Subscription Management side.
The Modified Yesterday filter is applied to every export. Without it, an export can return more or less data than the connector expects.

Data integration

Automated exports sync on a nightly basis, and each run imports the subscription traits below. Learn more about importing user traits with Recurly, or about configuring Automated Exports in Recurly Subscription Management. To receive near real-time data instead of waiting for the nightly sync, integrate with Recurly webhooks.

Trait	Description
`state`	Current state of the subscription (pending, active, canceled, expired)
`plan_code`	Plan code the customer is subscribed to
`currency`	Currency of the subscription
`current_period_started_at`	Date and time the current billing period starts
`current_period_ends_at`	Date and time the current billing period ends
`trial_started_at`	Date and time the trial period began
`trial_ends_at`	Date and time the trial period ends
`activated_at`	Date and time the subscription became active
`canceled_at`	Date and time the subscription was canceled
`expires_at`	Date and time the subscription will churn
`status`	Invoice status (pending, processing, past_due, paid, failed, voided)
`maintenance_url`	Link to the customer's hosted account maintenance page, if enabled
`total_recurring_amount`	The total amount, in the subscription's currency, billed on a recurring basis

Supported actions

Once your connector is active and data is synced, you can attach these 1-Click actions to prompt interactions.

NoteEach user must have the account_code or account_number trait present for these actions to work.

Action	Description	API integration	Additional instructions
Apply Coupon Code	Applies a coupon code to the user's account or subscription	Coupon Redemption	Select the coupon code
Pause Subscription	Pauses a user's subscription	Pause Subscription	Select how many billing cycles to pause for
Resume Subscription	Resumes a paused subscription	Resume Subscription	—
Switch Subscription	Switches the user to a new plan	Subscription Change	Select the plan
Create Subscription	Creates a subscription for an existing account	Create Subscription	Select the plan and enter the currency
Reactivate Subscription	Reactivates a canceled subscription	Reactivate Subscription	—
Update Subscription Price	Updates the price of an active subscription	Subscription Change	—
Convert Trial	Converts a trial to a paid subscription	Convert Trial	—
Record Usage	Logs a usage record for a subscription add-on	Log Usage Record	Select the add-on and amount
Cancel Subscription	Stops auto-renewal for an active subscription	Cancel Subscription	Select refund option