Recurly

Plans API

List plans

Lists all your active subscription plans.

GET https://:subdomain.recurly.com/v2/plans

Query Parameters

Parameter Default Description
cursor Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
per_page 50 Number of records to return per page, up to a maximum of 200.

Example

Status: 200 OK
Content-Type: application/xml; charset=utf-8
X-Records: 64
Link: <https://your-subdomain.recurly.com/v2/plans?cursor=1304958672>; rel="next"
ETag: "9220276b89e7b1a7eb6b750de3bf9fbc"
<?xml version="1.0" encoding="UTF-8"?>
<plans type="array">
  <plan href="https://your-subdomain.recurly.com/v2/plans/gold">
    <add_ons href="https://your-subdomain.recurly.com/v2/plans/gold/add_ons"/>
    <plan_code>gold</plan_code>
    <name>Gold plan</name>
    <description nil="nil"></description>
    <success_url nil="nil"></success_url>
    <cancel_url nil="nil"></cancel_url>
    <display_donation_amounts type="boolean">false</display_donation_amounts>
    <display_quantity type="boolean">false</display_quantity>
    <display_phone_number type="boolean">false</display_phone_number>
    <bypass_hosted_confirmation type="boolean">false</bypass_hosted_confirmation>
    <unit_name>unit</unit_name>
    <payment_page_tos_link nil="nil"></payment_page_tos_link>
    <plan_interval_length type="integer">1</plan_interval_length>
    <plan_interval_unit>months</plan_interval_unit>
    <trial_interval_length type="integer">0</trial_interval_length>
    <trial_interval_unit>days</trial_interval_unit>
    <accounting_code nil="nil"></accounting_code>
    <created_at type="datetime">2011-04-19T07:00:00Z</created_at>
    <unit_amount_in_cents>
      <USD type="integer">1000</USD>
      <EUR type="integer">800</EUR>
    </unit_amount_in_cents>
    <setup_fee_in_cents>
      <USD type="integer">6000</USD>
      <EUR type="integer">4500</EUR>
    </setup_fee_in_cents>
  </plan>
  <!-- Continued... -->
</plans>

$plans = Recurly_PlanList::get();
foreach ($plans as $plan) {
  print "Plan: $plan\n";
}
The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page. 
Recurly::Plan.find_each do |plan|
  puts "Plan: #{plan.inspect}"
end
The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page. 
#client version <= 2.1.5
plans = Plan.all()
while plans:
    for plan in plans:
        print 'Plan: %s' % plan
    try:
        plans = plans.next_page()
    except PageError:
        plans = ()

#client version 2.1.6+
for plan in Plan.all():
    print 'Plan: %s' % plan

Lookup plan details

Lookup a plan's details.

GET https://:subdomain.recurly.com/v2/plans/:plan_code

Example

Response

Status: 200 OK
Content-Type: application/xml; charset=utf-8
ETag: "937782009c7a198a1ee2659bf198e987"
<?xml version="1.0" encoding="UTF-8"?>
<plan href="https://your-subdomain.recurly.com/v2/plans/gold">
  <add_ons href="https://your-subdomain.recurly.com/v2/plans/gold/add_ons"/>
  <plan_code>gold</plan_code>
  <name>Gold plan</name>
  <description nil="nil"></description>
  <success_url nil="nil"></success_url>
  <cancel_url nil="nil"></cancel_url>
  <display_donation_amounts type="boolean">false</display_donation_amounts>
  <display_quantity type="boolean">false</display_quantity>
  <display_phone_number type="boolean">false</display_phone_number>
  <bypass_hosted_confirmation type="boolean">false</bypass_hosted_confirmation>
  <unit_name>unit</unit_name>
  <payment_page_tos_link nil="nil"></payment_page_tos_link>
  <plan_interval_length type="integer">1</plan_interval_length>
  <plan_interval_unit>months</plan_interval_unit>
  <trial_interval_length type="integer">0</trial_interval_length>
  <trial_interval_unit>days</trial_interval_unit>
  <accounting_code nil="nil"></accounting_code>
  <created_at type="datetime">2011-04-19T07:00:00Z</created_at>
  <unit_amount_in_cents>
    <USD type="integer">1000</USD>
    <EUR type="integer">800</EUR>
  </unit_amount_in_cents>
  <setup_fee_in_cents>
    <USD type="integer">6000</USD>
    <EUR type="integer">4500</EUR>
  </setup_fee_in_cents>
