Recurly

Subscriptions API

Table of Contents

List subscriptions

Returns a list of all the subscriptions.

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

Query Parameters

Parameter Default Description
state live The state of subscriptions to return: "active", "canceled", "expired", "future", "in_trial", "live", or "past_due". A subscription will belong to more than one state.
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.

Subscription Query States

active
Subscriptions that are valid for the current time. This includes subscriptions in a trial period
canceled
Subscriptions that are valid for the current time but will not renew because a cancelation was requested
expired
Subscriptions that have expired and are no longer valid
future
Subscriptions that will start in the future, they are not active yet
in_trial
Subscriptions that are active or canceled and are in a trial period
live
All subscriptions that are not expired
past_due
Subscriptions that are active or canceled and have a past-due invoice

Please note: a subscription may belong to multiple states. For example, a subscription may be active and in a trial.

Example

Status: 200 OK
Content-Type: application/xml; charset=utf-8
X-Records: 123
Link: <https://your-subdomain.recurly.com/v2/subscriptions?cursor=1304958672>; rel="next"
ETag: "0172c6c72335c9346256a5c483bf3066"
<?xml version="1.0" encoding="UTF-8"?>
<subscriptions type="array">
  <subscription href="https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96">
    <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
    <invoice href="https://your-subdomain.recurly.com/v2/invoices/1108"/>
    <plan href="https://your-subdomain.recurly.com/v2/plans/gold">
      <plan_code>gold</plan_code>
      <name>Gold plan</name>
    </plan>
    <uuid>44f83d7cba354d5b84812419f923ea96</uuid>
    <state>active</state>
    <unit_amount_in_cents type="integer">800</unit_amount_in_cents>
    <currency>EUR</currency>
    <quantity type="integer">1</quantity>
    <activated_at type="datetime">2011-05-27T07:00:00Z</activated_at>
    <canceled_at nil="nil"></canceled_at>
    <expires_at nil="nil"></expires_at>
    <current_period_started_at type="datetime">2011-06-27T07:00:00Z</current_period_started_at>
    <current_period_ends_at type="datetime">2010-07-27T07:00:00Z</current_period_ends_at>
    <trial_started_at nil="nil"></trial_started_at>
    <trial_ends_at nil="nil"></trial_ends_at>
    <tax_in_cents type="integer">72</tax_in_cents>
    <tax_type>usst</tax_type>
    <tax_rate type="float">0.0875</tax_rate>
    <po_number nil="nil"></po_number>
    <net_terms type="integer">0</net_terms>
    <subscription_add_ons type="array">
    </subscription_add_ons>
    <a name="cancel" href="https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/cancel" method="put"/>
    <a name="terminate" href="https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/terminate" method="put"/>
    <a name="postpone" href="https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/postpone" method="put"/>
  </subscription>
  <!-- Continued... -->
