Recurly

Plan Add-ons API

Table of Contents

List add-ons for a plan

Returns a list of all the add-ons for a plan.

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

Query Parameters

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

Example

Status: 200 OK
Content-Type: application/xml; charset=utf-8
X-Records: 5
ETag: "a4b0568a2278bc591ceb64b31547eb78"
<?xml version="1.0" encoding="UTF-8"?>
<add_ons type="array">
  <add_on href="https://your-subdomain.recurly.com/v2/plans/gold/add_ons/ipaddresses">
    <plan href="https://your-subdomain.recurly.com/v2/plans/gold"/>
    <add_on_code>ipaddresses</add_on_code>
    <name>IP Addresses</name>
    <display_quantity_on_hosted_page type="boolean">false</display_quantity_on_hosted_page>
    <default_quantity type="integer">1</default_quantity>
    <unit_amount_in_cents>
      <USD>200</USD>
    </unit_amount_in_cents>
    <created_at type="datetime">2011-06-28T12:34:56Z</created_at>
  </add_on>
  <!-- Continued... -->
</add_ons>
$plan = Recurly_Plan::get('gold');
$add_ons = $plan->add_ons->get();
// Or, in 1 API request:
// $add_ons = Recurly_AddonsList::get('gold');
foreach ($add_ons as $add_on) {
  print "Add-on: $add_on\n";
}
The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page.
plan = Recurly::Plan.find('gold')
plan.add_ons.find_each do |add_on|
  puts "Add-on: #{add_on.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
plan = Plan.get('gold')
add_ons = plan.add_ons()
while add_ons:
    for add_on in add_ons:
        print 'Add-on: %s' % add_on
    try:
        add_ons = add_ons.next_page()
    except PageError:
        add_ons = ()

#client version 2.1.6+
plan = Plan.get('gold')
for plan in plan.add_ons():
    print 'Add-on: %s' % add_on

Lookup an add-on

Returns information about an add-on.

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

Attributes

Attribute Description
add_on_code Add On Code
name Add-on name
unit_amount_in_cents Array of unit amounts for currencies
default_quantity Default quantity for the hosted pages, defaults to 1
display_quantity_on_hosted_page If true, display a quantity field on the hosted pages for the addon
created_at Date the add-on was created

Example

Status: 200 OK
Content-Type: application/xml; charset=utf-8
ETag: "a81253e90a4f16089b951028675c58d2"
<?xml version="1.0" encoding="UTF-8"?>
<add_on href="https://your-subdomain.recurly.com/v2/plans/gold/add_ons/ipaddresses">
  <plan href="https://your-subdomain.recurly.com/v2/plans/gold"/>
  <add_on_code>ipaddresses</add_on_code>
  <name>IP Addresses</name>
  <display_quantity_on_hosted_page type="boolean">false</display_quantity_on_hosted_page>
  <default_quantity type="integer">1</default_quantity>
  <unit_amount_in_cents>
    <USD type="integer">200</USD>
  </unit_amount_in_cents>
  <created_at type="datetime">2011-06-28T12:34:56Z</created_at>
</add_on>

Create an add-on

Add an add-on to a plan.

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

Attributes

Attribute Description
add_on_code Add On Code. Max of 50 characters.
name Add-on name. Max of 255 characters.
unit_amount_in_cents Array of unit amounts for currencies. Max 10000000.
default_quantity Default quantity for the hosted pages, defaults to 1
display_quantity_on_hosted_page If true, display a quantity field on the hosted pages for the add-on
accounting_code Accounting code for invoice line items for the add-on, defaults to add_on_code. Max of 20 characters.

Example

Request

Location: https://your-subdomain.recurly.com/v2/plans/gold/add_ons
Accept-Type: application/xml
Content-Type: application/xml; charset=utf-8
<add_on>
  <add_on_code>ipaddresses</add_on_code>
  <name>Extra IP Addresses</name>
  <unit_amount_in_cents>
    <USD>200</USD>
  </unit_amount_in_cents>
</add_on>

Response

Status: 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://your-subdomain.recurly.com/v2/plans/gold/add_ons/ipaddresses
<?xml version="1.0" encoding="UTF-8"?>
<add_on href="https://your-subdomain.recurly.com/v2/plans/gold/add_ons/ipaddresses">
  <plan href="https://your-subdomain.recurly.com/v2/plans/gold"/>
  <add_on_code>ipaddresses</add_on_code>
  <name>Extra IP Addresses</name>
  <display_quantity_on_hosted_page type="boolean">false</display_quantity_on_hosted_page>
  <default_quantity type="integer">1</default_quantity>
  <unit_amount_in_cents>
    <USD type="integer">200</USD>
  </unit_amount_in_cents>
  <created_at type="datetime">2011-06-28T12:34:56Z</created_at>
</add_on>
$addon = new Recurly_Addon();
$addon->plan_code = 'gold';
$addon->add_on_code = 'ipaddresses';
$addon->name = 'Extra IP Addresses';
$addon->unit_amount_in_cents->addCurrency('USD', 200);
$addon->create();
plan = Recurly::Plan.find('gold')
add_on = plan.add_ons.create(
  :add_on_code          => 'ipaddresses',
  :name                 => 'Extra IP Addresses',
  :unit_amount_in_cents => 2_00
)
plan = Plan.get('gold')
addon = AddOn(
  add_on_code='ipaddresses',
  name='Extra IP Addresses',
  unit_amount_in_cents=200
)
plan.create_add_on(addon)

Update an add-on

Update the pricing information or description for an add-on. Subscriptions who have already subscribed to the add-on will not receive the new pricing.

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

Example

Request

Location: https://your-subdomain.recurly.com/v2/plans/gold/add_ons/ipaddresses
Accept-Type: application/xml
Content-Type: application/xml; charset=utf-8
<add_on>
  <unit_amount_in_cents>
    <USD>1200</USD>
  </unit_amount_in_cents>
</add_on>

Response

Status: 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<add_on href="https://your-subdomain.recurly.com/v2/plans/gold/add_ons/ipaddresses">
  <plan href="https://your-subdomain.recurly.com/v2/plans/gold"/>
  <add_on_code>ipaddresses</add_on_code>
  <name>Extra IP Addresses</name>
  <display_quantity_on_hosted_page type="boolean">false</display_quantity_on_hosted_page>
  <default_quantity type="integer">1</default_quantity>
  <unit_amount_in_cents>
    <USD type="integer">1200</USD>
  </unit_amount_in_cents>
  <created_at type="datetime">2011-06-28T12:34:56Z</created_at>
</add_on>
$add_on = Recurly_Addon::get('plan_code', 'addon_code');
$add_on->unit_amount_in_cents['USD']->amount_in_cents = 1200; // $12.00.
$add_on->update();
plan = Recurly::Plan.find('gold')
add_on = plan.add_ons.find('ipaddresses')
add_on.update_attributes :unit_amount_in_cents => 12_00
plan = Plan.get('gold')
add_on = plan.get_add_on('ipaddresses')
add_on.unit_amount_in_cents = 200
add_on.save()

Delete an add-on

Remove an add-on from a plan.

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

Example

Response

Status: 204 No Content
$add_on = Recurly_Addon::get('gold', 'ipaddresses');
$add_on->delete();
plan = Recurly::Plan.find('gold')
add_on = plan.add_ons.find('ipaddresses')
add_on.destroy
plan = Plan.get('gold')
add_on = plan.get_add_on('ipaddresses')
add_on.delete()