Recurly Getting Started: Account Setup & First API Request (2026)

Getting started overview

Integrating with Recurly involves a sequence of steps designed to prepare your application for managing subscriptions and billing processes. This guide outlines the initial setup, from creating your Recurly account to executing your first API request. The primary goal is to establish a functional connection between your system and Recurly's platform, enabling programmatic control over subscription lifecycles, invoicing, and payment processing.

Recurly provides a RESTful API that allows developers to interact with its services using standard HTTP methods. For convenience, client libraries are available in several programming languages, including Ruby, Python, PHP, Java, and Node.js. These libraries abstract the HTTP request details, simplifying common operations.

Quick Reference: Recurly Getting Started Steps

Create an account and get keys

To begin using Recurly, you must first create an account and configure a "site." A site in Recurly represents an independent environment for your subscription business, allowing you to manage different brands or stages (e.g., development, staging, production) separately. After account creation, you will access the Recurly Admin Console to obtain your API credentials.

1. Sign Up for Recurly: Navigate to the Recurly signup page and complete the registration process. You will typically start with a trial account.
2. Create a Site: Upon logging into the Recurly Admin Console for the first time, you will be prompted to create your first site. Provide a name (e.g., "My Dev Site") and select your currency. You can manage multiple sites from your Recurly account.
3. Locate API Credentials:
   • From the Recurly Admin Console, go to Integrations > API Credentials.
   • You will find two primary types of API keys: the Private API Key and the Public API Key (also known as the API Key for Recurly.js).
   • The Private API Key is used for server-side operations and should be kept confidential. It grants full access to your Recurly account's data and functions.
   • The Public API Key is designed for client-side integrations, such as with Recurly.js, to securely collect payment information without sensitive data touching your servers directly.
   • Copy your Private API Key. This will be used for your first server-side API request.

For enhanced security, Recurly recommends creating separate API keys for different applications or environments and rotating them periodically. More information on API key management can be found in the Recurly API Keys documentation.

Your first request

Once you have your Private API Key, you can make your first API request. This example demonstrates fetching a list of available plans using the Recurly API. We'll show examples using curl for a direct HTTP request and the Node.js client library.

Using cURL (Direct HTTP Request)

For a direct HTTP request, you'll use basic authentication with your Private API Key as the username and an empty password.

curl -X GET \
  https://your-site.recurly.com/v2/plans \
  -u "YOUR_PRIVATE_API_KEY:" \
  -H "Accept: application/xml"

Replace your-site.recurly.com with your actual Recurly site subdomain (e.g., mysubscriptions.recurly.com) and YOUR_PRIVATE_API_KEY with the key you obtained from the Admin Console. The Accept: application/xml header specifies the desired response format, as Recurly's v2 API primarily uses XML.

Using Node.js Client Library

First, install the Recurly Node.js client library:

npm install recurly --save

Then, use the following JavaScript code to fetch plans:

const recurly = require('recurly');
const API_KEY = 'YOUR_PRIVATE_API_KEY';
const SITE_SUBDOMAIN = 'your-site'; // e.g., 'mysubscriptions'

// Initialize the Recurly client
const client = new recurly.Client(API_KEY, { site: SITE_SUBDOMAIN });

async function fetchPlans() {
  try {
    const { data: plans } = await client.listPlans();
    console.log('Successfully fetched plans:');
    plans.forEach(plan => {
      console.log(`- ${plan.name} (Code: ${plan.plan_code})`);
    });
  } catch (error) {
    console.error('Error fetching plans:', error);
  }
}

fetchPlans();

Replace YOUR_PRIVATE_API_KEY and your-site with your actual credentials. This script initializes the Recurly client with your API key and site subdomain, then calls listPlans() to retrieve the plan data.

Common next steps

After successfully making your first API call, consider these common next steps to further your Recurly integration:

• Create a Plan: Define your subscription products by creating plans in the Recurly Admin Console or via the API. Plans include details such as pricing, billing frequency, and trial periods. Refer to the Recurly Create a Plan guide.
• Create a Customer Account: Establish customer records within Recurly. These accounts will hold subscription information, billing history, and payment methods. The Recurly Create an Account documentation provides details.
• Subscribe a Customer: Link a customer account to a plan to initiate a subscription. This often involves collecting payment information securely using Recurly.js to tokenize card data before sending it to your server and then to Recurly.
• Webhooks: Implement webhooks to receive real-time notifications from Recurly about important events, such as subscription changes, successful payments, or failed invoices. This is crucial for keeping your system synchronized with Recurly. Consult Recurly's Webhooks documentation.
• Error Handling: Develop robust error handling for API responses. Recurly's API returns specific error codes and messages that can help diagnose issues. Good error handling improves the resilience of your integration. The Recurly Error Handling guide is a valuable resource.
• Explore Recurly.js: For client-side payment collection, investigate Recurly.js. This JavaScript library helps you remain PCI compliant by directly sending sensitive payment data to Recurly, bypassing your servers. For general information on PCI compliance, the PCI Security Standards Council website offers detailed resources.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• Incorrect API Key: Double-check that you are using the correct Private API Key. Ensure there are no leading or trailing spaces. The Private API Key is distinct from the Public API Key.
• Wrong Site Subdomain: Verify that the subdomain in your API endpoint (e.g., your-site.recurly.com) precisely matches the subdomain of your Recurly site. You can find this in your Recurly Admin Console URL or site settings.
• Authentication Format: For curl, ensure the -u "YOUR_PRIVATE_API_KEY:" format is used, with a colon and no password. For client libraries, ensure the API key is passed correctly during client initialization.
• Network Issues: Confirm that your network can reach recurly.com. Temporary network outages or firewall restrictions can prevent successful API calls.
• HTTP Status Codes: Pay attention to the HTTP status code returned in the API response:
  • 401 Unauthorized: Typically indicates an issue with your API key or authentication.
  • 404 Not Found: Often means the endpoint URL is incorrect or the resource doesn't exist.
  • 5xx Server Error: Suggests an issue on Recurly's side. Check the Recurly Status Page for any ongoing incidents.
• XML Parsing Errors: If you're directly parsing XML, ensure your XML parser is configured correctly to handle Recurly's response structure. Client libraries typically handle this for you.
• Refer to Documentation: The Recurly Developer Documentation is the authoritative source for API details, error codes, and examples. Review the specific endpoint documentation for any unique requirements.