Integrating with Recurly

This page assumes that you already have a Recurly account created and are able to create plans. To sign-up and create a Recurly account, visit the Recurly website.

How it works

A billing meter is created via the Moesif UI for a specific metric and filter criteria that you want to charge for.

  • The filter criteria defines what the meter should include such as specific endpoints, certain customers, or other filter criteria.
  • The metric is what is metered. It could be number of API calls, unique users, an aggregation on a header or body field, or any other metric trackable by Moesif.

Once the meter is created, Moesif will automatically meter the usage for each company and charge your customers via Recurly. Moesif billing meters support a variety of billing models including prepaid, postpaid, Pay As You Go (PAYG) and more. If you have different features or metrics you need to charge on, you can create multiple meters in Moesif, each linked to a different plan in Recurly. The integration also syncs subscription and revenue data from Recurly to Moesif so you can understand how API usage translates to revenue.

Example

Prerequisites

In order to integrate Recurly with Moesif, there are a few prerequisites which must be completed. These include:

  1. Creating an account with Recurly
  2. Creating a plan in Recurly
    • Include at least one add on in your Recurly Plan.
    • Configure your add-on to bill customers at the end of the billing cycle.
    • Configure your add-on to charge per unit of usage.

Configuring the Recurly integration

Moesif’s connection with Recurly involves 2-way communication. Moesif has created a simple way to get all the info you need and to configure certain variables for Recurly in a single screen. To access the Recurly setup details screen, follow one of these methods:

Access From Account Settings Menu

  1. Select your account icon to bring up the settings menu.
  2. Select Extensions.
  3. Search and select Recurly.

Access From Billing Meters Page

  1. Select Billing Meters in the navigation menu to open the Billing Meters screen.
  2. Select Edit Billing Providers dropdown
  3. Select Recurly.

Access From New Billing Meter Creation Page

  1. Select Billing Meters in the navigation menu to open the Billing Meters screen.
  2. Select + Add Billing Meter.
  3. Select Set up Recurly from the Select Billing Provider dropdown.

Once you’ve opened the configuration screen through one of the routes above, you can get the info needed to add the Moesif Webhook to Recurly, inputs to plug the Recurly API into Moesif, and customize your Customer ID source in a single place.

Adding the Moesif Webhook to Recurly

After logging into your Recurly account, follow these steps to add Moesif webhook endpoint to Recurly:

  1. Select Integrations and then select Webhooks in the navigation pane. Example

  2. In the Webhooks screen, select Manage Endpoints. Example
  3. In the Webhook Endpoints screen, select New Endpoint.
  4. In the New Endpoint screen, enter the endpoint details:
    • Enter a name for the endpoint,
    • Enter Moesif webhook URL in the ENDPOINT URL field and your Moesif Application ID in the HTTP AUTH USERNAME field. Leave the HTTP AUTH PASSWORD field blank. Remember that you can get these details from the Recurly configuration dialog in Moesif. Example
    • In the Notifications pane, select all notifications associated with account and subscription.
  5. Select Save Changes.

The webhook you’ve added appears in the Webhooks screen in Recurly. Example

Configuring the Recurly extension in Moesif

Next, you must add the Recurly API key to Moesif.

Moesif supports Recurly API version 3 or higher (v2019-10-10, v2021-02-25, or higher).

To add your Recurly API key to Moesif, follow these steps:

  1. Select Integrations and then select API Credentials in the navigation pane.
  2. Copy the API key from the PRIVATE API KEY field. Example
  3. Paste the API key in the Recurly API Key field of the Recurly configuration dialog in Moesif. Example

After you finish, select Save in the Recurly configuration dialog.

Set the Id Mapping

The Set Id Mapping section of the Recurly configuration dialog in Moesif enables you to specify the correct Recurly subscription field that contains the Moesif Company Id. Moesif will use this to link your Subscriptions in Recurly with Companies in Moesif. By default this is subscription.uuid, but you’ll likely need to modify this unless you use Recurly’s default subscription ids to identify customers on your API. Typically, this is a Custom Field added to the Recurly Subscription object like company_id or tenant_id.

Correct linking of Moesif companies to Recurly subscriptions is required for metered billing to function.

While not required, you can also link Recurly Customer Accounts to Moesif User Objects. By default, this is account.account_code, but you can chagne it to any field present on the Account object in Recurly such as a Custom Field.

Example

For example, both the Customer Account and Subscription objects have the ability to add Custom Fields. You can add a Custom Field programmatically through Recurly API or using the Recurly web UI. After adding Custom Fields, you will be able to see them in the Recurly UI and retrieve them from the Recurly API.

Example

Now, you’d want to make sure that the data you enter into the Custom Field matches whatever value you have in the Moesif UserId and/or CompanyId fields. Based on the Custom Fields above, we could map the values into Moesif by going to the Recurly configuration screen and changing the values in the Set Id Mapping fields to match.

Example

It’s important to remember that the values you see under the Moesif CompanyId and UserId should be what you are mapping to in Recurly through this configuration. This is how usage is synced for the user/company.

Linking a plan in Recurly to a billing meter

When creating a new billing meter, in the Link To section you can specify Recurly as the Billing Provider and then select the Plan and Add-on you’d like the usage to be linked to.

Example

Updated: