Skip to main content

Recurly Destination

Nexla's bi-directional connectors allow data to flow both to and from any location, making it simple to create a FlexFlow data flow that sends data to a Recurly location.
recurly_api.png

Recurly

Create a Recurly Destination​

  1. Click the + icon on the Nexset that will be sent to the Recurly destination, and select the Send to Destination option from the menu.

  2. 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.

  3. In Nexla, Recurly destinations can be created using pre-built endpoint templates, which expedite destination setup for common Recurly endpoints. Each template is designed specifically for the corresponding Recurly endpoint, making destination configuration easy and efficient.
    • To configure this destination using a template, follow the instructions in Configure Using a Template.

    Recurly destinations can also be configured manually, allowing you to send data to Recurly endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
    • To configure this destination manually, follow the instructions in Configure Manually.

Configure Using a Template​

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.

  • To configure this destination using a template, 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.

Configure Manually​

Recurly destinations can be manually configured to send data to any valid Recurly API endpoint.

Using manual configuration, you can also configure Nexla to automatically send the response received from the Recurly API after each call to a new Nexla webhook data source.

API Method​

  1. To manually configure this destination, select the Advanced tab at the top of the configuration screen.

  2. Select the API method that will be used for calls to the Recurly API from the Method pulldown menu. Common methods for Recurly write operations are:

    • POST: For creating new resources (accounts, subscriptions, purchases, invoices, coupons).
    • PUT: For replacing existing resource data.
    • PATCH: For partial updates to existing resources.
    • DELETE: For removing resources.

Data Format​

  1. Select the format in which the Nexset data will be sent to the Recurly API from the Content Format pulldown menu. Recurly's V3 API accepts JSON format for all write operations—select JSON to ensure Nexla formats the request body correctly.

API Endpoint URL​

  1. Enter the URL of the Recurly API endpoint to which you want to send the Nexset data in the URL field. All Recurly V3 API endpoints use the base URL https://v3.recurly.com/ followed by the resource path. For update operations on a specific resource, include the resource's ID at the end of the URL.

    Examples of commonly used Recurly V3 destination endpoints:

    • https://v3.recurly.com/accounts — Create a new account
    • https://v3.recurly.com/subscriptions — Create a new subscription
    • https://v3.recurly.com/purchases — Create a new purchase charge
    • https://v3.recurly.com/coupons — Create a new coupon

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this destination, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2).

    You do not need to include the Accept: application/vnd.recurly.v2021-02-25 header here—the Nexla Recurly connector includes this header automatically. Authorization headers are also handled automatically based on your credential configuration.

Exclude Attributes from the Call​

Optional

  • If any record attributes in the Nexset should be omitted when sending data to this Recurly destination, select the attributes from the Exclude Attributes pulldown menu.

  • Any number of attributes can be selected for exclusion, and all excluded attributes will be shown in the field. To remove an attribute from the list, click the X icon next to the attribute name.

Record Batching​

Optional

  1. If records should be sent to this destination in batched API calls, check the box next to Would you like to batch your records together? to enable record batching.

  2. Enter the maximum number of records that should be batched together in a single API call in the Batch Size field. By default, this value is set to 100.

  3. Select the algorithm that will be used to group records into batches from the Grouping Algorithm pulldown menu. The sample request shown in the panel on the right will be updated to reflect the current batching settings. Some algorithms require additional settings—click on an algorithm listed below to view instructions for configuring these settings.

Response Webhook​

Optional

Nexla can automatically send the response received from the Recurly API after each call to a new Nexla webhook data source. This option allows you to keep track of the status of each API call and any additional information returned after each call.

  • To enable this option, check the box next to Would you like to process the API response as a Nexla Webhook source?.

Sample Request Payload​

Sample request payloads containing a portion of the Nexset data that will be sent to the Recurly API endpoint based on the current settings are shown in the Sample Payload panel on the right. These samples can be referenced to ensure that the destination and request settings are correctly configured.

  • Click on a sample request payload to expand it and view the complete payload content.
  • Sample payloads are automatically updated with each setting change, making it easy to verify that changes achieve the desired effect.

Endpoint Testing (Manual Configuration)​

After all endpoint settings have been configured, Nexla can send a test payload to the Recurly API to ensure that the destination is configured correctly.

  1. To send a test payload, select the Test button at the top of the Sample Payload panel, and click on a listed sample payload to expand it.

  2. If any modifications to the sample payload are needed, make the necessary changes directly within the sample window.

  3. Click the Send Test Data button at the top of a sample payload to send the test payload to the Recurly API using the current settings.

Save & Activate the Destination​

  • 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.