Recurly

Recurly is a subscription management and recurring billing platform that automates the full subscription lifecycle — plan creation, subscriber onboarding, invoicing, payment processing, and revenue recognition. It supports flat-rate, usage-based, tiered, and hybrid pricing and integrates with leading payment gateways to reduce churn and recover failed payments. It's used by SaaS, media, and e-commerce businesses.

Power end-to-end data operations for your Recurly API with Nexla. Our bi-directional Recurly connector is purpose-built for Recurly, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to Recurly or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your Recurly workflows fast, secure, and fully governed.

Features

Type: API

SourceDestination

• Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
• Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
• API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
• Request optimization with intelligent batching, retry, and caching to minimize API calls and costs

Prerequisites

To connect Nexla to Recurly, you need a Recurly account with API access and a private API key. Recurly's V3 API uses HTTP Basic Authentication, where your private API key serves as the username.

Recurly private API keys grant programmatic access to your Recurly account and should be kept secure. API keys provide full access to your account data, so treat them like passwords and avoid sharing or exposing them publicly.

1. Sign in to your Recurly Admin Console at app.recurly.com.

2. Navigate to Integrations > API Credentials in the left-hand navigation menu.

3. If no API key exists, click Add Private API Key to generate a new one. Assign a descriptive name (for example, "Nexla Integration") to help identify the key's purpose.

4. Copy the generated private API key and store it securely. You will need this key when creating the Nexla credential.

Only users assigned a Role that includes the Integration permission can access the API Credentials page. Contact your Recurly account administrator if you do not see this option. For additional details, see the Recurly REST API Keys documentation.

Authenticate

Credentials required

Recurly V3: use your private API key as the Basic auth username (password optional). Enter the key when connecting—do not rely on a default. Same pattern as Postman: username = API key.

Field	Required	Secret	Description
Username Or API Key	Yes	No	Private API key from Recurly (API Credentials). Used as Basic auth username; no default—paste at test/connection time only.
Password	No	Yes	Optional password

Create a credential in Nexla

1. After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

2. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

3. Recurly V3 uses HTTP Basic Authentication, where your private API key is sent as the username. This key is securely transmitted over SSL/TLS with every API call. Enter your Recurly private API key in the Username Or API Key field. This is the same key you copied from Integrations > API Credentials in the Recurly Admin Console. The API key is used as the Basic Auth username—Recurly does not require a separate username.

4. The Password field is optional for Recurly V3. If your workflow or tooling requires a password value, you may leave it blank or enter any placeholder string; Recurly ignores the password when a valid API key is provided as the username.

   Recurly's V3 API requires the Accept: application/vnd.recurly.v2021-02-25 request header to specify the API version. This header is included automatically by the Nexla connector and does not need to be configured separately.

5. Click the Save button at the bottom of the overlay to save the configured credential. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.

Use as a data source

To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the Recurly connector tile, then select the credential that will be used to connect to the Recurly instance, and click Next; or, create a new Recurly credential for use in this flow.

Endpoint templates

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Recurly endpoints. Each template is designed specifically for the corresponding Recurly endpoint, making data source setup easy and efficient. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below.

Get Billing Info

This endpoint retrieves billing information for a specific Recurly account, including payment method details, billing address, and associated card or bank account data. Use this endpoint when you need to audit billing details, verify payment methods on file, or synchronize billing records with an external system.

• Enter the account code that identifies the Recurly account whose billing information you want to retrieve in the Account Code field. The account code is the unique identifier you assigned to the customer account when it was created in Recurly. You can find account codes in the Recurly Admin Console under Accounts, or by querying the Recurly API's list accounts endpoint.

• This endpoint makes a single GET request to the Recurly V3 API at https://v3.recurly.com/accounts/{account_code}/billing_info and returns the complete billing info object for the specified account, including details such as payment type, card last four digits, expiration date, and billing address.

Each Recurly account has a single billing info record. If you need billing data for multiple accounts, configure separate data sources for each account code, or use the manual configuration option to build a more complex multi-account ingestion flow. For additional details about the billing info object structure, see the Recurly API reference for Get Billing Info.

Get Unique Coupon Codes

This endpoint retrieves unique coupon codes generated for a specific bulk coupon in Recurly. Recurly allows you to create a bulk coupon and then generate a set of unique single-use codes from it. Use this endpoint to export those unique codes for distribution, reporting, or tracking purposes.

