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
`account_code`	The Recurly account identifier — the join key linking a Recurly account to an Engage user. Must match the user's ID in Engage, or be mapped via Use Account Code.
`plan_code`	The code of the plan the customer is currently subscribed to.
`plan_name`	The display name of the current plan.
`state`	Current subscription state. Possible values: `pending`, `active`, `canceled`, `expired`.
`currency`	The three-letter currency code for the subscription (e.g. `USD`, `EUR`).
`total_recurring_amount`	The total amount billed on a recurring basis, in the subscription's currency.
`current_period_started_at`	Date and time the current billing period started.
`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 fully expire.
`status`	Invoice status from the subscriber's most recent invoice. Possible values: `pending`, `processing`, `past_due`, `paid`, `failed`, `voided`. (webhook)
`maintenance_url`	Link to the subscriber's hosted account maintenance page in Recurly, if the hosted pages feature is enabled.
`active_coupon_codes`	Comma-separated list of coupon codes active on the subscriber's most recent invoice. (webhook)
`plan_coupon_codes`	Comma-separated list of coupon codes applied at the subscription level. Distinct from `active_coupon_codes`, which reflects invoice-level redemptions. (webhook)
`card_expiration_date`	The subscriber's credit card expiration date, formatted as `YYYY-MM-01`. Empty if no card is on file. (webhook)
`has_billing_info`	Whether the account has a payment method on file (`true` or `false`). Useful for targeting users who need to add payment details. (webhook)
`payment_method_type`	The type of payment method on file. Common values: `credit_card`, `paypal`, `amazon`, `check`. (webhook)
`past_due_invoice_date`	The date of the subscriber's most recent past-due invoice. Set when a `past_due` webhook event is received. (webhook)

NoteTraits marked (webhook) require Recurly webhooks to be configured and active. The nightly CSV export does not populate these traits.

Subscription add-ons

The subscription_add_ons trait contains a list of all add-ons currently attached to the subscriber's subscription. It can be used to segment users based on which add-ons they have active.

Each item in the list is an object with the following fields:

Field	Description
`add_on_code`	The unique code identifying the add-on.
`add_on_name`	The display name of the add-on.
`quantity`	How many units of the add-on the subscriber has.
`unit_amount`	The per-unit price of the add-on.
`created_at`	Date and time the add-on was added to the subscription.
`expired_at`	Date and time the add-on expired, if applicable.

Notesubscription_add_ons is updated via Recurly webhooks. Ensure webhooks are active for this trait to stay current.

External subscription traits

For merchants using Recurly's App Management feature — subscriptions sold through the Apple App Store or Google Play — an additional set of traits is synced nightly from the External Subscriptions export.

Trait	Description
`external_product_reference_code`	The reference code for the external product.
`external_product_reference_source`	The source of the external subscription. Common values: `apple_app_store`, `google_play_store`.
`external_product_name`	The display name of the external product.
`external_product_activated_at`	Date and time the external subscription was activated.
`external_product_expires_at`	Date and time the external subscription expires.
`external_product_state`	Current state of the external subscription.

WarningExternal subscription traits require the External Subscriptions (v5) export to be enabled in Recurly Subscription Management. If you're not using Recurly App Management, this section doesn't apply.

1-Click actions — required traits

To use 1-Click subscription actions in prompts — such as Apply Coupon, Switch Plan, or Cancel Subscription — Recurly Engage needs to look up the subscriber's account in Recurly. Depending on your integration configuration, one of the following traits must be present on the user's profile:

Trait	When to use
`account_code`	Used when Use Account Code is enabled in the integration settings. Recurly Engage assumes the user's ID matches their Recurly account code — no separate trait is needed.
`recurly_account_code`	Used when Use Account Code is not enabled and your Engage user IDs differ from Recurly account codes. Set this trait to the subscriber's Recurly account code so Engage can look up their account.
`recurly_subscription_id`	Optional. When set, Recurly Engage targets this specific subscription rather than looking up the subscriber's active subscription automatically. Useful for multi-subscription accounts.

Custom subscription fields

If you use Recurly's custom subscription fields feature, Recurly Engage can sync those field values as additional user traits. This lets you use any custom data stored on subscriptions in Recurly for segmentation and targeting in Engage.

Custom field mapping is configured per app in Pulse → Settings → Integrations → Recurly. For each custom field, you define the Recurly field name and, optionally, a different trait name to use in Engage. Trait names are app-specific and will vary by merchant.

Contact [email protected] or your CSM to enable this feature.

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