Recurly Plan Add Ons API

openapi: 3.2.0
info:
  title: Recurly Plan Add Ons API
  version: '1.0'
  description: 'Operations tagged plan-add-ons across 2 of this provider''s published API definitions: recurly-v2-api.yaml, recurly-v2-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{subdomain}.recurly.com/v2
  variables:
    subdomain:
      description: Subdomain of your Recurly site.
      default: my-super-successful-company
security:
- api_key: []
tags:
- name: plan-add-ons
  x-displayName: Plan add-ons
paths:
  /plans/{plan_code}/add_ons:
    get:
      summary: List Add-Ons for a Plan
      description: Returns a list of all the add-ons for a plan.
      tags:
      - plan-add-ons
      operationId: listAddOnsForAPlan
      parameters:
      - in: query
        name: cursor
        schema:
          type: string
          default: ''
        required: false
        description: 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.
      - in: query
        name: per_page
        schema:
          type: string
          default: '50'
        required: false
        description: Number of records to return per page, up to a maximum of 200.
      - in: path
        name: plan_code
        schema:
          type: string
        required: true
        description: Plan Code.
      responses:
        '200':
          description: ''
          content:
            application/xml:
              example: "Status: 200 OK\nContent-Type: application/xml; charset=utf-8\nX-Records: 5\nETag: \"a4b0568a2278bc591ceb64b31547eb78\"\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<add_ons type=\"array\">\n  <add_on href=\"https://your-subdomain.recurly.com/v2/plans/gold/add_ons/ipaddresses\">\n    <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\"/>\n    <add_on_code>ipaddresses</add_on_code>\n    <name>IP Addresses</name>\n    <default_quantity type=\"integer\">1</default_quantity>\n    <display_quantity_on_hosted_page type=\"boolean\">false</display_quantity_on_hosted_page>\n    <tax_code>digital</tax_code>\n    <unit_amount_in_cents>\n      <USD type=\"integer\">200</USD>\n    </unit_amount_in_cents>\n    <accounting_code>abc123</accounting_code>\n    <created_at type=\"datetime\">2015-06-28T12:34:56Z</created_at>\n  </add_on>\n  <!-- Continued... -->\n</add_ons>"
      x-codeSamples:
      - lang: PHP
        source: "try {\n  $plan = Recurly_Plan::get('gold');\n  $add_ons = $plan->add_ons->get();\n  // Or, in 1 API request:\n  // $add_ons = Recurly_AddonsList::get('gold');\n  foreach ($add_ons as $add_on) {\n    print \"Add-on: $add_on\\n\";\n  }\n} catch (Recurly_NotFoundError $e) {\n  print \"Plan Not Found: $e\";\n}"
      - lang: Ruby
        source: "plan = Recurly::Plan.find('gold')\nplan.add_ons.find_each do |add_on|\n  puts \"Add-on: #{add_on.inspect}\"\nend"
      - lang: Python
        source: "# client version 2.1.6+\nplan = Plan.get('gold')\nfor add_on in plan.add_ons():\n    print 'Add-on: %s' % add_on\n\n# client version <= 2.1.5\nplan = Plan.get('gold')\nadd_ons = plan.add_ons()\nwhile add_ons:\n    for add_on in add_ons:\n        print 'Add-on: %s' % add_on\n    try:\n        add_ons = add_ons.next_page()\n    except PageError:\n        add_ons = ()"
      - lang: Dotnet
        source: "using System.Linq;\n\nvar plan = Plans.Get(\"gold\");\nvar addons = plan.AddOns;\nwhile (addons.Any())\n{\n\tforeach (var addon in addons)\n\t\tConsole.WriteLine(\"Addon: \" + addon);\n\taddons = addons.Next;\n}"
    post:
      summary: Create an Add-On
      description: 'Add an add-on to a plan.


        **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. |

        | `tax_code` | Optional field for EU VAT merchants and Avalara AvaTax Pro merchants. If you are using Recurly''s EU VAT feature, you can use values of ''unknown'', ''physical'', or ''digital''. If you have your own AvaTax account configured, you can use Avalara tax codes to assign custom tax rules. |'
      tags:
      - plan-add-ons
      operationId: createAnAddOn
      parameters:
      - in: path
        name: plan_code
        schema:
          type: string
        required: true
        description: Plan Code.
      responses:
        '201':
          description: ''
          content:
            application/xml:
              example: "Status: 201 Created\nContent-Type: application/xml; charset=utf-8\nLocation: https://your-subdomain.recurly.com/v2/plans/gold/add_ons/ipaddresses\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<add_on href=\"https://your-subdomain.recurly.com/v2/plans/gold/add_ons/ipaddresses\">\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\"/>\n  <add_on_code>ipaddresses</add_on_code>\n  <name>Extra IP Addresses</name>\n  <default_quantity type=\"integer\">1</default_quantity>\n  <display_quantity_on_hosted_page type=\"boolean\">false</display_quantity_on_hosted_page>\n  <tax_code nil=\"nil\"/>\n  <unit_amount_in_cents>\n    <USD type=\"integer\">200</USD>\n  </unit_amount_in_cents>\n  <accounting_code nil=\"nil\"/>\n  <created_at type=\"datetime\">2011-06-28T12:34:56Z</created_at>\n</add_on>"
      x-codeSamples:
      - lang: PHP
        source: "try {\n  $add_on = new Recurly_Addon();\n  $add_on->plan_code = 'gold';\n  $add_on->add_on_code = 'ipaddresses';\n  $add_on->name = 'Extra IP Addresses';\n  $add_on->unit_amount_in_cents->addCurrency('USD', 200);\n  $add_on->create();\n\n  print \"Addon: $add_on\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Addon data: $e\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Plan Not Found: $e\";\n}"
      - lang: Ruby
        source: "plan = Recurly::Plan.find('gold')\nadd_on = plan.add_ons.create(\n  :add_on_code          => 'ipaddresses',\n  :name                 => 'Extra IP Addresses',\n  :unit_amount_in_cents => 2_00\n)"
      - lang: Python
        source: "plan = Plan.get('gold')\naddon = AddOn(\n  add_on_code='ipaddresses',\n  name='Extra IP Addresses',\n  unit_amount_in_cents=200\n)\nplan.create_add_on(addon)"
      - lang: Dotnet
        source: 'var plan = Plans.Get("gold");

          var addon = plan.NewAddOn("ipaddresses", "Extra IP Addresses"); // add-on code, name

          addon.UnitAmountInCents.Add("USD", 200);

          addon.DefaultQuantity = 1;

          addon.DisplayQuantityOnHostedPage = true;

          addon.Create();


          // accounting_code not yet supported.

          // Please contact us if you need this.'
      - lang: xml
        source: "Location: https://your-subdomain.recurly.com/v2/plans/gold/add_ons\nAccept-Type: application/xml\nContent-Type: application/xml; charset=utf-8\n<add_on>\n  <add_on_code>ipaddresses</add_on_code>\n  <name>Extra IP Addresses</name>\n  <unit_amount_in_cents>\n    <USD>200</USD>\n  </unit_amount_in_cents>\n</add_on>"
    servers:
    - url: https://{subdomain}.recurly.com/v2
      variables:
        subdomain:
          description: Subdomain of your Recurly site.
          default: my-super-successful-company
  /{plan_code}/add_ons/{addon_code}:
    get:
      summary: Lookup an Add-On
      description: 'Returns information about an add-on.


        **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. |'
      tags:
      - plan-add-ons
      operationId: lookupAnAddOn
      parameters:
      - in: path
        name: plan_code
        schema:
          type: string
        required: true
        description: Plan Code.
      - in: path
        name: addon_code
        schema:
          type: string
        required: true
        description: Addon Code.
      responses:
        '200':
          description: ''
          content:
            application/xml:
              example: "Status: 200 OK\nContent-Type: application/xml; charset=utf-8\nETag: \"a81253e90a4f16089b951028675c58d2\"\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<add_on href=\"https://your-subdomain.recurly.com/v2/plans/gold/add_ons/ipaddresses\">\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\"/>\n  <add_on_code>ipaddresses</add_on_code>\n  <name>IP Addresses</name>\n  <default_quantity type=\"integer\">1</default_quantity>\n  <display_quantity_on_hosted_page type=\"boolean\">false</display_quantity_on_hosted_page>\n  <tax_code>digital</tax_code>\n  <unit_amount_in_cents>\n    <USD type=\"integer\">200</USD>\n  </unit_amount_in_cents>\n  <accounting_code>abc123</accounting_code>\n  <created_at type=\"datetime\">2011-06-28T12:34:56Z</created_at>\n</add_on>"
      x-codeSamples:
      - lang: Dotnet
        source: 'var plan = Plans.Get("gold");

          var addon = plan.GetAddOn("addOnCode");'
    servers:
    - url: https://{subdomain}.recurly.com/v2
      variables:
        subdomain:
          description: Subdomain of your Recurly site.
          default: my-super-successful-company
  /plans/{plan_code}/add_ons/{add_on_code}:
    put:
      summary: Update an Add-On
      description: 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.
      tags:
      - plan-add-ons
      operationId: updateAnAddOn
      parameters:
      - in: path
        name: plan_code
        schema:
          type: string
        required: true
        description: Plan Code.
      - in: path
        name: add_on_code
        schema:
          type: string
        required: true
        description: Add On Code.
      responses:
        '200':
          description: ''
          content:
            application/xml:
              example: "Status: 200 OK\nContent-Type: application/xml; charset=utf-8\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<add_on href=\"https://your-subdomain.recurly.com/v2/plans/gold/add_ons/ipaddresses\">\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\"/>\n  <add_on_code>ipaddresses</add_on_code>\n  <name>Extra IP Addresses</name>\n  <default_quantity type=\"integer\">1</default_quantity>\n  <display_quantity_on_hosted_page type=\"boolean\">false</display_quantity_on_hosted_page>\n  <tax_code nil=\"nil\"/>\n  <unit_amount_in_cents>\n    <USD type=\"integer\">1200</USD>\n  </unit_amount_in_cents>\n  <accounting_code nil=\"nil\"/>\n  <created_at type=\"datetime\">2011-06-28T12:34:56Z</created_at>\n</add_on>"
        '400':
          description: ''
          content:
            application/json:
              example: '{}'
      x-codeSamples:
      - lang: PHP
        source: "try {\n  $add_on = Recurly_Addon::get('gold', 'ipaddresses'); // (plan_code, addon_code)\n  $add_on->unit_amount_in_cents['USD']->amount_in_cents = 1200; // $12.00.\n  $add_on->update();\n\n  print \"Addon: $add_on\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Addon data: $e\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Plan or Addon Not Found: $e\";\n}"
      - lang: Ruby
        source: 'plan = Recurly::Plan.find(''gold'')

          add_on = plan.add_ons.find(''ipaddresses'')

          add_on.update_attributes :unit_amount_in_cents => 12_00'
      - lang: Python
        source: 'plan = Plan.get(''gold'')

          add_on = plan.get_add_on(''ipaddresses'')

          add_on.unit_amount_in_cents = 200

          add_on.save()'
      - lang: Dotnet
        source: "var plan = Plans.Get(\"gold\");\nvar addon = plan.GetAddOn(\"ipaddresses\");\naddon.UnitAmountInCents[\"USD\"] = 200;\naddon.Update();\n "
      - lang: xml
        source: "Location: https://your-subdomain.recurly.com/v2/plans/gold/add_ons/ipaddresses\nAccept-Type: application/xml\nContent-Type: application/xml; charset=utf-8\n<add_on>\n  <unit_amount_in_cents>\n    <USD>1200</USD>\n  </unit_amount_in_cents>\n</add_on>"
    delete:
      summary: Delete an Add-On
      description: '


        '
      tags:
      - plan-add-ons
      operationId: deleteAnAddOn
      parameters:
      - in: path
        name: plan_code
        schema:
          type: string
        required: true
        description: Plan Code.
      - in: path
        name: add_on_code
        schema:
          type: string
        required: true
        description: Add On Code.
      responses:
        '204':
          description: ''
          content:
            application/json:
              example: 'Status: 204 No Content'
      x-codeSamples:
      - lang: PHP
        source: "try {\n  $add_on = Recurly_Addon::get('gold', 'ipaddresses'); // (plan_code, addon_code)\n  $add_on->delete();\n\n  print \"Addon: $add_on\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Plan or Addon Not Found: $e\";\n}"
      - lang: Ruby
        source: 'plan = Recurly::Plan.find(''gold'')

          add_on = plan.add_ons.find(''ipaddresses'')

          add_on.destroy'
      - lang: Python
        source: 'plan = Plan.get(''gold'')

          add_on = plan.get_add_on(''ipaddresses'')

          add_on.delete()'
      - lang: Dotnet
        source: 'var plan = Plans.Get("gold");

          var addon = plan.GetAddOn("ipaddresses");

          addon.Delete();'
    servers:
    - url: https://{subdomain}.recurly.com/v2
      variables:
        subdomain:
          description: Subdomain of your Recurly site.
          default: my-super-successful-company
components:
  securitySchemes:
    api_key:
      type: http
      description: Enter the API key as the username and set the password to an empty string. You can locate and manage your API keys from the [API Credentials](https://app.recurly.com/go/developer/api_keys) page.
      scheme: basic
x-refined-from:
- recurly-v2-api.yaml
- recurly-v2-openapi.yml
x-readme:
  explorer-enabled: false