Recurly Plans API

openapi: 3.2.0
info:
  title: Recurly Plans API
  version: '1.0'
  description: 'Operations tagged plans 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: Plans
  x-displayName: Plans
paths:
  /plans:
    get:
      summary: List Plans
      description: 'Lists all your active subscription plans.


        The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page.'
      tags:
      - Plans
      operationId: listPlans
      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: integer
          default: '50'
        required: false
        description: Number of records to return per page, up to a maximum of 200.
      responses:
        '200':
          description: ''
          content:
            application/xml:
              example: "Status: 200 OK\nContent-Type: application/xml; charset=utf-8\nX-Records: 64\nLink: <https://your-subdomain.recurly.com/v2/plans?cursor=1304958672>; rel=\"next\"\nETag: \"9220276b89e7b1a7eb6b750de3bf9fbc\"\n\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<plans type=\"array\">\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n    <add_ons href=\"https://your-subdomain.recurly.com/v2/plans/gold/add_ons\"/>\n    <plan_code>gold</plan_code>\n    <name>Gold plan</name>\n    <description nil=\"nil\"/>\n    <success_url nil=\"nil\"/>\n    <cancel_url nil=\"nil\"/>\n    <display_donation_amounts type=\"boolean\">false</display_donation_amounts>\n    <display_quantity type=\"boolean\">false</display_quantity>\n    <display_phone_number type=\"boolean\">false</display_phone_number>\n    <bypass_hosted_confirmation type=\"boolean\">false</bypass_hosted_confirmation>\n    <unit_name>unit</unit_name>\n    <payment_page_tos_link nil=\"nil\"/>\n    <plan_interval_length type=\"integer\">1</plan_interval_length>\n    <plan_interval_unit>months</plan_interval_unit>\n    <trial_interval_length type=\"integer\">0</trial_interval_length>\n    <trial_interval_unit>days</trial_interval_unit>\n    <total_billing_cycles nil=\"nil\"/>\n    <accounting_code nil=\"nil\"/>\n    <created_at type=\"datetime\">2015-05-29T17:38:15Z</created_at>\n    <tax_exempt type=\"boolean\">false</tax_exempt>\n    <tax_code nil=\"nil\"/>\n    <unit_amount_in_cents>\n      <USD type=\"integer\">6000</USD>\n      <EUR type=\"integer\">4500</EUR>\n    </unit_amount_in_cents>\n    <setup_fee_in_cents>\n      <USD type=\"integer\">1000</USD>\n      <EUR type=\"integer\">800</EUR>\n    </setup_fee_in_cents>\n  </plan>\n  <!-- Continued... -->\n</plans>"
      x-codeSamples:
      - lang: PHP
        source: "$plans = Recurly_PlanList::get();\nforeach ($plans as $plan) {\n  print \"Plan: $plan\\n\";\n}"
      - lang: Ruby
        source: "Recurly::Plan.find_each do |plan|\n  puts \"Plan: #{plan.inspect}\"\nend"
      - lang: Python
        source: "# client version 2.1.6+\nfor plan in Plan.all():\n    print 'Plan: %s' % plan\n\n# client version <= 2.1.5\nplans = Plan.all()\nwhile plans:\n    for plan in plans:\n        print 'Plan: %s' % plan\n    try:\n        plans = plans.next_page()\n    except PageError:\n        plans = ()"
      - lang: Dotnet
        source: "using System.Linq;\n\nvar plans = Plans.List();\nwhile (plans.Any())\n{\n\tforeach (var plan in plans)\n\t\tConsole.WriteLine(\"Plan: \" + plan);\n\tplans = plans.Next;\n}"
    post:
      summary: Create Plan
      description: Create a new subscription plan.
      tags:
      - Plans
      operationId: createPlan
      parameters: []
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: object
              properties:
                plan_code:
                  type: string
                  default: ''
                  description: 'Unique code to identify the plan. This code may only contain the following characters: [a-z 0-9 @ - _ .]. Max of 50 characters.'
                name:
                  type: string
                  default: ''
                  description: Plan name. Max of 255 characters.
                description:
                  type: string
                  default: ''
                  description: Optional plan description, not displayed
                accounting_code:
                  type: string
                  default: ''
                  description: 'Accounting code for related invoice line items, defaults to ths code may only contain the following characters: [a-z 0-9 @ - _ .]. Max of 20 characters.'
                plan_interval_unit:
                  type: string
                  default: ''
                  description: '"days", or "months", defaults to "months"'
                plan_interval_length:
                  type: integer
                  default: '1'
                  description: Plan interval length, defaults to 1
                trial_interval_unit:
                  type: string
                  default: months
                  description: days", or "months", defaults to "months"
                trial_interval_length:
                  type: integer
                  default: '0'
                  description: Defaults to zero, or no trial
                setup_fee_in_cents:
                  type: array
                  default: ''
                  description: Array of currency objects, see examples. Max 10000000.
                unit_amount_in_cents:
                  type: integer
                  default: ''
                  description: Array of currency objects, see example below. Max 10000000.
                total_billing_cycles:
                  type: string
                  default: 'null'
                  description: Number of billing cycles before the plan stops renewing, defaults to null for continuous auto renewal.
                unit_name:
                  type: string
                  default: ''
                  description: Unit description for the quantity, e.g. "users".
                display_quantity:
                  type: boolean
                  default: 'false'
                  description: Display the quantity field on the hosted payment page if true, defaults to false.
                success_url:
                  type: string
                  default: ''
                  description: URL to redirect to after signup on the hosted payment pages.
                cancel_url:
                  type: string
                  default: ''
                  description: URL to redirect to on canceled signup on the hosted payment pages.
                tax_exempt:
                  type: boolean
                  default: ''
                  description: '`true` exempts tax on the plan, `false` applies tax on the plan. If not defined, then defaults to the Plan and Site settings.'
                tax_code:
                  type: string
                  maxLength: 50
                  title: Tax code
                  description: Optional field used by Avalara, Vertex, and Recurly's In-the-Box tax solution to determine taxation rules. You can pass in specific tax codes using any of these tax integrations. For Recurly's In-the-Box tax offering you can also choose to instead use simple values of `unknown`, `physical`, or `digital` tax codes.
      responses:
        '201':
          description: ''
          content:
            application/xml:
              example: "Status: 201 Created\nContent-Type: application/xml; charset=utf-8\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n  <add_ons href=\"https://your-subdomain.recurly.com/v2/plans/gold/add_ons\"/>\n  <plan_code>gold</plan_code>\n  <name>Gold plan</name>\n  <description nil=\"nil\"/>\n  <success_url nil=\"nil\"/>\n  <cancel_url nil=\"nil\"/>\n  <display_donation_amounts type=\"boolean\">false</display_donation_amounts>\n  <display_quantity type=\"boolean\">false</display_quantity>\n  <display_phone_number type=\"boolean\">false</display_phone_number>\n  <bypass_hosted_confirmation type=\"boolean\">false</bypass_hosted_confirmation>\n  <unit_name>unit</unit_name>\n  <payment_page_tos_link nil=\"nil\"/>\n  <plan_interval_length type=\"integer\">1</plan_interval_length>\n  <plan_interval_unit>months</plan_interval_unit>\n  <trial_interval_length type=\"integer\">0</trial_interval_length>\n  <trial_interval_unit>days</trial_interval_unit>\n  <total_billing_cycles nil=\"nil\"/>\n  <accounting_code nil=\"nil\"/>\n  <created_at type=\"datetime\">2015-05-29T17:38:15Z</created_at>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <tax_code nil=\"nil\"/>\n  <unit_amount_in_cents>\n    <USD type=\"integer\">6000</USD>\n    <EUR type=\"integer\">4500</EUR>\n  </unit_amount_in_cents>\n  <setup_fee_in_cents>\n    <USD type=\"integer\">1000</USD>\n    <EUR type=\"integer\">800</EUR>\n  </setup_fee_in_cents>\n</plan>"
      x-codeSamples:
      - lang: PHP
        source: "try {\n  $plan = new Recurly_Plan();\n  $plan->plan_code = 'gold';\n  $plan->name = \"Gold plan\";\n  $plan->unit_amount_in_cents->addCurrency('USD', 1000); // USD 10.00 month\n  $plan->unit_amount_in_cents->addCurrency('EUR', 800);  // EUR 8.00 month\n  $plan->setup_fee_in_cents->addCurrency('USD', 6000); // USD 60.00 setup fee\n  $plan->setup_fee_in_cents->addCurrency('EUR', 4500); // EUR 45.00 setup fee\n  $plan->plan_interval_length = 1;\n  $plan->plan_interval_unit = 'months';\n  $plan->tax_exempt = false;\n  $plan->create();\n\n  print \"Plan: $plan\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Data: $e\";\n}"
      - lang: Ruby
        source: "plan = Recurly::Plan.create(\n  :plan_code            => 'gold',\n  :name                 => 'Gold plan',\n  :unit_amount_in_cents => { 'USD' => 10_00, 'EUR' => 8_00 },\n  :setup_fee_in_cents   => { 'USD' => 60_00, 'EUR' => 45_00 },\n  :plan_interval_length => 1,\n  :plan_interval_unit   => 'months'\n  :tax_exempt           => false\n)"
      - lang: Python
        source: 'plan = Plan(plan_code=''gold'', name=''Gold plan'')

          plan.unit_amount_in_cents = Money(USD=1000, EUR=800)

          plan.setup_fee_in_cents = Money(USD=6000, EUR=4500)

          plan.plan_interval_length = 1

          plan.plan_interval_unit = ''months''

          plan.tax_exempt = False

          plan.save()'
      - lang: Dotnet
        source: 'var plan = new Plan("gold", "Gold plan"); // plan code, name

          plan.UnitAmountInCents.Add("USD", 1000);

          plan.UnitAmountInCents.Add("EUR", 800);

          plan.SetupFeeInCents.Add("USD", 6000);

          plan.SetupFeeInCents.Add("EUR", 4500);

          plan.PlanIntervalLength = 1;

          plan.PlanIntervalUnit = Plan.IntervalUnit.Month;

          plan.TaxExempt = false;

          plan.Create();'
      - lang: xml
        source: "Accept: application/xml\nContent-Type: application/xml; charset=utf-8\n<plan>\n  <plan_code>gold</plan_code>\n  <name>Gold plan</name>\n  <unit_amount_in_cents>\n    <USD>6000</USD>\n    <EUR>4500</EUR>\n  </unit_amount_in_cents>\n  <setup_fee_in_cents>\n    <USD>1000</USD>\n    <EUR>800</EUR>\n  </setup_fee_in_cents>\n  <plan_interval_length>1</plan_interval_length>\n  <plan_interval_unit>months</plan_interval_unit>\n  <tax_exempt>false</tax_exempt>\n</plan>"
    servers:
    - url: https://{subdomain}.recurly.com/v2
      variables:
        subdomain:
          description: Subdomain of your Recurly site.
          default: my-super-successful-company
  /plans/{plan_code}:
    get:
      summary: Lookup Plan Details
      description: Lookup a plan's details.
      tags:
      - Plans
      operationId: lookupPlanDetails
      parameters:
      - 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\nETag: \"937782009c7a198a1ee2659bf198e987\"\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n  <add_ons href=\"https://your-subdomain.recurly.com/v2/plans/gold/add_ons\"/>\n  <plan_code>gold</plan_code>\n  <name>Gold plan</name>\n  <description nil=\"nil\"/>\n  <success_url nil=\"nil\"/>\n  <cancel_url nil=\"nil\"/>\n  <display_donation_amounts type=\"boolean\">false</display_donation_amounts>\n  <display_quantity type=\"boolean\">false</display_quantity>\n  <display_phone_number type=\"boolean\">false</display_phone_number>\n  <bypass_hosted_confirmation type=\"boolean\">false</bypass_hosted_confirmation>\n  <unit_name>unit</unit_name>\n  <payment_page_tos_link nil=\"nil\"/>\n  <plan_interval_length type=\"integer\">1</plan_interval_length>\n  <plan_interval_unit>months</plan_interval_unit>\n  <trial_interval_length type=\"integer\">0</trial_interval_length>\n  <trial_interval_unit>days</trial_interval_unit>\n  <total_billing_cycles nil=\"nil\"/>\n  <accounting_code nil=\"nil\"/>\n  <created_at type=\"datetime\">2015-05-29T17:38:15Z</created_at>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <tax_code nil=\"nil\"/>\n  <unit_amount_in_cents>\n    <EUR type=\"integer\">4500</EUR>\n    <USD type=\"integer\">6000</USD>\n  </unit_amount_in_cents>\n  <setup_fee_in_cents>\n    <EUR type=\"integer\">800</EUR>\n    <USD type=\"integer\">1000</USD>\n  </setup_fee_in_cents>\n</plan>"
      x-codeSamples:
      - lang: PHP
        source: "try {\n  $plan = Recurly_Plan::get('gold');\n  print \"Plan: $plan\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Plan not found\";\n}"
      - lang: Ruby
        source: plan = Recurly::Plan.find('gold')
      - lang: Python
        source: plan = Plan.get('gold')
      - lang: Dotnet
        source: var plan = Plans.Get("gold");
    put:
      summary: Update Plan
      description: Update the pricing or details for a plan. Existing subscriptions will remain at the previous renewal amounts.
      tags:
      - Plans
      operationId: updatePlan
      parameters:
      - 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\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n  <add_ons href=\"https://your-subdomain.recurly.com/v2/plans/gold/add_ons\"/>\n  <plan_code>gold</plan_code>\n  <name>Gold plan</name>\n  <description nil=\"nil\"/>\n  <success_url nil=\"nil\"/>\n  <cancel_url nil=\"nil\"/>\n  <display_donation_amounts type=\"boolean\">false</display_donation_amounts>\n  <display_quantity type=\"boolean\">false</display_quantity>\n  <display_phone_number type=\"boolean\">false</display_phone_number>\n  <bypass_hosted_confirmation type=\"boolean\">false</bypass_hosted_confirmation>\n  <unit_name>unit</unit_name>\n  <payment_page_tos_link nil=\"nil\"/>\n  <plan_interval_length type=\"integer\">1</plan_interval_length>\n  <plan_interval_unit>months</plan_interval_unit>\n  <trial_interval_length type=\"integer\">0</trial_interval_length>\n  <trial_interval_unit>days</trial_interval_unit>\n  <total_billing_cycles nil=\"nil\"/>\n  <accounting_code nil=\"nil\"/>\n  <created_at type=\"datetime\">2015-05-29T17:38:15Z</created_at>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <tax_code nil=\"nil\"/>\n  <unit_amount_in_cents>\n    <EUR type=\"integer\">4500</EUR>\n    <USD type=\"integer\">6000</USD>\n  </unit_amount_in_cents>\n  <setup_fee_in_cents>\n    <EUR type=\"integer\">5000</EUR>\n    <USD type=\"integer\">6000</USD>\n  </setup_fee_in_cents>\n</plan>"
        '400':
          description: ''
          content:
            application/json:
              example: '{}'
      x-codeSamples:
      - lang: PHP
        source: "try {\n  $plan = Recurly_Plan::get('gold');\n  $plan->unit_amount_in_cents['EUR'] = 5000; // EUR 50.00 monthly fee\n  $plan->setup_fee_in_cents['EUR'] = 5000; // EUR 50.00 setup fee\n  $plan->update();\n\n  print \"Plan: $plan\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Data: $e\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Plan Not Found: $e\";\n}"
      - lang: Ruby
        source: 'plan = Recurly::Plan.find(''gold'')

          plan.setup_fee_in_cents[''EUR''] = 50_00

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

          plan.setup_fee_in_cents[''EUR''] = 5000

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

          plan.SetupFeeInCents["EUR"] = 5000;

          plan.Update();'
      - lang: xml
        source: "Location: https://your-subdomain.recurly.com/v2/plans/gold\nAccept: application/xml\nContent-Type: application/xml; charset=utf-8\n<plan>\n  <setup_fee_in_cents>\n    <USD>6000</USD>\n    <EUR>5000</EUR>\n  </setup_fee_in_cents>\n</plan>"
    delete:
      summary: Delete Plan
      description: Deleting a plan makes it inactive. New accounts cannot be created on the plan.
      tags:
      - Plans
      operationId: deletePlan
      parameters:
      - in: path
        name: plan_code
        schema:
          type: string
        required: true
        description: Plan Code.
      responses:
        '200':
          description: ''
          content:
            application/text:
              example: ''
      x-codeSamples:
      - lang: PHP
        source: "try {\n  $plan = Recurly_Plan::get('gold');\n  $plan->delete();\n\n  print \"Plan: $plan\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Plan Not Found: $e\";\n}"
      - lang: Ruby
        source: 'plan = Recurly::Plan.find(''gold'')

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

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

          plan.Deactivate();'
    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