Content

Quickstart guide

This guide is intended to get you up and running with the Recurly API as quickly as possible using one of the official Recurly client libraries.

Estimated completion time

5 minutes

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.

Ruby

Node.js

Python

Java

Dotnet

PHP

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

Add to your Gemfile:

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 via npm:

npm install recurly --save

Or add directly to dependencies in package.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 the dotnet 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 the composer tool:

composer install recurly/recurly-client

Or manually add to your composer.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.

Ruby

Node.js

Python

Java

Dotnet

PHP

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 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.

Ruby

Node.js

Python

Java

Dotnet

PHP

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 using the Purchases endpoint.