</subscriptions>
$subscriptions = Recurly_SubscriptionList::getActive();
foreach ($subscriptions as $subscription) {
  print "Subscription: $subscription\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::Subscription.find_each do |subscription|
  puts "Susbcription: #{subscription}"
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
subscriptions = Subscription.all()
while subscriptions:
    for subscription in subscriptions:
        print 'Subscription: %s' % subscription
    try:
        subscriptions = subscriptions.next_page()
    except PageError:
        subscriptions = ()

#client version 2.1.6+
for subscription in Subscription.all():
    print 'Subscription: %s' % subscription
using System.Linq;

var account = Accounts.Get("1");
var subscriptions = account.GetSubscriptions();
while (subscriptions.Any())
{
	foreach (var subscription in subscriptions)
		Console.WriteLine("Subscription: " + subscription);
	subscriptions = subscriptions.Next;
}

List an account's subscriptions

Returns a list of subscriptions for an account.

GET https://:subdomain.recurly.com/v2/accounts/:account_code/subscriptions

Example

$subscriptions = Recurly_SubscriptionList::getForAccount('1');
foreach ($subscriptions as $subscription) {
  print "Subscription: $subscription\n";
}
The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page.
account = Recurly::Account.find('1')
account.subscriptions.find_each do |subscription|
  puts "Subscription: #{subscription.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.6+
account = Account.get('1')
for subscription in account.subscriptions():
    print 'Subscription: %s' % subscription

#client version <= 2.1.5
account = Account.get('1')
subscriptions = account.subscriptions()
while subscriptions:
    for subscription in subscriptions:
        print 'Subscription: %s' % subscription
    try:
        subscriptions = subscriptions.next_page()
    except PageError:
        subscriptions = ()
using System.Linq;

var account = Accounts.Get("1");
var subscriptions = account.GetSubscriptions();
while (subscriptions.Any())
{
  foreach (var subscription in subscriptions)
    Console.WriteLine("Subscription: " + subscription);
  subscriptions = subscriptions.Next;
}

Lookup subscription details

Lookup a subscription's details.

GET https://:subdomain.recurly.com/v2/subscriptions/:uuid

Subscription Attributes

Subscription Parameters Description
plan Nested plan_code and plan name
uuid Unique subscription ID
state "active", "canceled", "future", "expired", "modified"
unit_amount_in_cents Unit amount of the subscription
quantity Number of units
currency 3-letter ISO currency for the subscription
activated_at Date the subscription started
canceled_at Date the subscription was marked canceled
expires_at Date the subscription will end (if state is "canceled"), ended (if state is "expired"), or was modified (if state is "modified")
current_period_started_at Date the current bill cycle started
current_period_ends_at Date the current bill cycle will end
trial_started_at Date the trial was started, if applicable
trial_ends_at Date the trial ended, if applicable
tax_in_cents Amount of tax or VAT within the transaction, in cents.
tax_type Tax type as "vat" for VAT or "usst" for US Sales Tax.
tax_rate Tax rate that will be applied to this subscription.
po_number PO number reference.
net_terms Invoice net terms in days.
subscription_add_ons Nested list of add-ons on the subscription, if applicable
pending_subscription Nested information about a pending subscription change at renewal
Subscription Parameters Description
plan Nested information about the new plan
unit_amount_in_cents New subscription's unit amount in cents
quantity New subscription quantity
subscription_add_ons Nested list of add-ons

Pending subscription changes

When looking up a subscription that has pending changes, the new subscription details will be in a pending_subscription node. Since immediate subscription changes take place immediately, pending subscription changes will only show for changes occurring when the subscription renews.

Example

Response

Status: 200 OK
Content-Type: application/xml; charset=utf-8
ETag: "937782009c7a198a1ee2659bf198e987"
<?xml version="1.0" encoding="UTF-8"?>
<subscription href="https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <invoice href="https://your-subdomain.recurly.com/v2/invoices/1108"/>
  <plan href="https://your-subdomain.recurly.com/v2/plans/gold">
    <plan_code>gold</plan_code>
    <name>Gold plan</name>
  </plan>
  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>
  <state>active</state>
  <unit_amount_in_cents type="integer">800</unit_amount_in_cents>
  <currency>EUR</currency>
  <quantity type="integer">1</quantity>
  <activated_at type="datetime">2011-05-27T07:00:00Z</activated_at>
  <canceled_at nil="nil"></canceled_at>
  <expires_at nil="nil"></expires_at>
  <current_period_started_at type="datetime">2011-06-27T07:00:00Z</current_period_started_at>
  <current_period_ends_at type="datetime">2010-07-27T07:00:00Z</current_period_ends_at>
  <trial_started_at nil="nil"></trial_started_at>
  <trial_ends_at nil="nil"></trial_ends_at>
  <tax_in_cents type="integer">80</tax_in_cents>
  <tax_type>usst</tax_type>
  <tax_rate type="float">0.0875</tax_rate>
  <po_number nil="nil"></po_number>
  <net_terms type="integer">0</net_terms>
  <subscription_add_ons type="array">
  </subscription_add_ons>
  <a name="cancel" href="https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/cancel" method="put"/>
  <a name="terminate" href="https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/terminate" method="put"/>
  <a name="postpone" href="https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/postpone" method="put"/>
</subscription>
$subscription = Recurly_Subscription::get('44f83d7cba354d5b84812419f923ea96');
subscription = Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')
subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')
var subscription = Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");

Create subscription

Create a new subscription.

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

Subscription Attributes

Subscription Parameters Description
plan_code Plan code for the subscription Required
account Nested account attributes Required
subscription_add_ons Nested add-ons
coupon_code Optional coupon code to apply to the new subscription. Please note, the subscription request will fail if the coupon is invalid
unit_amount_in_cents Override the unit amount of the subscription plan by setting this value in cents. If not provided, the subscription will inherit the price from the subscription plan for the provided currency. Max 10000000.
currency Currency for the subscription Required
quantity Optionally override the default quantity of 1
trial_ends_at If set, overrides the default trial behavior for the subscription. This must be a date and time, preferably in UTC. The date must be in the future.
starts_at If set, the subscription will begin in the future on this date. The subscription will apply the setup fee and trial period, unless the plan has no trial.
total_billing_cycles Renews the subscription for a specified number of cycles, then automatically cancels. Defaults to the subscription renewing indefinitely.
first_renewal_date Indicates a date at which the first renewal should occur. Subsequent renewals will be offset from this date. The first invoice will be prorated appropriately so that the customer only pays for the portion of the first billing period for which the subscription applies. Useful for forcing a subscription to renew on the first of the month.

Subscription starts date

If you would like the subscription to start on a specified date, please set the trial_ends_at parameter in your API request. Recurly will ignore any trial period currently specified on the plan and begin charging the subscription on the date specified. This is useful for creating your own, custom trial intervals and for importing existing subscriptions from an external system.

Using stored billing info

You may create a subscription without specifying billing information if an account already has stored billing information.

Redeeming a coupon

You may optionally pass a coupon_code with the subscription request. The subscription will only be created if the coupon code is valid for the given plan.

Example

Request

Accept: application/xml
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<subscription>
  <plan_code>gold</plan_code>
  <currency>EUR</currency>
  <account>
    <account_code>1</account_code>
    <email>verena@example.com</email>
    <first_name>Verena</first_name>
    <last_name>Example</last_name>
    <billing_info>
      <number>4111-1111-1111-1111</number>
      <month>1</month>
      <year>2014</year>
    </billing_info>
  </account>
</subscription>

Response

Status: 201 Created
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<subscription href="https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <invoice href="https://your-subdomain.recurly.com/v2/invoices/1108"/>
  <plan href="https://your-subdomain.recurly.com/v2/plans/gold">
    <plan_code>gold</plan_code>
    <name>Gold plan</name>
  </plan>
  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>
  <state>active</state>
  <unit_amount_in_cents type="integer">800</unit_amount_in_cents>
  <currency>EUR</currency>
  <quantity type="integer">1</quantity>
  <activated_at type="datetime">2011-05-27T07:00:00Z</activated_at>
  <canceled_at nil="nil"></canceled_at>
  <expires_at nil="nil"></expires_at>
  <current_period_started_at type="datetime">2011-06-27T07:00:00Z</current_period_started_at>
  <current_period_ends_at type="datetime">2010-07-27T07:00:00Z</current_period_ends_at>
  <trial_started_at nil="nil"></trial_started_at>
  <trial_ends_at nil="nil"></trial_ends_at>
  <tax_in_cents type="integer">80</tax_in_cents>
  <tax_type>usst</tax_type>
  <tax_rate type="float">0.0875</tax_rate>
  <po_number nil="nil"></po_number>
  <net_terms type="integer">0</net_terms>
  <subscription_add_ons type="array">
  </subscription_add_ons>
  <a name="cancel" href="https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/cancel" method="put"/>
  <a name="terminate" href="https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/terminate" method="put"/>
</subscription>
$subscription = new Recurly_Subscription();
$subscription->plan_code = 'gold';
$subscription->currency = 'EUR';

$account = new Recurly_Account();
$account->account_code = '1';
$account->email = 'verena@example.com';
$account->first_name = 'Verena';
$account->last_name = 'Example';

$billing_info = new Recurly_BillingInfo();
$billing_info->number = '4111-1111-1111-1111';
$billing_info->month = 1;
$billing_info->year = 2014;

$account->billing_info = $billing_info;
$subscription->account = $account;

$subscription->create();
subscription = Recurly::Subscription.create(
  :plan_code => 'gold',
  :currency  => 'EUR',
  :account   => {
    :account_code => '1',
    :email        => 'verena@example.com',
    :first_name   => 'Verena',
    :last_name    => 'Example',
    :billing_info => {
      :number => '4111-1111-1111-1111',
      :month  => 1,
      :year   => 2014,
    }
  }
)
subscription = Subscription()
subscription.plan_code = 'gold'
subscription.currency = 'EUR'

account = Account(account_code='1')
account.email = 'verena@example.com'
account.first_name = 'Verena'
account.last_name = 'Example'

billing_info = BillingInfo()
billing_info.number = '4111-1111-1111-1111'
billing_info.month = 1
billing_info.year = 2014

account.billing_info = billing_info
subscription.account = account

subscription.save()
var account = Accounts.Get("1"); // Account contains BillingInfo
var plan = Plans.Get("gold");
var subscription = new Subscription(account, plan, "USD"); // account, plan, currency
subscription.Create();

Update subscription

Request an update to a subscription that takes place immediately or at renewal.

PUT https://:subdomain.recurly.com/v2/subscriptions/:uuid

Parameters

Change Parameters Description
timeframe "now" for immediate, "renewal" to perform when the subscription renews. defaults to "now" if not specified
plan_code New plan, remains unchanged if not specified
quantity New quantity, remains unchanged if not specified and the plan_code remains the same
unit_amount_in_cents New unit amount in cents
subscription_add_ons Nested add-on information for the subscription, the new subscription will have no add-ons unless specified
Add-on Parameters Description
add_on_code Add-on code, required if making an add-on change
quantity Quantity of add-on, defaults to 1
unit_amount_in_cents Unit amount for the add-on, specify to override the add-ons default unit amount

Timeframe

The timeframe parameter controls when the upgrade or downgrade takes place. The subscription change can occur now or when the subscription renews. Generally, if you're performing an upgrade, you will want the change to occur immediately (now). If you're performing a downgrade, you should set the timeframe to "renewal" so the change takes affect at the end of the current billing cycle.

Add-ons

The original subscription's add-ons will be removed unless they are specified in your update subscription request. Please specify all the add-ons that should be present after the subscription change.

Example

Request

Accept: application/xml
Content-Type: application/xml; charset=utf-8
<subscription>
  <timeframe>now</timeframe>
  <quantity>2</quantity>
  <subscription_add_ons>
    <subscription_add_on>
      <add_on_code>ipaddresses</add_on_code>
      <quantity>10</quantity>
      <unit_amount_in_cents>150</unit_amount_in_cents>
    </subscription_add_on>
  </subscription_add_ons>
</subscription>

Response

Status: 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<subscription href="https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <invoice href="https://your-subdomain.recurly.com/v2/invoices/1108"/>
  <plan href="https://your-subdomain.recurly.com/v2/plans/gold">
    <plan_code>gold</plan_code>
    <name>Gold plan</name>
  </plan>
  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>
  <state>active</state>
  <unit_amount_in_cents type="integer">800</unit_amount_in_cents>
  <currency>EUR</currency>
  <quantity type="integer">1</quantity>
  <activated_at type="datetime">2011-05-27T07:00:00Z</activated_at>
  <canceled_at nil="nil"></canceled_at>
  <expires_at nil="nil"></expires_at>
  <current_period_started_at type="datetime">2011-06-27T07:00:00Z</current_period_started_at>
  <current_period_ends_at type="datetime">2010-07-27T07:00:00Z</current_period_ends_at>
  <tax_in_cents type="integer">80</tax_in_cents>
  <tax_type>usst</tax_type>
  <tax_rate type="float">0.0875</tax_rate>
  <po_number nil="nil"></po_number>
  <net_terms type="integer">0</net_terms>
  <trial_started_at nil="nil"></trial_started_at>
  <trial_ends_at nil="nil"></trial_ends_at>
  <subscription_add_ons type="array">
    <subscription_add_on>
      <add_on_code>ipaddresses</add_on_code>
      <quantity>10</quantity>
      <unit_amount_in_cents>150</unit_amount_in_cents>
    </subscription_add_on>
  </subscription_add_ons>
  <a name="cancel" href="https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/cancel" method="put"/>
  <a name="terminate" href="https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/terminate" method="put"/>
</subscription>
$subscription = Recurly_Subscription::get('44f83d7cba354d5b84812419f923ea96');
$subscription->plan_code = 'silver';
$subscription->quantity = 2;
$subscription->updateImmediately();     // Update immediately.
// or $subscription->updateAtRenewal(); // Update when the subscription renews.
subscription = Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')
subscription.update_attributes(
  :plan_code => 'silver',
  :quantity  => 2,
  :timeframe => 'now'       # Update immediately.
  # :timeframe => 'renewal' # Update when the subscription renews.
)
subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')
subscription.plan_code = 'silver'
subscription.quantity = 2
subscription.timeframe = 'now'       # Update immediately.
# subscription.timeframe = 'renewal' # Update when the subscription renews.
subscription.save()
var subscription = Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");
subscription.Plan = Plans.Get("silver");
subscription.Quantity = 2;

// perform the update operation
subscription.ChangeSubscription(Subscription.ChangeTimeframe.Now);

// You might also use Subscription.ChangeTimeframe.Renewal

Preview a subscription change

Returns a preview for a subscription change applied to an account without committing a subscription change or posting an invoice.

POST https://subdomain.recurly.com/v2/subscriptions/:uuid/preview

If the original subscription is in trial, or the timeframe parameter is set to renewal, then no invoice array will be returned.

Paramters

Change Parameters Description
timeframe Set as either "now" for immediate, "renewal" to perform when the subscription renews. defaults to "now" if not specified.
plan_code New plan, remains unchanged if not specified.
quantity New quantity, remains unchanged if not specified and the plan_code remains the same.
unit_amount_in_cents New unit amount in cents
subscription_add_ons Nested add-on information for the subscription, the new subscription will have no add-ons unless specified.
Add-on Parameters Description
Add-on Quantity Add-on code, required if making an add-on change.
Quantity Quantity of add-on, defaults to 1.
unit_amount_in_cents Unit amount for the add-on, specify to override the add-ons default unit amount.

Example

Request

Accept: application/xml
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<subscription>
  <timeframe>now</timeframe>
  <plan_code>gold</plan_code>
  <quantity>2</quantity>   
  <subscription_add_ons>     
    <subscription_add_on>       
      <add_on_code>ipaddresses</add_on_code>       
      <quantity>10</quantity>
      <unit_amount_in_cents>150</unit_amount_in_cents>
    </subscription_add_on>
  </subscription_add_ons>
</subscription>

Response

Status: 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://your-subdomain.recurly.com/v2/accounts/1
<?xml version="1.0" encoding="UTF-8"?> 
<subscription href="">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1" />   
  <plan href="https://your-subdomain.recurly.com/v2/plans/gold">       
    <plan_code>gold</plan_code>     
    <name>Gold plan</name>   
  </plan>   
  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>   
  <state>pending</state>  
  <cost_in_cents>3379</cost_in_cents> 
  <unit_amount_in_cents type="integer">800</unit_amount_in_cents>     
  <currency>USD</currency>   
  <quantity type="integer">2</quantity>   
  <activated_at type="datetime">2011-05-27T07:00:00Z</activated_at>    
  <canceled_at nil="nil"></canceled_at>   
  <expires_at nil="nil"></expires_at>   
  <current_period_started_at type="datetime">2011-06-27T07:00:00Z</current_period_started_at>   
  <current_period_ends_at type="datetime">2010-07-27T07:00:00Z</current_period_ends_at>   
  <trial_started_at nil="nil"></trial_started_at>   
  <trial_ends_at nil="nil"></trial_ends_at>   
  <tax_in_cents type="integer">279</tax_in_cents>   
  <tax_type>usst</tax_type>   
  <tax_rate type="float">0.09</tax_rate>   
  <po_number nil="nil"></po_number>   
  <net_terms type="integer">0</net_terms>   
  <collection_method>automatic</collection_method>   
  <subscription_add_ons type="array">   
    <subscription_add_on>       
      <add_on_code>ipaddresses</add_on_code>       
      <quantity>10</quantity>
      <unit_amount_in_cents>150</unit_amount_in_cents>
    </subscription_add_on>
  </subscription_add_ons> 
  <invoice>
    <account href="https://your-subdomain.recurly.com/v2/accounts/1" />
    <subscription href="https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96" />
    <uuid>421f7b7d414e4c6792938e7c49d552e9</uuid>
    <state>open</state>
    <invoice_number nil="nil"><invoice_number>
    <po_number nil="nil"></po_number>
    <vat_number nil="nil"></vat_number>
    <subtotal_in_cents type="integer">9900</subtotal_in_cents>
    <tax_in_cents type="integer">0</tax_in_cents>
    <total_in_cents type="integer">9900</total_in_cents>
    <currency>USD</currency>
    <created_at type="datetime">2011-08-25T12:00:00Z</created_at>
    <closed_at nil="nil"></closed_at>
    <tax_type>usst</tax_type>
    <tax_rate type="float">0.09</tax_rate>
    <net_terms type="integer">0</net_terms>
    <collection_method>automatic</collection_method>
    <redemption href="https://your-subdomain.recurly.com/v2/invoices/e3f0a9e084a2468480d00ee61b090d4d/redemption"/>
    <line_items type="array">
      <adjustment>
        <!-- Detail. Includes proration amounts if applicable -->
      </adjustment>
    </line_items>
    <transactions nil="nil”></transactions>
  </invoice>
</subscription>

Cancel a subscription

Cancel a subscription so it remains active and then expires at the end of the current bill cycle.

PUT https://:subdomain.recurly.com/v2/subscriptions/:uuid/cancel

Canceling a subscription turns off the subscription's auto-renewal. The subscription will continue through the current, invoiced term. When the subscription is up for renewal, the account will transition to a free account and the subscription will no longer be active.

When a subscription is canceled, Recurly will send a cancelation push notification. Recurly will send an additional subscription expired push notification once the subscription is no longer active.

Example

$subscription = Recurly_Subscription::get('44f83d7cba354d5b84812419f923ea96');
$subscription->cancel();
subscription = Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')
subscription.cancel
subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')
subscription.cancel()
var subscription = Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");
subscription.Cancel();

Please note: If a subscription that is set to start in the future is canceled, the subscription will be deleted from the account and will not show up in the account's subscription list.

Reactivating a canceled subscription

Reactivate a canceled subscription so it renews at the end of the current bill cycle.

PUT https://:subdomain.recurly.com/v2/subscriptions/:uuid/reactivate

When a subscription is canceled, it will not renew. It is considered active until the end of the current billing period. Then, the subscription will end. To renew the subscription without modifying it, simply send a reactivation request to this end point.

Example

$subscription = Recurly_Subscription::get('44f83d7cba354d5b84812419f923ea96');
$subscription->reactivate();
subscription = Subscription.find('44f83d7cba354d5b84812419f923ea96')
subscription.reactivate
subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')
subscription.reactivate()
var subscription = Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");
subscription.Reactivate();

Terminate a subscription

You can terminate any active subscription immediately. You also have the option to grant a full or partial refund to the account.

PUT https://:subdomain.recurly.com/v2/subscriptions/:uuid/terminate?refund=:refund_type

Refund Type

partial
Prorates a refund based on the amount of time remaining in the current bill cycle.
full
Performs a full refund of the last charge for the current subscription term.
none
Terminates the subscription without a refund.

Please note: When terminating with a full or partial refund, the request may fail if Recurly is unable to find an appropriate transaction to refund.

Please use the Transactions API to refund a specific transaction or a specific amount.

Example

$subscription = Recurly_Subscription::get('44f83d7cba354d5b84812419f923ea96');
$subscription->terminateWithoutRefund();
subscription = Subscription.find('44f83d7cba354d5b84812419f923ea96')
subscription.terminate :partial
subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')
subscription.terminate(refund='partial')
var subscription = Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");
subscription.Terminate(Subscription.RefundType.Full);
//subscription.Terminate(Subscription.RefundType.Partial);
//subscription.Terminate(Subscription.RefundType.None);

Postpone a subscription

PUT https://:subdomain.recurly.com/v2/subscriptions/:uuid/postpone?next_renewal_date=:next_renewal_date

Example

$subscription = Recurly_Subscription::get('44f83d7cba354d5b84812419f923ea96');
$subscription->postpone(date('c', strtotime('2012-12-31Z')));
subscription = Subscription.find('44f83d7cba354d5b84812419f923ea96')
subscription.postpone Time.utc(2012, 12, 31)
subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')
subscription.postpone(next_renewal_date=datetime.datetime(2012, 12, 31))
var subscription = Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");
subscription.Postpone(new DateTime(2012, 12, 31));

Preview a subscription

Returns a preview for a new subscription applied to an account.

POST https://:subdomain.recurly.com/v2/subscriptions/preview

Example

Request

Accept: application/xml
Content-Type: application/xml; charset=utf-8
<subscription>
  <plan_code>gold</plan_code>
  <currency>USD</currency>
  <account>
    <account_code>1</account_code>
    <email>verena@example.com</email>
    <first_name>verena</first_name>
    <last_name>example</last_name>
  </account>
</subscription>

Response

Status: 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://your-subdomain.recurly.com/v2/accounts/1
<?xml version="1.0" encoding="UTF-8"?>
<subscription href="">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1" />
  <plan href="https://you-subdomain.recurly.com/v2/plans/gold">
    <plan_code>gold</plan_code>
    <name>Gold plan</name>
  </plan>
  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>
  <state>pending</state>
  <unit_amount_in_cents type="integer">800</unit_amount_in_cents>
  <currency>USD</currency>
  <quantity type="integer">1</quantity>
  <activated_at type="datetime">2011-05-27T07:00:00Z</activated_at>
  <canceled_at nil="nil"></canceled_at>
  <expires_at nil="nil"></expires_at>
  <current_period_started_at type="datetime">2011-06-27T07:00:00Z</current_period_started_at>
  <current_period_ends_at type="datetime">2010-07-27T07:00:00Z</current_period_ends_at>
  <trial_started_at nil="nil"></trial_started_at>
  <trial_ends_at nil="nil"></trial_ends_at>
  <tax_in_cents type="integer">72</tax_in_cents>
  <tax_type>usst</tax_type>
  <tax_rate type="float">0.0875</tax_rate>
  <po_number nil="nil"></po_number>
  <net_terms type="integer">0</net_terms>
  <collection_method>automatic</collection_method>
  <subscription_add_ons type="array">
  </subscription_add_ons>
</subscription>
$subscription = new Recurly_Subscription();
$subscription->plan_code = 'gold';
$subscription->currency = 'EUR';

$account = new Recurly_Account();
$account->account_code = '1';
$account->email = 'verena@example.com';
$account->first_name = 'Verena';
$account->last_name = 'Example';

$billing_info = new Recurly_BillingInfo();
$billing_info->number = '4111-1111-1111-1111';
$billing_info->month = 1;
$billing_info->year = 2014;

$account->billing_info = $billing_info;
$subscription->account = $account;

$subscription->preview();
subscription = Recurly::Subscription.preview(
  plan_code: 'gold',
  currency: 'EUR',
  account: {
    account_code: '1',
    email: 'verena@example.com',
    first_name: 'Verena',
    last_name: 'Example',
    billing_info: {
      number: '4111-1111-1111-1111',
      month: 1,
      year: 2014,
    }
  }
)
subscription = Subscription()
subscription.plan_code = 'gold'
subscription.currency = 'EUR'

account = Account(account_code='1')
account.email = 'verena@example.com'
account.first_name = 'Verena'
account.last_name = 'Example'

billing_info = BillingInfo()
billing_info.number = '4111-1111-1111-1111'
billing_info.month = 1
billing_info.year = 2014

account.billing_info = billing_info
subscription.account = account

subscription.preview()
var account = Accounts.Get("1");
var plan = Plans.Get("gold");
var subscription = new Subscription(account, plan, "USD"); // account, plan, currency
subscription.Preview();