Integrate with Recurly

⚠️

Note: Integrating with Recurly is in beta

Our impact.com integration with Recurly is currently in beta. Should your experience not match the guide below, please reach out to your CSM (or contact support).

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 (irclickid) 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, 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

impact.com will complete several integration steps on your behalf. Check with your implementation engineer to ensure that the following configuration steps have been completed: Event Type, Gateway Tracking, General Tracking.

Recurly Setup

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

Step 1: 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.
  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.

Step 2: 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.
  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.
  5. Select Create Custom Field.

impact.com Integration Setup

Step 1: Configure the Recurly Integration

  1. Navigate to the impact.com payments integration platform, 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.

    • See the Account info cheat sheet table below to learn how to access these credentials.
  4. Select Submit. The form will populate the Execution Url field. Take note of this URL, we'll need it for the next step.

📘

impact.com Account Info Cheat Sheet

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

Required infoDescription
Account SIDIn impact.com, navigate to ⋮ [Menu] → Settings → [API](https://app.impact.com/secure/advertiser/accountSettings/techintegration/adv-wsapi-table-flow.ihtml) to find your Account SID. Copy the full case-sensitive value.
Auth TokenIn impact.com, navigate to ⋮ [Menu] → Settings → [API](https://app.impact.com/secure/advertiser/accountSettings/techintegration/adv-wsapi-table-flow.ihtml) to find your Account SID. Copy the full case-sensitive value.
Program IDEnter your impact.com Program ID value. In impact.com, select your brand name in the top left-corner. Your Program ID is shown in gray type under your Program name in the Program column.
Event Type IDYour impact.com Event tracking identifier that will track the first subscription event. In impact.com, navigate to ⋮ [Menu] → Settings → [Event Types](https://app.impact.com/secure/advertiser/tracking-settings/actiontracker/view-actiontracker-flow.ihtml). For help with creating and linking event types, contact support.
Recurring Tracker IDYour impact.com recurring subscription Event tracking identifier. In impact.com, navigate to ⋮ [Menu] → Settings → [Event Types](https://app.impact.com/secure/advertiser/tracking-settings/actiontracker/view-actiontracker-flow.ihtml). This event type must be linked as a child event to your first subscription event type. For help with creating and linking event types, contact support.

Step 2: Configure Recurly webhook

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

  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.
  5. For notifications, select the following 3 events: successful_refund, successful_payment, and void_payment.

Step 3: Capture the Click ID and send it to Recurly

📘

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.

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 that would ease you into 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 left navigation, select   [Menu]Settings.
  2. Select General under the Tracking section

2. Capture the irclickid and add it to the payment form

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

ire(‘generateClickId’, callback);
  • 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 irclickid 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.

ire(‘generateClickId’, function (clickid) {
  $(‘#impact_click_id’).val(clickid);
});

3. Add the irclickid 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 irclickid, captured in the previous step, in the custom_fields field of the subscription body before calling the Recurly API.

# javascript
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(subscriptionRed);
  console.log(‘Created subscription: ‘, sub.uuid);
} catch (err) {
   // ...
}