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.

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

The plan must be set to bill at the End of the billing period and must include at least one add-on. The add-on is what the usage metrics will be linked to.

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.The Recurly setup details screen can be accessed a few ways, including:

Through Settings > Extensions

and then selecting install on the Recurly extension

Through the Billing Meters screen Edit Billing Providers dropdown

And through the Create New Billing Meter screen

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

In Recurly, a Webhook needs to be added so that Recurly can send subscription updates to Moesif. To do this you’ll need to make sure you are logged into your Recurly account. Once logged in, use the left-side menu to navigate to Integrations > Webhooks.

Once you’re on the Webhooks page click the Configure button in the top-right of the screen.

Then click New Endpoint button in the top-right of the screen.

On the New Endpoint screen, create a name for the endpoint, paste in the Webhook URL into the ENDPOINT URL field, and your Moesif Application ID into the HTTP AUTH USERNAME field. Leave the HTTP AUTH PASSWORD field blank.

These details can be found in Moesif by clicking the Edit Billing Provider dropdown on the Billing Meters screen or by going to Settings > Extensions > Recurly and clicking install.

Then click Save Changes. The Webhook should then be created and display on the Webhooks screen in Recurly.

Configuring the Recurly extension in Moesif

In Moesif, you will need to plug in the Recurly API details so that Moesif can post usage details to Recurly to bill upon. These details can be entered into the Recurly API Version and Recurly API Key fields on the Recurly Setup Details screen.

Currently, Moesif only supports v3 of the Recurly API.

The Recurly Private API Key can be found in Recurly by navigating to Recurly > Integrations > API Credentials.

Take the value listed under PRIVATE API KEY and paste it into the Recurly API Key field on the Recurly Setup Details screen.

Once completed, be sure to click Save.

Set the Id Mapping

The Id Mapping Configuration 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 Customers to Moesif User Objects. By default, this is customer.account_code, but can be changed to any field present on the Customer object in Recurly such as a Custom Field.

An example of how to do this is via Recurly metadata fields. For instance, both the Customer and Subscription objects have the ability to add Custom Fields. To add a Custom Field to the Customer or Subscription object, you can do it programmatically through the Recurly APIs or through the Recurly UI. When fields are added, you will be able to see them in the Recurly UI and retrieve them from the Recurly API.

Now, you’d want to make sure that the data you enter into the Custom Field match 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.

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.