API: Subscription Changes

Recurly makes it easy to modify a subscription. When you request a change to a subscription, you may specify if the change should take place immediately or when the subscription renews.

Modifying an existing Subscription

Changing a subscription can update the subscription's plan, price, quantity, or add ons.

Please see the Upgrades and Downgrades information for more about the logic we use to modify an account's current subscription.

PUT/v2/subscriptions/:id

Parameters

timeframe
Required. Please specify "now" or "renewal" to delay the change until the subscription renews.
plan_code
If specified, change the subscription plan
quantity
Optionally changes the quantity on the subscription
unit_amount_in_cents
Optionally override the unit amount in cents of the subscription plan
add_ons
If provided, explicitly define all the add-ons for the subscription.
add_on_code
Unique add on code to identify the add-on
quantity
Optionally override the default quantity of 1
unit_amount_in_cents
Optionally override the default price of the add-on

Timeframe

The timeframe parameter controls when the upgrade or downgrade takes place. The subscription chance 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.

Please see the Upgrades and Downgrades information for more about the logic we use to modify an account's current subscription.

Plan Code, Quantity, and Unit Amount

Values not specified will be not be changed.

If the subscription plan changes, the unit amount will default to the new plan's unit amount. Of course, you are welcome to override the plan's unit amount by specifying it in the change request. If you change the subscription plan but do not specify a quantity, the new subscription will use the same quantity as the previous subscription.

Add-ons

Any add ons included in the subscription change request will be applied to the new subscription. The original subscription's add ons will not be carried over to the new subscription automatically.

Request

Status: 200 OK
Content-Type: application/xml; charset=utf-8

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<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_on>
      <add_on_code>dns-hosting</add_on_code>
    </subscription_add_on>
  </subscription_add_ons>
</subscription>

Look up a subscription with pending changes

When looking up a subscription that has pending changes, the new subscripion details will be in a pending_subscription node. Since immediate subscription changes take place immediately, pending subscription changes will only show for changes occuring at the subscription renewal.

GET/v2/subscriptions/:id

Pending subscription parameters

plan
Specifies the new plan
unit_amount_in_cents
Unit amount in cents after the change
quantity
Quantity of the subscription after the change
add_ons
The complete list of addons after the change

Response

Status: 200 OK
Content-Type: application/xml; charset=utf-8
ETag: "17e9af50489ec928feda798be95f02ee"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
<?xml version="1.0" encoding="UTF-8"?>
<subscription href="https://api.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96">
  <account href="https://api.recurly.com/v2/accounts/verena"/>
  <plan href="https://api.recurly.com/v2/plans/silver">
    <plan_code>silver</plan_code>
    <name>Silver Plan</name>
  </plan>
  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>
  <state>active</state>
  <unit_amount_in_cents type="integer">1000</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>
  <pending_subscription type="subscription">
    <plan href="https://api.recurly.com/v2/plans/gold">
      <plan_code>gold</plan_code>
      <name>Gold Plan</name>
    </plan>
    <unit_amount_in_cents type="integer">2000</unit_amount_in_cents>
    <quantity type="integer">1</quantity>
    <subscription_add_ons type="array">
      <subscription_add_on>
        <add_on_code>extra-gold</add_on_code>
        <unit_amount_in_cents type="integer">500</unit_amount_in_cents>
        <quantity type="integer">2</quantity>
      </subscription_add_on>
    </subscription_add_ons>
  </pending_subscription>
  <a name="cancel" href="https://api.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/cancel" method="put"/>
  <a name="terminate" href="https://api.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/terminate" method="put"/>
</subscription>