</plan>

try {
  $plan = Recurly_Plan::get('gold');
  print "Plan: $plan\n";
} catch (Recurly_NotFoundError $e) {
  print "Plan not found\n";
}

plan = Recurly::Plan.find('gold')

plan = Plan.get('gold')

Create plan

Create a new subscription plan.

POST https://:subdomain.recurly.com/v2/plans

Plan Attributes

Parameter Description
plan_code Unique code to identify the plan. This code may only contain the following characters: [a-z 0-9 @ - _ .]. Max of 50 characters. Required
name Plan name. Max of 255 characters. Required
description Optional plan description, not displayed
accounting_code Accounting code for related invoice line items, defaults to the plan_code. Max of 20 characters.
plan_interval_unit "days", or "months", defaults to "months"
plan_interval_length Plan interval length, defaults to 1
trial_interval_unit "days", or "months", defaults to "months"
trial_interval_length Defaults to zero, or no trial
setup_fee_in_cents Array of currency objects, see example below. Max 10000000.
unit_amount_in_cents Array of currency objects, see example below. Max 10000000. Required
total_billing_cycles Number of billing cycles before the plan stops renewing, defaults to null for continuous auto renewal
unit_name Unit description for the quantity, e.g. "users"
display_quantity Display the quantity field on the hosted payment page if true, defaults to false
success_url URL to redirect to after signup on the hosted payment pages
cancel_url URL to redirect to on canceled signup on the hosted payment pages

Example

Request

Accept: application/xml
Content-Type: application/xml; charset=utf-8
<plan>
  <plan_code>gold</plan_code>
  <name>Gold plan</name>
  <setup_fee_in_cents>
    <USD>1000</USD>
    <EUR>800</EUR>
  </setup_fee_in_cents>
  <unit_amount_in_cents>
    <USD>6000</USD>
    <EUR>4500</EUR>
  </unit_amount_in_cents>
  <plan_interval_length>1</plan_interval_length>
  <plan_interval_unit>months</plan_interval_unit>
</plan>

Response

Status: 201 Created
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<plan href="https://your-subdomain.recurly.com/v2/plans/gold">
  <add_ons href="https://your-subdomain.recurly.com/v2/plans/gold/add_ons"/>
  <plan_code>gold</plan_code>
  <name>Gold plan</name>
  <description nil="nil"></description>
  <success_url nil="nil"></success_url>
  <cancel_url nil="nil"></cancel_url>
  <display_donation_amounts type="boolean">false</display_donation_amounts>
  <display_quantity type="boolean">false</display_quantity>
  <display_phone_number type="boolean">false</display_phone_number>
  <bypass_hosted_confirmation type="boolean">false</bypass_hosted_confirmation>
  <unit_name>unit</unit_name>
  <payment_page_tos_link nil="nil"></payment_page_tos_link>
  <plan_interval_length type="integer">1</plan_interval_length>
  <plan_interval_unit>months</plan_interval_unit>
  <trial_interval_length type="integer">0</trial_interval_length>
  <trial_interval_unit>days</trial_interval_unit>
  <accounting_code nil="nil"></accounting_code>
  <created_at type="datetime">2011-04-19T07:00:00Z</created_at>
  <unit_amount_in_cents>
    <USD type="integer">1000</USD>
    <EUR type="integer">800</EUR>
  </unit_amount_in_cents>
  <setup_fee_in_cents>
    <USD type="integer">6000</USD>
    <EUR type="integer">4500</EUR>
  </setup_fee_in_cents>
</plan>

