Quick-start guide

This guide walks you through your first Recurly API integration — generating an API key, installing a client library, creating a client instance, and defining your first subscription plan. By the end you'll have a working plan visible in the Recurly Admin Dashboard and be ready to start creating accounts and subscriptions.

1Prerequisites 2Integration guide

Prerequisites

A valid Recurly account with API access
Basic familiarity with RESTful APIs and JSON
A compatible programming environment: Ruby, Node.js, Python, Java, C#, or PHP

Integration guide

Step 1: Get your private API key

Recurly authenticates every API request using your private API key. Generate and manage your keys in the Recurly Admin Dashboard under Integrations > API Keys.

Keep your API key secret

Never embed your private API key in client-side code or commit it to version control. Always load it from an environment variable or secrets manager.

Step 2: Install the SDK

Install the Recurly client library for your language.

gem install recurly

npm install recurly --save

pip install --upgrade recurly

<dependency>
  <groupId>com.recurly.v3</groupId>
  <artifactId>api-client</artifactId>
  <version>4.4.0</version>
</dependency>

dotnet add package Recurly --version 4.*

composer install recurly/recurly-client

You can also declare the dependency in your project's config file:

gem 'recurly', '~> 4.0'

{
  "recurly": "^4.0.0"
}

recurly~=4.0

implementation 'com.recurly.v3:api-client:4.4.0'

<ItemGroup>
  <PackageReference Include="Recurly" Version="4.*" />
</ItemGroup>

{
  "require": {
    "recurly/recurly-client": "^4"
  }
}

For full docs and source, see the official client libraries: Ruby, Node.js, Python, Java (Maven), C#, PHP.

Step 3: Create a client instance

Every API operation is a method on the Client object. Create one instance per application using your private API key loaded from an environment variable.

require 'recurly'
@client = Recurly::Client.new(
  api_key: ENV['RECURLY_PRIVATE_KEY']
)

const recurly = require('recurly')
const client = new recurly.Client(process.env.RECURLY_PRIVATE_KEY)

import recurly
client = recurly.Client(os.environ['RECURLY_PRIVATE_KEY'])

import com.recurly.v3.Client;

final Client client = new Client(System.getenv("RECURLY_PRIVATE_KEY"));

using Recurly;

var client = new Recurly.Client(Environment.GetEnvironmentVariable("RECURLY_PRIVATE_KEY"));

$client = new \Recurly\Client(getenv('RECURLY_PRIVATE_KEY'));

Step 4: Create a plan

A plan defines how often and how much Recurly charges your customers. Plans support free trials, setup fees, add-ons, and more. You can create plans in the Admin Dashboard or via the API.

The example below creates a monthly coffee delivery plan priced at $100/month with the unique identifier coffee-monthly.

plan_create = {
  code: "coffee-monthly",
  name: "Monthly Coffee Subscription",
  currencies: [
    {
      currency: "USD",
      unit_amount: 100
    }
  ]
}
plan = @client.create_plan(body: plan_create)
puts "Created Plan #{plan}"

const planCreate = {
  code: 'coffee-monthly',
  name: 'Monthly Coffee Subscription',
  currencies: [
    {
      currency: 'USD',
      unitAmount: 100
    }
  ]
}
const plan = await client.createPlan(planCreate)
console.log('Created Plan: ', plan.code)

plan_create = {
    "code": 'coffee-monthly',
    "name": "Monthly Coffee Subscription",
    "currencies": [{
        "currency": "USD",
        "unit_amount": 100
    }],
}
plan = client.create_plan(plan_create)
print("Created Plan %s" % plan)

import com.recurly.v3.requests.PlanCreate;
import com.recurly.v3.requests.PlanPricing;
import com.recurly.v3.resources.Plan;
import java.util.ArrayList;
import java.util.List;

PlanCreate planCreate = new PlanCreate();
planCreate.setCode("coffee-monthly");
planCreate.setName("Monthly Coffee Subscription");

List<PlanPricing> currencies = new ArrayList<>();
PlanPricing planPrice = new PlanPricing();
planPrice.setCurrency("USD");
planPrice.setUnitAmount(100.0f);
currencies.add(planPrice);
planCreate.setCurrencies(currencies);

Plan plan = client.createPlan(planCreate);
System.out.println("Created Plan " + plan.getCode());

using Recurly.Resources;
using System.Collections.Generic;

var planReq = new PlanCreate()
{
    Code = "coffee-monthly",
    Name = "Monthly Coffee Subscription",
    Currencies = new List<PlanPricing>() {
        new PlanPricing() {
            Currency = "USD",
            UnitAmount = 100
        }
    }
};
Plan plan = client.CreatePlan(planReq);
Console.WriteLine($"Created plan {plan.Code}");

$plan_create = array(
    "name" => "Monthly Coffee Subscription",
    "code" => $plan_code,
    "currencies" => [
        array(
            "currency" => "USD",
            "unit_amount" => 100
        )
    ]
);

$plan = $client->createPlan($plan_create);

echo 'Created Plan:' . PHP_EOL;
var_dump($plan);

Step 5: Verify in the Admin Dashboard

Log in to the Recurly Admin Dashboard and confirm your new plan appears under Plans. That's it — your integration is working.

With a plan in place, you're ready to create customer accounts, attach billing info, and process subscriptions or one-time payments. Follow the Purchases guide to continue.

Updated about 9 hours ago