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 queried state and the base state of a returned subscription may differ. For example, querying for past_due subscriptions will not result in a list of subscriptions with a 'past_due' state (they will either be 'active' or 'canceled'). Only base states ('pending', 'active', 'canceled', 'expired', 'future') will be present in the returned subscription records.

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_region>CA</tax_region>
    <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 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"
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") or ended (if state is "expired")
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_region Region where taxes are applied.
tax_rate Tax rate that will be applied to this subscription.
po_number PO number reference.
net_terms Invoice net terms in days.
collection_method Invoice collection as "automatic" or "manual".
subscription_add_ons Nested list of add-ons on the subscription, if applicable
pending_subscription Nested information about a pending subscription change at renewal
terms_and_conditions Optional notes field. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals.
customer_notes Optional notes field. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Customer Notes. Custom notes will stay with a subscription on all renewals.
bank_account_authorized_at Recurring subscriptions paid with ACH will have this attribute with an iso8601 timestamp value. This timestamp is used for alerting customers to reauthorize in 3 years in accordance with NACHA rules. If a subscription becomes inactive or the billing info is no longer a bank account, this timestamp is cleared and the attribute will not exist.
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_region>CA</tax_region>
  <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.
collection_method Optional field to set the collection for an invoice as "automatic" or "manual". The default is "automatic" if it's not set.
net_terms Integer representing the number of days after an invoice's creation that the invoice will become past due. If an invoice's net terms are set to '0', it is due 'On Receipt' and will become past due 24 hours after it’s created. If an invoice is due net 30, it will become past due at 31 days exactly. Defaults to '0'.
po_number Optional notes field. Attach a PO number to the invoice.
bulk Optional field to be used only when needing to bypass the 60 second limit on creating subscriptions. Should only be used when creating subscriptions in bulk from the API. Set to 'true' or 'false'. Defaults to 'false'.
terms_and_conditions Optional notes field. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals.
customer_notes Optional notes field. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Customer Notes. Custom notes will stay with a subscription on all renewals.
vat_reverse_charge_notes VAT Reverse Charge Notes only appear if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription. Specify custom notes with this tag to add or override VAT Reverse Charge Notes. Custom notes will stay with a subscription on all renewals.
bank_account_authorized_at Merchants importing recurring subscriptions paid with ACH into Recurly can backdate the subscription's authorization with this attribute using an iso8601 timestamp. This timestamp is used for alerting customers to reauthorize in 3 years in accordance with NACHA rules. If a subscription becomes inactive or the billing info is no longer a bank account, this timestamp is cleared.

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.

Creating an account simultaneously

To avoid paying multiple transaction fees, Recurly allows you to create a subscription, account and billing information in one API call. That way the billing information can be validated when charging for the subscription.

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. In the future, to change the coupon that is applied, you will have to remove this coupon from the corresponding account and redeem the new coupon.

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_region>CA</tax_region>
  <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',
  :customer_notes  => 'Thank you for your business!',
  :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();

Preview 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_region>CA</tax_region>
  <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 has been updated with new attributes
print "$subscription->tax_in_cents\n";
print "$subscription->cost_in_cents\n";
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();

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
collection_method Optional field to set the collection for an invoice as "automatic" or "manual". The default is "automatic" if it's not set.
net_terms Integer representing the number of days after an invoice's creation that the invoice will become past due. If an invoice's net terms are set to '0', it is due 'On Receipt' and will become past due 24 hours after it’s created. If an invoice is due net 30, it will become past due at 31 days exactly. Defaults to '0'.
po_number Optional notes field. Attach a PO number to the invoice.
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_region>CA</tax_region>
  <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>
  <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

Update subscription notes

Update a subscription's invoice notes before the next renewal. Updating notes will not trigger the renewal.

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

Parameters

Change Parameters Description
terms_and_conditions Optional notes field. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin, unless custom notes were created with the original subscription. Specify custom notes with this tag to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals, unless updated before renewal.
customer_notes Optional notes field. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin, unless custom notes were created with the original subscription. Specify custom notes with this tag to add or override Customer Notes. Custom notes will stay with a subscription on all renewals.
vat_reverse_charge_notes VAT Reverse Charge Notes only appear if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription. Specify custom notes with this tag to add or override VAT Reverse Charge Notes. Custom notes will stay with a subscription on all renewals.

Example

Request

Accept: application/xml
Content-Type: application/xml; charset=utf-8
<subscription>
 <terms_and_conditions>Payment can be sent to Acme Cloud, Inc.</terms_and_conditions>
 <customer_notes>Thanks for your business!</customer_notes>
 <vat_reverse_charge_notes>No VAT was applied on this invoice. Please reference this legislation.</vat_reverse_charge_notes>
</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>
  <terms_and_conditions>Payment can be sent to Acme Cloud, Inc.</terms_and_conditions>
  <customer_notes>Thanks for your business!</customer_notes>
  <vat_reverse_charge_notes>No VAT was applied on this invoice. Please reference this legislation.</vat_reverse_charge_notes>
  <tax_in_cents type="integer">80</tax_in_cents>
  <tax_type>usst</tax_type>
  <tax_region>CA</tax_region>
  <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.updateNotes(array(
    "customer_notes" => "New Customer Notes",
    "terms_and_conditions" => "New Terms",
    "vat_reverse_charge_notes" => "New VAT Notes"
  ));
subscription = Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')
subscription.update_notes(
  customer_notes: 'New Customer Notes',
  terms_and_conditions: 'New Terms',
  vat_reverse_charge_notes: 'New VAT Notes'
)
subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')
subscription.update_notes(customer_notes='New Customer Notes',
    terms_and_conditions='New Terms',
        vat_reverse_charge_notes='New VAT Notes')
Dictionary<string, string> notes = new Dictionary<string, string>();
var subscription = Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");

notes.Add("CustomerNotes", "New Customer Notes");
notes.Add("TermsAndConditions", "New T and C");
notes.Add("VatReverseChargeNotes", "New VAT Notes");

subscription.UpdateNotes(notes);

Preview 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
collection_method Optional field to set the collection for an invoice as "automatic" or "manual". The default is "automatic" if it's not set.
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

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" />
  <address>
      <address1>123 Main St</address1>
      <address2></address2>
      <city>San Francisco</city>
      <state>CA</state>
      <zip>12345</zip>
      <country>US</country>
      <phone></phone>
  </address>
  <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_region>CA</tax_region>
  <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_region>CA</tax_region>
    <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>
$subscription = Recurly_Subscription::get('44f83d7cba354d5b84812419f923ea96');
$subscription->unit_amount_in_cents = 1000;
$subscription->preview();
foreach ($subscription->invoice->line_items as $adjustment) {
  print_r($adjustment);
}
subscription = Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')
subscription.unit_amount_in_cents = 1000
subscription.preview
subscrtption.invoice.line_items.each do |line_item|
  puts line_item
end
subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')
subscription.unit_amount_in_cents = 1000
subscription.preview()

for line_item in sub.invoice.line_items:
    print line_item

Cancel 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 webhook. Recurly will send an additional subscription expired webhook once the subscription is no longer active.

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.

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();

Reactivate 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 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 subscription

For an active subscription, this will pause the subscription until the specified date. The subscription will not be prorated. For a subscription in a trial period, modifying the renewal date will modify when the trial expires.

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

Example

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