Recurly

Configuration guide for the Recurly connector in Recurly Engage, including activation, data sync, and 1-Click subscription actions.

Overview

The Recurly integration allows you to sync your subscription data and execute billing actions directly from prompts in Recurly Engage, leveraging your Recurly account.

Video

Required plan

This feature or setting is available to all customers on any Recurly Engage subscription plan.

Prerequisites & limitations

  • Company or App Administrator permissions in Recurly Engage.
  • A Recurly account with API access and valid API key.
  • If your application uses custom User IDs (Account Codes), enable Use Account Code in the connector settings.

Definition

The Recurly connector imports subscription traits nightly and provides actions for managing subscriptions—coupon application, plan changes, pauses, resumes—via prompts.

Key benefits

  • Seamless billing workflows: Manage subscriptions without leaving the prompt interface.
  • Real-time data: Keep segments and prompts in sync with nightly data imports.
  • Flexible configurations: Support custom account codes and multiple subscription actions.

Key details

Activation

  1. Generate an API Key in the Recurly console.
  2. In Recurly Engage, navigate to Settings > Integrations > Recurly and paste your API Key.
  3. Toggle Use Account Code to On if you map your own user IDs to Recurly Account Codes.
  4. Toggle Active to On.

API Key (Instructions )

Data integration

to enable the automated sync.

Once enabled, the following traits are imported nightly:

Trait NameDescription
stateCurrent state of subscription (pending, active, canceled, expired)
plan_codePlan code the customer is subscribed to
currencyCurrency of the subscription
current_period_started_atDate/time when the current billing period starts
current_period_ends_atDate/time when the current billing period ends
trial_started_atDate/time when the trial period began
trial_ends_atDate/time when the trial period ends
activated_atDate/time the subscription became active
canceled_atDate/time the subscription was canceled
expires_atDate/time when the subscription will churn
statusInvoice status (pending, processing, past_due, paid, failed, voided)
maintenance_urlLink to the customer’s hosted account maintenance page (if enabled)

Supported actions

Once your connector is active and data is synced, you can attach these 1-Click actions to prompt interactions. The account_code or account_number trait must be present on users.

ActionDescriptionAPI IntegrationAdditional Instructions
Apply Coupon CodeApplies a coupon code to the user's account or subscriptionCoupon RedemptionSelect the coupon code
Pause SubscriptionPauses a user's subscriptionPause SubscriptionSelect how many billing cycles to pause for
Resume SubscriptionResumes a paused subscriptionResume Subscription
Switch SubscriptionSwitches the user to a new planSubscription ChangeSelect the plan
Create SubscriptionCreates a subscription for an existing accountCreate SubscriptionSelect the plan and enter the currency
Reactivate SubscriptionReactivate a cancelled subscriptionReactivate Subscription
Update Subscription PriceUpdate price of an active subscriptionSubscription Change
Convert TrialConvert trial to paid subscriptionConvert Trial
Record UsageLogs a usage record for a subscription add-onLog Usage RecordSelect the add-on and amount
Cancel SubscriptionStops auto-renewal for an active subscriptionCancel SubscriptionSelect refund option