# Integrate with Recurly

{% hint style="success" %}
**Note:** Our impact.com integration with Recurly is currently in beta. Should your experience not match the guide below, reach out to your CSM (or [contact support](https://app.impact.com/support/portal.ihtml?createTicket=true)).
{% endhint %}

Recurly is a subscription and billing platform that allows you to easily process recurring payments. B2B brands often run Performance programs to drive new subscription sign-ups and reward partners based on recurring payments from the sign-ups. The impact.com Recurly integration allows you to track those subscription sign-ups and reward your partners for them.

## Understand the integration limitations

impact.com only supports tracking *Subscription* events on Recurly.

The integration is also able to differentiate the first and recurring subscription events, but cannot differentiate between the recurring events. For example, the integration cannot differentiate between the second recurring billing and the fifth recurring billing.

## How it works

* On your website (or store), you'll implement a script that captures an impact.com Click ID (`im_ref`) value from the user's browser, then add it as a metadata property to the Recurly subscription record.
* You'll then generate read-only Recurly API credentials for impact.com to use.
* You'll create a custom field (`impact_click_id`) for Subscriptions.
* You'll provide Recurly API credentials for impact.com via our [partner integration portal](https://payments-integration.impact.com/), which will generate an Execution URL that you'll use to configure a webhook in Recurly.
* Once authenticated, the integration uses *Event Webhooks* to capture `successful_refund`, `successful_payment`, and `void_payment` events from Recurly and send them to your impact.com account

### Check before integrating

Before proceeding with the Recurly integration, ensure you have:

* Access to your impact.com account
* Admin access to your Recurly account
* Your impact.com account credentials ready
* A Performance program set up in impact.com

### Recurly Setup

Before we can integrate impact.com with Recurly, you'll need to complete these two steps in your Recurly account.

{% stepper %}
{% step %}

### Generate a Recurly API key

You will need to generate a private API key for impact.com to access the necessary data layer.

1. Navigate to your Recurly Dashboard, and from the left navigation bar, select **Integrations**.
2. Select **API Credentials**.
3. Select **Add Private API Key**.

<div data-with-frame="true"><figure><img src="/files/CFqrqONE5V5greNtEJ53" alt="" width="563"><figcaption></figcaption></figure></div>

4. Fill in the *API Key Information*.

* Add a meaningful (1) Key Name.
* Select (2) **Read-Only**.
* For the (3) *Application Using this Key* field, select **Other**.
* Enter (4) impact.com as the *Application Name*.

5. Select **Save Changes**.

<div data-with-frame="true"><figure><img src="/files/nXrvnisqqu51bQPA5HNH" alt="" width="563"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### Create a custom field

Create a custom field in Recurly for Subscriptions.

1. Navigate to your Recurly Dashboard, and from the left navigation bar, select **Configuration**.
2. Select **Custom Fields**.
3. Select **Create Your First Custom Field** or **Create Custom Field** if you already have existing custom fields.

<div data-with-frame="true"><figure><img src="/files/2NCo7Kxbp7jfpwSA1Ks4" alt="" width="563"><figcaption></figcaption></figure></div>

4. Fill in the *Custom Field Details*.

* In the *API Field Name* (1) field, enter `impact_click_id`.
* For the *Recurly Object* (2), select **Subscription**.
* For the (3) *Admin Console Field Name* field, enter `impact_click_id`.

<div data-with-frame="true"><figure><img src="/files/QLFW4OYbibd5yBAZ7OQ8" alt="" width="563"><figcaption></figcaption></figure></div>

5. Select **Create Custom Field**.
   {% endstep %}
   {% endstepper %}

## impact.com Integration Setup

{% stepper %}
{% step %}

### Configure the Recurly Integration

1. Navigate to the [**impact.com payments integration platform**](https://payments-integration.impact.com/), and select **Recurly**.
2. Log in with your impact.com **Account SID** and **Auth Token** as credentials.
   * See the *Account info cheat sheet* table below to learn how to access these credentials.
3. In the Recurly integration form, add your account information, including the **API Key** you created in Recurly above.
4. Select **Submit**. The form will populate the *Execution URL* field. Take note of this URL, we'll need it for the next step.

<div data-with-frame="true"><figure><img src="/files/eeUciDzXakkEPrDUzV0E" alt="" width="563"><figcaption></figcaption></figure></div>

### impact.com Account Info Cheat Sheet

Not sure what your account info is? Refer to the table below:

<table><thead><tr><th width="211.94140625">Field</th><th>Description</th></tr></thead><tbody><tr><td>Impact Account SID *</td><td>In the impact.com platform, from the top navigation bar, select <img src="/files/qPLiENtq33ewHc3tmEP4" alt=""> <strong>[User profile] → Settings →</strong> <a href="https://app.impact.com/secure/advertiser/api/fr/api-access-tokens-ui.ihtml"><strong>API</strong></a> and copy your Account SID.</td></tr><tr><td>Auth Token *</td><td>In the impact.com platform, from the top navigation bar, select <img src="/files/qPLiENtq33ewHc3tmEP4" alt=""> <strong>[User profile] → Settings →</strong> <a href="https://app.impact.com/secure/advertiser/api/fr/api-access-tokens-ui.ihtml"><strong>API</strong></a> and copy your Auth Token.</td></tr><tr><td>Program ID *</td><td><p>In the impact.com platform, select your brand name in the top-left corner. Your <strong>Program ID</strong> is the numerical value under the program name.</p><p></p><p><img src="https://files.readme.io/2edc9a646ec0744579c7d80854773dc742f408e01c48224be1fb9756c4d524f0-program_id.png" alt="Program ID screenshot"></p></td></tr><tr><td>Event Type ID *</td><td>In the impact.com platform, from the top navigation bar, select <img src="/files/qPLiENtq33ewHc3tmEP4" alt=""> <strong>[User profile] → Settings →</strong> <a href="https://app.impact.com/secure/advertiser/tracking-settings/actiontracker/view-actiontracker-flow.ihtml"><strong>Event Types</strong></a>. Copy the number in parenthesis next to the name of the event type.</td></tr><tr><td>Recurring Tracker ID*</td><td>In the impact.com platform, navigate to your <a href="https://help.impact.com/en/support/solutions/articles/155000000011-how-do-i-find-my-event-type-id-s-">Event Types</a>. This event type must be <a href="https://help.impact.com/en/support/solutions/articles/48001235457-modify-parent-child-event-types">linked as a child event</a> to your first subscription event type. For help with creating and linking event types, <a href="https://app.impact.com/support/portal.ihtml?createTicket=true">contact support</a>.</td></tr></tbody></table>
{% endstep %}

{% step %}

### Configure Recurly webhook

1. In Recurly, navigate to **Integrations → Webhooks**
2. Select **Configure**.

<div data-with-frame="true"><figure><img src="/files/zciM0QYMzTMYbxpFIGMj" alt="" width="563"><figcaption></figcaption></figure></div>

3. Select **New Endpoint**.
4. Fill in the endpoint details.
   * (1) **Endpoint Name** — enter a meaningful name of choice.
   * (2) **Endpoint URL**, copy and paste the *Execution URL* from the step above.
   * (3) Select **XML** as the format.

<div data-with-frame="true"><figure><img src="/files/ZPttZ8hhxhNz1nDGuBGW" alt="" width="563"><figcaption></figcaption></figure></div>

5. For notifications, select the following 3 events: `successful_refund`, `successful_payment`, and `void_payment`.

<div data-with-frame="true"><figure><img src="/files/N5qVlDKNTOJ7uQXOpjG9" alt="" width="462"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### Capture the Click ID and send it to Recurly

{% hint style="info" %}
**Suggested Instructions**

**Step 3** below is just a recommended method to get the `clickID` value into Recurly.

Feel free to implement an alternative approach that best fits your business needs.
{% endhint %}

#### 1. Implement UTT

impact.com needs to generate and capture `clickId` values for visitors to your store, a simple way to do this is to implement impact.com's UTT in your store. The UTT provides a series of functionality to simplify capturing and handling the `clickId`. To capture the `ClickId`, you must obtain your account’s UTT script from impact.com’s platform and set it up to load on every public page of your site. Follow the steps below to access your account UTT.

1. In impact.com, from the top navigation bar, select ![](/files/qPLiENtq33ewHc3tmEP4) **\[User profile] →** [**Settings**](https://app.impact.com/secure/advertiser/account-settings-flow.ihtml).
2. Select **General** under the *Tracking* section.

#### 2. Capture the `im_ref` and add it to the payment form

The UTT provides the `generateClickId` function that you can use to fetch the `im_ref` value required to be able to track conversions. Copy the full script tag below into your clipboard.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
<script>
  ire("generateClickId", callback);
</script>
```

{% endtab %}
{% endtabs %}

* Callback: Receives the captured `clickId` as a parameter and you can freely manipulate it to include it in Recurly's subscription payment form. You can then send this information to your backend for later processing.

The example below indicates how you could capture the `im_ref` using the UTT `generateClickId` function and set the value in a hidden field of a form on a field with id `impact_click_id` using jQuery.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
<script>
  ire("generateClickId", function (clickid) {
    $("#impact_click_id").val(clickid);
  });
</script>
```

{% endtab %}
{% endtabs %}

#### 3. Add the `im_ref` value to the custom field (`impact_click_id`) when subscriptions are created

When the subscription creation is being processed on your application backend, you can include the `im_ref`, captured in the previous step, in the `custom_fields` field of the subscription body before calling the Recurly API.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
<script>
  try {
    let subscriptionReq = {
      planCode: planCode,
      currency: "USD",
      account: {
        code: accountCode
      },
      custom_fields: [
        {
          name: "impact_click_id",
          value: impact_click_id
        }
      ]
    };
    let sub = await client.createSubscription(subscriptionReq);
    console.log("Created subscription: ", sub.uuid);
  } catch (err) {
    // ...
  }
</script>
```

{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}

### End-to-End Testing

Once the impact.com app is fully installed, you can begin end-to-end testing to ensure everything is working properly. Learn how to proceed with [End-to-End Testing](/integration-guides/end-to-end-tests.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://integrations.impact.com/integration-guides/for-brands/plugin-integrations/subscriptions-and-payments/integrate-with-recurly.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.