• Enter the coupon identifier for the parent bulk coupon in the Coupon Id field. This is the coupon code or ID of the bulk coupon from which unique codes were generated. You can find this value in the Recurly Admin Console under Coupons, or via the Recurly API's list coupons endpoint.

• This endpoint returns an array of unique coupon code objects. Each object includes the unique code string, its state (redeemable, maxed_out, or inactive), and the associated bulk coupon identifier.

Unique coupon codes are generated from a parent bulk coupon. Ensure the Coupon Id you enter refers to a bulk coupon (not a regular coupon), as only bulk coupons generate unique individual codes. For additional details, see the Recurly API reference for List Unique Coupon Codes.

List Unique Coupon Codes

This endpoint lists all unique coupon codes associated with a specific bulk coupon in Recurly. Use this endpoint when you need a complete inventory of unique codes for a given coupon campaign—for example, to audit code usage, track redemption status, or reconcile codes distributed externally.

• Enter the coupon identifier for the parent bulk coupon in the Coupon Id field. This is the coupon code or ID of the bulk coupon for which you want to list all unique codes. You can find this value in the Recurly Admin Console under Coupons, or via the Recurly API's list coupons endpoint.

• The endpoint returns an array of unique coupon code objects for the specified bulk coupon, including each code's current state and redemption details.

The Get Unique Coupon Codes and List Unique Coupon Codes templates both retrieve unique coupon codes for a bulk coupon. Both point to the same Recurly API operation—use either depending on which label is more meaningful for your use case. For additional details, see the Recurly API reference for List Unique Coupon Codes.

Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.

Manual configuration

Recurly data sources can also be manually configured to ingest data from any valid Recurly API endpoint, including endpoints not covered by the pre-built templates, chained API calls, or custom request parameters. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers.

All Recurly V3 API endpoints use the base URL https://v3.recurly.com/ followed by the resource path—for example, https://v3.recurly.com/accounts, /subscriptions, /invoices, /plans, or /coupons. Recurly's V3 API requires an Accept: application/vnd.recurly.v2021-02-25 header to specify the API version; the Nexla Recurly connector includes this header automatically. Recurly V3 list responses return a JSON object with a top-level data array containing the individual records, along with has_more and next pagination fields—set Path to Data in Response to $.data[*] to treat each element as a separate record. Date/time macros are useful for endpoints that accept range filters such as begin_time and end_time.

Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new Recurly data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.

Use as a destination

Click the + icon on the Nexset that will be sent to the Recurly destination, and select the Send to Destination option from the menu. Select the Recurly connector from the list of available destination connectors, then select the credential that will be used to connect to the Recurly organization, and click Next; or, create a new Recurly credential for use in this flow.

Endpoint templates

Nexla provides pre-built templates that can be used to rapidly configure destinations to send data to common Recurly endpoints. Each template is designed specifically for the corresponding Recurly endpoint, making destination setup easy and efficient. Select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.

Create Purchase Charge

This endpoint creates a new purchase in Recurly, which can include subscriptions, one-time charges, or a combination of both for an account. Use this template when you want to initiate a billing transaction—such as charging a customer for a new subscription or a standalone product—directly from your Nexla data flow. The Recurly Purchases API bundles account creation, subscription setup, and payment processing into a single consolidated API call.

• Prepare your Nexset data to match the Recurly purchase request body. Each record in the Nexset will be sent as the JSON body of a separate POST request to the Recurly Purchases endpoint. The request body must include a valid account object and at least one line item (subscription or adjustment). Key fields include:

  • account: An object containing the customer account details (e.g., account_code, email, billing_info).
  • subscriptions: An array of subscription objects, each specifying a plan_code and optional add-ons.
  • adjustments: An array of one-time charge objects if you are billing for non-subscription items.
  • currency: The three-letter ISO 4217 currency code (e.g., USD, EUR).
  • coupon_codes: An optional array of coupon codes to apply to the purchase.
• No additional template parameters are required beyond the record data—the endpoint URL is fixed at https://v3.recurly.com/purchases and the Nexla connector sends each record as the JSON request body automatically.

The Create Purchase endpoint is idempotent when you include a unique transaction_error_type or leverage Recurly's built-in duplicate transaction detection. Review your account's dunning settings to understand how failed purchases are handled. For complete request body schema details, see the Recurly API reference for Create Purchase.

Modify Subscription

