Metadata Description

Overview

This Quick Start Guide walks you through setting up your Recurly API integration in five steps:

Step 1: Obtain your private API key

Generate your private API key in Recurly’s Admin Dashboard under Integrations > API Keys. You’ll use this key to authenticate all API requests.

Step 2: Choose a client library

Recurly provides official client libraries for Ruby, Node.js, Python, Java, C#, and PHP. Pick one to simplify development and ensure compatibility.

Step 3: Create a client instance

In your chosen language, create a new Client object using your private API key. All API calls go through this client instance.

Step 4: Define a plan

Use the createPlan method to build subscription plans. Configure details like currency, price, and billing frequency.

Step 5: Verify in Recurly Admin

Prerequisites & limitations

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

Definition

Quick Start Guide: A high-level tutorial for connecting to Recurly’s API, authenticating with a private API key, and creating an initial subscription plan. This is the foundation for more advanced tasks like account creation, subscription management, and invoicing.

Step 1: Authentication keys

Recurly authenticates your API requests using your private API key. You can generate and retrieve private API keys in the Recurly Admin Dashboard.

Step 2: Choose a client library

Recurly offers a number of client libraries to integrate to the API. We suggest using
one of these official clients as it will make support, onboarding, and security much easier.

Check out the Ruby API docs,
or see the source on GitHub.

Add to yourGemfile:

gem 'recurly', '~> 4.0'

Or install from the command line:

gem install recurly

Check out the Js API docs,
or see the source on GitHub.

Install vianpm:

npm install recurly --save

Or add directly to dependencies inpackage.json:

{
  "recurly": "^4.0.0"
}

Check out the Python API docs,
or see the source on GitHub.

Add to your requirements.txt:

recurly~=4.0

Or install via pip

pip install --upgrade recurly

See the source on GitHub
and release details on Maven Central.

As a Maven dependency:

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

In Gradle:

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

See the source on GitHub.

Install via thedotnet tool:

dotnet add package Recurly --version 4.*

Or manually insert into your.csproj file:

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

See the source on GitHub.

Install via thecomposer tool:

composer install recurly/recurly-client

Or manually add to yourcomposer.json:

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

Step 3: Create a client instance

Your integration starts by creating an instance of the Client class. The client
represents a connection to Recurly's API. Every operation in the API exists as a method on this object. Creating a client only requires the private API key.

require 'recurly'
@client = Recurly::Client.new(
  api_key: '<your private api key>'
)

const recurly = require('recurly')
const client = new recurly.Client('<your private api key>')

import recurly
client = recurly.Client('<your private api key>')

// Put this import on the top of your file
import com.recurly.v3.Client;

final Client client = new Client("<your private api key>");

// Add this on the top of your file
using Recurly;

var client = new Recurly.Client("<your private api key>");

$client = new \Recurly\Client("<your private api key>");

Step 4: Create a plan

A plan tells Recurly how often and how much to charge your customers.
Plans can be created with free trials, optional products (called add-ons), setup fees, and more.

Plans are typically created in the admin interface if you only have a few offerings, but you can also create as many plans as you need through the API.

Let's create a hypothetical plan for a monthly coffee delivery product. The customer will
be charged $100 a month. It will use the unique identifier "coffee-monthly" to refer to this plan.

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)

// Put these imports on the top of your file
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());

// Add this on the top of your file
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 and finish

That's it! You can now view your newly created plan in the admin interface

Next steps

With a newly created plan at your disposal, it's time to start creating customer accounts, billing info, subscriptions and / or one time payments following our Purchases Guide.