Skip to main content

Recurly Data Source

The Recurly connector enables you to ingest subscription and billing data from your Recurly account into Nexla data flows. Use this connector to retrieve billing information, coupon codes, and other subscription-related data for reporting, analytics, and downstream processing. Follow the instructions below to create a new data flow that ingests data from a Recurly source in Nexla.
recurly_api.png

Recurly

Create a New Data Flow​

  1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

  2. Select the Recurly connector tile from the list of available connectors. 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.

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

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

Configure Using a Template​

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.

Endpoint Settings​

  • 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. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

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.

Endpoint Testing​

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually​

Recurly data sources can be manually configured to ingest data from any valid Recurly API endpoint. Manual configuration provides maximum flexibility for accessing endpoints not covered by pre-built templates or when you need custom API configurations.

With manual configuration, you can also create more complex Recurly sources, such as sources that use chained API calls to fetch data from multiple endpoints or sources that require custom request parameters.

API Method​

  1. To manually configure this source, 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. The most common method for retrieving data from Recurly is:

    • GET: For retrieving data such as accounts, subscriptions, billing info, invoices, plans, or coupons.

    Recurly's V3 API also supports POST, PUT, PATCH, and DELETE for write operations, though data source configurations most commonly use GET.

API Endpoint URL​

  1. Enter the URL of the Recurly API endpoint from which this source will fetch data in the Set API URL field. All Recurly V3 API endpoints use the base URL https://v3.recurly.com/ followed by the resource path.

    Examples of commonly used Recurly V3 source endpoints:

    • https://v3.recurly.com/accounts — List all accounts
    • https://v3.recurly.com/subscriptions — List all subscriptions
    • https://v3.recurly.com/invoices — List all invoices
    • https://v3.recurly.com/plans — List all plans
    • https://v3.recurly.com/coupons — List all coupons

Recurly's V3 API requires an Accept header set to application/vnd.recurly.v2021-02-25 to specify the API version. The Nexla Recurly connector includes this header automatically—you do not need to add it manually in the Request Headers field unless you are overriding the default behavior.

Date/Time Macros (API URL)​

Optional

Optionally, the API URL can be customized using macros—all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that can adapt to different time periods or data requirements.

Date/time macros are particularly useful when querying Recurly endpoints that accept date-range filter parameters, such as begin_time and end_time, which allow you to scope retrieved records to a specific time window on each ingestion run.

  1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

    • {now} – The current datetime
    • {now-1} – The datetime one time unit before the current datetime
    • {now+1} – The datetime one time unit after the current datetime
    • custom – Datetime macros can reference any number of time units before or after the current datetime—for example, enter (now-4) to indicate the datetime four time units before the current datetime

  2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. This format will be applied to the base datetime value of the macro—i.e., the value of {now} in {now-1}.

  3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu—for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)​

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic API endpoints that can adapt based on existing data.

Lookup-based macros are useful when, for example, you need to pass a list of account codes or subscription IDs retrieved from another Nexla source into Recurly API requests, enabling record-by-record or multi-entity data ingestion flows.

  1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

  2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data​

Optional

If only a subset of the data returned by the Recurly API endpoint is needed, you can designate the part(s) of the response that should be included in the Nexset(s) produced from this source by specifying the path to the relevant data within the response.

Recurly V3 API list responses typically return a JSON object with a data array containing the individual records, along with a has_more boolean and a next cursor for pagination. Specifying the correct path to the data array ensures that Nexla treats each element of the returned array as an individual record.

Path to Data is important for Recurly list responses. Without specifying the correct path (such as $.data[*]), Nexla may not properly parse the response into individual records.

  • To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

    • For responses in JSON format enter the JSON path that points to the object or array that should be treated as relevant data. JSON paths use dot notation (e.g., $.data[*] to access the array of records within a Recurly list response).
    Path to Data Example:

    For Recurly list endpoints (such as list accounts, list subscriptions, or list invoices), the response includes a top-level data array containing the individual records. Enter $.data[*] as the path to data to treat each element in the array as a separate record.

Autogenerate Path Suggestions​

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

  • To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

  • Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

    PathSuggestions.png

Metadata​

If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record.

For Recurly list responses, the has_more and next fields at the top level of the response are pagination metadata. If preserving this pagination context alongside each record is useful for your downstream processing, you can specify a path to these fields using the Metadata configuration.

Metadata paths are particularly useful for preserving Recurly response context like pagination cursors or response-level timestamps that apply to all records in the response.

  • To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

    • For responses in JSON format, enter the JSON path to the object or array that contains the metadata.

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this source, 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. Common headers like Authorization are also handled automatically by Nexla based on your credential configuration.

Endpoint Testing​

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source​

  1. Once all of the relevant steps in the above sections have been completed, 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.