Subscriptions API

List subscriptions

Returns a list of all the active 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"/>
    <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>
    <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

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 = 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.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 = ()

#client version 2.1.6+
account = Account.get('1')
for subscription in account.subscriptions():
    print 'Subscription: %s' % subscription

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
`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"/>
  <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>
  <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')

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"/>
  <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>
  <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('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()

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 Required
`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
`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"/>
  <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>
  <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()

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 = Subscription.find('44f83d7cba354d5b84812419f923ea96')
subscription.cancel

subscription = Subscription.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()

Terminate a subscription

You may remove any stored billing information for an account. If the account has a subscription, the renewal will go into past due unless you update the billing info before the renewal occurs.

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')

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