Plan Add-ons API

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 = 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`	First name
`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()