Just as a carpenter would certainly choose a hammer to drive a nail, not the blunt end of a screwdriver, so too should a merchant use the correct tool to extract data from Recurly.

Today, a merchant has three different options for extracting data.

  • Listen for events in Recurly (via Webhooks)

  • Talk to the Recurly system (by querying the API)

  • Export data from Recurly (via Exports)

Webhooks

Webhooks are a push-based notification system. XML is POSTed to one or more HTTP endpoints which a merchant specifies. If a merchant wants to test against an authenticated endpoint, a username and password may be utilized as well. When data changes in Recurly, the webhook will be sent, then business logic performed. This near real-time communication method can also be helpful for syncing with reporting applications such as ChartMogul, automation tools like AutoPilot, or referral tracking software like Referral SaaSquatch.

Recurly offers over two dozen types of webhooks that a merchant can digest. Here, a merchant can see the New Subscription webhook.

New subscription notification code

This webhook contains information about the account, plan, and subscription. Quickly parsing it, a merchant can see what plan the customer signed up for, the amount they paid, and relevant details about the length of a trial and plan. A merchant can see the benefits of a push-based system and how this is an ideal candidate for keeping a merchant's systems and partner applications in sync with actions inside Recurly.

Querying the API

Querying the API is an excellent way to "talk" to Recurly about customers, transactions, subscriptions, plans, and more! By querying the RESTful API, a merchant will find it's easy to create, retrieve, update, and delete information inside of Recurly. An API call is an action triggered by a merchant, which allows the interaction of information and data in Recurly. By GETing a specific account, a merchant can gain insights about its attributes and related information. This can be helpful in syncing with a data warehouse, accounting systems/ERP, and reporting software. By PUTing to an account, a merchant can update attributes such as an account’s contact information, billing information, tax status, and more.

GETing an account is easy, as seen in the API call using our Ruby client library, below:

Curl update code

In the case of fetching a single account, a status code of 200 will be returned indicating that the request was successful. A merchant will encounter several different status codes when interacting with the API, and in broad strokes, can be handled as such: 200–299 as success, 400–499 as client request errors, and 500–599 as server errors.

Recurly rate limits API calls to 5,000 GET requests over a sliding five-minute window for production accounts. PUTs, POSTs, and DELETEs are not included in the rate limits, so a merchant need not worry that creating, updating, or destroying will be rate limited. To keep a merchant informed, headers are returned with each request stating the rate limit, number of requests remaining and an integer timestamp for when the current rate limit window will reset.

Rate limit code

PUTing to an account follows a RESTful pattern of an idempotent action. A merchant might want to update an account with new details about the customer's company.

Curl update code

When attempting to create or update data, validation errors may be presented in XML with an array of the validation errors and a 422 Unprocessable Entity status code.

XML error code

If a merchant is building a system that requires them to quickly pull up details about a specific resource in Recurly, querying the API is the way to go. A merchant can clearly see the benefits of making an API call that receives the relevant information immediately.

Exports

Retrieving a lot of information from Recurly at one time is where Exports really shine, as Exports are engineered specifically for extracting information in bulk about data in the application. Since no code is necessary to create an export, it's a simple way to quickly get a lot of information out of Recurly.

Exports are ideal for building reports, gaining business insights, and importing data to third-party systems. A merchant simply uses the UI to specify what resource they’d like to export and timeframe they’d like to scope results to. Recurly then presents a CSV file with the requested information.

Choosing the right tool

Whether a merchant needs to listen for events in Recurly (via Webhooks), talk to the Recurly system (by querying the API), or export data from Recurly (via Exports), each tool for data extraction is designed to efficiently complete a specific objective. Choosing the right tool for the task at hand will ensure that data and insights extracted from Recurly are produced in the most intelligent and meaningful manner. Download our PDF that summarizes the different options here.  Â