This endpoint modifies an existing Recurly subscription by creating a pending subscription change. Use this template when you need to update subscription attributes—such as changing the plan, adjusting add-ons, updating quantity, or modifying billing details—for one or more subscriptions from your Nexla data flow. Changes are applied according to your Recurly account's configured change timing (immediately, at renewal, or at a specific date).

• Enter the subscription identifier for the subscription you want to modify in the Subscription Id field. This is the Recurly-generated UUID for the subscription (e.g., 37bfef9c6d3a4aa5a7e40da3ccd5b6da). You can find subscription IDs in the Recurly Admin Console under Subscriptions, or by querying the Recurly API's list subscriptions endpoint.

• Prepare your Nexset data to include the subscription change details in the request body. The record data will be sent as the JSON body of a POST request to the subscription change endpoint. Common fields include:

  • plan_code: The code of the new plan if you are changing the plan.
  • quantity: The updated subscription quantity.
  • add_ons: An array of add-on objects to update.
  • timeframe: When the change should take effect—now, renewal, or bill_date.

Only one pending subscription change can exist at a time for a given subscription. If a pending change already exists, the new change will replace it. To remove a pending change before it takes effect, use the Cancel Subscription Change endpoint. For complete request body schema details, see the Recurly API reference for Modify Subscription.

Cancel Subscription Change

This endpoint cancels a pending subscription change that has not yet taken effect. Use this template when you need to programmatically remove a queued plan change, quantity update, or add-on modification before it is applied at the next renewal or bill date.

• Enter the subscription identifier for the subscription whose pending change you want to cancel in the Subscription Id field. This is the Recurly-generated UUID for the subscription. You can find subscription IDs in the Recurly Admin Console under Subscriptions, or by querying the Recurly API's list subscriptions endpoint.
• No request body is required for this operation. The Nexla connector will send a POST request to the cancel subscription change endpoint using the specified subscription ID, and Recurly will remove any pending changes associated with that subscription.

Cancelling a subscription change removes only the pending future change—it does not cancel the subscription itself. The subscription will continue on its current plan and terms. For additional details, see the Recurly API reference for Cancel Subscription Change.

Create Coupon

This endpoint creates a new coupon in Recurly. Use this template when you want to programmatically generate discount coupons—such as for a marketing campaign, promotional pricing offer, or partner discount—directly from your Nexla data flow. Recurly supports fixed-amount, percentage, and free trial coupon types, and coupons can be applied to plans, add-ons, or entire orders.

• Prepare your Nexset data to match the Recurly coupon creation request body. Each record will be sent as the JSON body of a POST request to the Recurly coupons endpoint. Key required fields include:

  • coupon_code: A unique code for the coupon (e.g., SUMMER25). Must be alphanumeric and can include hyphens and underscores.
  • name: A descriptive name for the coupon (e.g., Summer 25% Off).
  • discount_type: The type of discount—percent, dollars, or free_trial.
  • discount_percent: Required when discount_type is percent; an integer between 1 and 100.
  • currencies: Required when discount_type is dollars; an array of objects specifying the discount amount per currency code.
  • duration: How long the discount applies—once, temporal, or forever.
• No additional template parameters are required—the endpoint URL is fixed at https://v3.recurly.com/coupons and the Nexla connector sends each record as the JSON request body automatically.

Coupon codes must be unique within your Recurly site. If you attempt to create a coupon with a code that already exists, the API will return an error. For complete request body schema details and available coupon options, see the Recurly API reference for Create Coupon.

Manual configuration

Recurly destinations can also be manually configured to send data to any valid Recurly API endpoint, including the ability to automatically send the response received from the Recurly API after each call to a new Nexla webhook data source. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, data format, endpoint URL, request headers, attribute exclusions, record batching, and response webhooks.

Recurly's V3 API accepts JSON format for all write operations. All Recurly V3 API endpoints use the base URL https://v3.recurly.com/ followed by the resource path—for example, https://v3.recurly.com/accounts, /subscriptions, /purchases, or /coupons—and for update operations on a specific resource, include the resource's ID at the end of the URL. Recurly's V3 API requires an Accept: application/vnd.recurly.v2021-02-25 header, which the Nexla Recurly connector includes automatically; Authorization headers are also handled automatically based on your credential configuration.

Save & activate

Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To send the data to the configured Recurly endpoint, open the destination resource menu, and select Activate.

The Nexset data will not be sent to Recurly until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.