$plan = new Recurly_Plan();
$plan->plan_code = 'gold';
$plan->name = "Gold plan";
$plan->unit_amount_in_cents->addCurrency('USD', 1000); // USD 10.00 month
$plan->unit_amount_in_cents->addCurrency('EUR', 800);  // EUR 8.00 month
$plan->setup_fee_in_cents->addCurrency('USD', 6000); // USD 60.00 setup fee
$plan->setup_fee_in_cents->addCurrency('EUR', 4500); // EUR 45.00 setup fee
$plan->plan_interval_length = 1;
$plan->plan_interval_unit = 'months';
$plan->create();

plan = Recurly::Plan.create(
  :plan_code            => 'gold',
  :name                 => 'Gold plan',
  :unit_amount_in_cents => { 'USD' => 10_00, 'EUR' => 8_00 },
  :setup_fee_in_cents   => { 'USD' => 60_00, 'EUR' => 45_00 },
  :plan_interval_length => 1,
  :plan_interval_unit   => 'months'
)

plan = Plan(plan_code='gold', name='Gold plan')
plan.unit_amount_in_cents = Money(USD=1000, EUR=800)
plan.setup_fee_in_cents = Money(USD=6000, EUR=4500)
plan.plan_interval_length = 1
plan.plan_interval_unit = 'months'
plan.save()

Update plan

Update the pricing or details for a plan. Existing subscriptions will remain at the previous renewal amounts.

PUT https://:subdomain.recurly.com/v2/plans/:plan_code

Example

Request

Location: https://your-subdomain.recurly.com/v2/plans/gold
Accept: application/xml
Content-Type: application/xml; charset=utf-8
<plan>
  <setup_fee_in_cents>
    <USD>6000</USD>
    <EUR>5000</EUR>
  </setup_fee_in_cents>
</plan>

Response

Status: 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<plan href="https://your-subdomain.recurly.com/v2/plans/gold">
  <add_ons href="https://your-subdomain.recurly.com/v2/plans/gold/add_ons"/>
  <plan_code>gold</plan_code>
  <name>Gold plan</name>
  <description nil="nil"></description>
  <success_url nil="nil"></success_url>
  <cancel_url nil="nil"></cancel_url>
  <display_donation_amounts type="boolean">false</display_donation_amounts>
  <display_quantity type="boolean">false</display_quantity>
  <display_phone_number type="boolean">false</display_phone_number>
  <bypass_hosted_confirmation type="boolean">false</bypass_hosted_confirmation>
  <unit_name>unit</unit_name>
  <payment_page_tos_link nil="nil"></payment_page_tos_link>
  <plan_interval_length type="integer">1</plan_interval_length>
  <plan_interval_unit>months</plan_interval_unit>
  <trial_interval_length type="integer">0</trial_interval_length>
  <trial_interval_unit>days</trial_interval_unit>
  <accounting_code nil="nil"></accounting_code>
  <created_at type="datetime">2011-04-19T07:00:00Z</created_at>
  <unit_amount_in_cents>
    <USD type="integer">1000</USD>
    <EUR type="integer">800</EUR>
  </unit_amount_in_cents>
  <setup_fee_in_cents>
    <USD type="integer">6000</USD>
    <EUR type="integer">5000</EUR>
  </setup_fee_in_cents>
</plan>

$plan = Recurly_Plan::get('gold');
$plan->unit_amount_in_cents['EUR'] = 5000; // EUR 50.00 monthly fee
$plan->setup_fee_in_cents['EUR'] = 5000; // EUR 50.00 setup fee
$plan->update();

plan = Recurly::Plan.find('gold')
plan.setup_fee_in_cents['EUR'] = 50_00
plan.save

plan = Plan.get('gold')
plan.setup_fee_in_cents['EUR'] = 5000
plan.save()

Delete plan

Deleting a plan makes it inactive. New accounts cannot be created on the plan.

DELETE https://:subdomain.recurly.com/v2/plans/:plan_code

Example

$plan = Recurly_Plan::get('gold');
$plan->delete();

plan = Recurly::Plan.find('gold')
plan.destroy

plan = Plan.get('gold')
plan.delete()