Recurly Coupons API

openapi: 3.2.0
info:
  title: Recurly Coupons API
  version: '1.0'
  description: 'Operations tagged coupons 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: Coupons
  x-displayName: Coupons
paths:
  /coupons:
    get:
      summary: List Active Coupons
      description: Returns a list of all the coupons.
      tags:
      - Coupons
      operationId: listActiveCoupons
      parameters:
      - in: query
        name: state
        schema:
          type: string
          default: all
        required: false
        description: 'The state of coupons to return: "redeemable", "expired", "maxed_out", or "inactive".'
      - 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\nETag: \"b2b8cb271080534189ba41d7058177cc\"\n\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<coupons type=\"array\">\n  <coupon href=\"https://your-subdomain.recurly.com/v2/coupons/special\">\n    <redemptions href=\"https://your-subdomain.recurly.com/v2/coupons/special/redemptions\"/>\n    <coupon_code>special</coupon_code>\n    <name>Special 10% off</name>\n    <state>redeemable</state>\n    <discount_type>percent</discount_type>\n    <discount_percent type=\"integer\">10</discount_percent>\n    <redeem_by_date type=\"datetime\">2014-01-01T07:00:00Z</redeem_by_date>\n    <single_use type=\"boolean\">true</single_use>\n    <applies_for_months nil=\"nil\"></applies_for_months>\n    <max_redemptions type=\"integer\">10</max_redemptions>\n    <applies_to_all_plans type=\"boolean\">false</applies_to_all_plans>\n    <created_at type=\"datetime\">2011-04-10T07:00:00Z</created_at>\n    <plan_codes type=\"array\">\n      <plan_code>gold</plan_code>\n      <plan_code>platinum</plan_code>\n    </plan_codes>\n    <a name=\"redeem\" href=\"https://your-subdomain.recurly.com/v2/coupons/special/redeem\" method=\"post\"/>\n  </coupon>\n  <!-- Continued... -->\n</coupons>"
      x-codeSamples:
      - lang: PHP
        source: "$coupons = Recurly_CouponList::get();\nforeach ($coupons as $coupon) {\n  print \"Coupon: $coupon\\n\";\n}"
      - lang: Ruby
        source: "Recurly::Coupon.find_each do |coupon|\n  puts \"Coupon: #{coupon.inspect}\"\nend"
      - lang: Python
        source: "# client version 2.1.6+\nfor coupon in Coupon.all():\n    print 'Coupon: %s' % coupon\n\n# client version <= 2.1.5\ncoupons = Coupon.all()\nwhile coupons:\n    for coupon in coupons:\n        print 'Coupon: %s' % coupon\n    try:\n        coupons = coupons.next_page()\n    except PageError:\n        coupons = ()"
      - lang: Dotnet
        source: "using System.Linq;\n\nvar coupons = Coupons.List();\nwhile (coupons.Any())\n{\n\tforeach (var coupon in coupons)\n\t\tConsole.WriteLine(\"Coupon: \" + coupon);\n\tcoupons = coupons.Next;\n}"
    post:
      summary: Create Coupon
      description: 'Creates a new coupon. Please note: coupons cannot be updated after being created.


        **DISCOUNT IN DOLLARS**

        When specifying a discount amount as a flat amount, the currency must be specified with the amount in an array. For example:

        ```

        dollars


        500

        400

        300


        ```

        **DISCOUNT IN PERCENTAGE**

        Percentage discounts only need to specify the discount percentage. For example:

        ```

        percent

        10

        ```

        **LIMITING TO SPECIFIC PLANS**

        If a coupon applies to all plans, it will also apply to any plans created in the future. To limit a coupon to specific plans, you may specify an array of plan codes. For example:

        ```

        false


        silver

        gold


        ```'
      tags:
      - Coupons
      operationId: createCoupon
      parameters: []
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: object
              properties:
                coupon_code:
                  type: string
                  default: ''
                  description: 'Unique code to identify and redeem the coupon. This code may only contain the following characters: [a-z A-Z 0-9 @ - _ .]. Max of 50 characters'
                name:
                  type: string
                  default: ''
                  description: Coupon name
                hosted_description:
                  type: string
                  default: ''
                  description: Description of the coupon on the hosted payment pages
                invoice_description:
                  type: string
                  default: ''
                  description: Description of the coupon on the invoice
                redeem_by_date:
                  type: string
                  format: date
                  default: ''
                  description: Last date to redeem the coupon, defaults to no date
                single_use:
                  type: boolean
                  default: ''
                  description: If true, the coupon applies to the first invoice only
                applies_for_months:
                  type: integer
                  default: ''
                  description: Number of months after redemption that the coupon is valid, defaults to no date
                max_redemptions:
                  type: string
                  default: ''
                  description: Maximum number of accounts that may use the coupon before it can no longer be redeemed
                applies_to_all_plans:
                  type: boolean
                  default: ''
                  description: The coupon is valid for all plans if true, defaults to true
                discount_type:
                  type: string
                  default: ''
                  description: '"percent" or "dollars"'
                discount_percent:
                  type: integer
                  default: ''
                  description: Discount percentage if discount_type is "percent"
                discount_in_cents:
                  type: integer
                  default: ''
                  description: Mapping of discount amounts by currency if discount_type is "dollars". Max 10000000.
                plan_codes:
                  type: string
                  default: ''
                  description: Array of plan_codes the coupon applies to, if applies_to_all_plans is false
      responses:
        '201':
          description: ''
          content:
            application/xml:
              example: "Status: 201 Created\nContent-Type: application/xml; charset=utf-8\nLocation: https://your-subdomain.recurly.com/v2/coupons/special\n\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<coupon href=\"https://your-subdomain.recurly.com/v2/coupons/special\">\n  <redemptions href=\"https://your-subdomain.recurly.com/v2/coupons/special/redemptions\"/>\n  <coupon_code>special</coupon_code>\n  <name>Special 10% off</name>\n  <state>redeemable</state>\n  <discount_type>percent</discount_type>\n  <discount_percent type=\"integer\">10</discount_percent>\n  <redeem_by_date type=\"datetime\">2016-07-04T07:00:00Z</redeem_by_date>\n  <single_use type=\"boolean\">true</single_use>\n  <applies_for_months nil=\"nil\"></applies_for_months>\n  <max_redemptions type=\"integer\">10</max_redemptions>\n  <applies_to_all_plans type=\"boolean\">false</applies_to_all_plans>\n  <created_at type=\"datetime\">2015-04-10T07:00:00Z</created_at>\n  <plan_codes type=\"array\">\n    <plan_code>gold</plan_code>\n    <plan_code>platinum</plan_code>\n  </plan_codes>\n  <a name=\"redeem\" href=\"https://your-subdomain.recurly.com/v2/coupons/special/redeem\" method=\"post\"/>\n</coupon>"
      x-codeSamples:
      - lang: PHP
        source: "try {\n  $coupon = new Recurly_Coupon();\n  $coupon->coupon_code = 'special';\n  $coupon->redeem_by_date = '2016-07-04';\n  $coupon->single_use = true;\n\n  // $2 off...\n  $coupon->name = 'Special $2 off coupon';\n  $coupon->discount_type = 'dollars';\n  $coupon->discount_in_cents->addCurrency('USD',200); // $2.00 discount\n\n  // ...or 10% off.\n  $coupon->name = 'Special 10% off';\n  $coupon->discount_type = 'percent';\n  $coupon->discount_percent = 10;\n\n  // Limit to gold and platinum plans only.\n  $coupon->applies_to_all_plans = false;\n  $coupon->plan_codes = array('gold', 'platinum');\n\n  $coupon->create();\n\n  print \"Coupon: $coupon\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid data: $e\";\n}"
      - lang: Ruby
        source: "coupon = Recurly::Coupon.new(\n  :coupon_code    => 'special',\n  :redeem_by_date => Date.new(2014, 1, 1),\n  :single_use     => true\n)\n\n# $2 off...\ncoupon.name = 'Special $2 off coupon'\ncoupon.discount_type = 'dollars'\ncoupon.discount_in_cents = 2_00\n\n# ...or 10% off.\ncoupon.name = 'Special 10% off'\ncoupon.discount_type = 'percent'\ncoupon.discount_percent = 10\n\n# Limit to gold and platinum plans only.\ncoupon.applies_to_all_plans = false\ncoupon.plan_codes = %w(gold platinum)\n\ncoupon.save"
      - lang: Python
        source: "coupon = Coupon(\n  coupon_code='special',\n  redeem_by_date=datetime.date(2014, 1, 1),\n  single_use=True\n)\n\n# $2 off...\ncoupon.name = 'Special $2 off coupon'\ncoupon.discount_type = 'dollars'\ncoupon.discount_in_cents = Money(200)\n\n# ...or 10% off.\ncoupon.name = 'Special 10% off'\ncoupon.discount_type = 'percent'\ncoupon.discount_percent = 10\n\n# Limit to gold and platinum plans only.\ncoupon.applies_to_all_plans = False\ncoupon.plan_codes = ['gold', 'platinum']\n\ncoupon.save()"
      - lang: Dotnet
        source: 'var coupon = new Coupon();

          coupon.CouponCode = "special";

          coupon.RedeemByDate = new DateTime(2017, 1, 1);

          coupon.SingleUse = true;


          // $2 off...

          coupon.Name = "Special $2 off coupon";

          coupon.DiscountType = Coupon.CouponDiscountType.Dollars

          coupon.DiscountInCents = new Dictionary<string, int>;

          coupon.DiscountInCents["USD"] = 200;


          // ...or 10% off

          coupon.Name = "Special 10% off coupon";

          coupon.DiscountType = Coupon.CouponDiscountType.Percent;

          coupon.DiscountPercent = 10;


          // Limit to gold and platinum plans only.

          coupon.AppliesToAllPlans = false;

          coupon.Plans.Add("gold");

          coupon.Plans.Add("silver");


          // Other properties

          coupon.RedeemByDate = new DateTime(2014, 1, 1);

          coupon.SingleUse = true;


          coupon.Create();'
      - lang: xml
        source: "//  Request for specific plans:\n\nAccept: application/xml\nContent-Type: application/xml; charset=utf-8\n<coupon>\n  <coupon_code>special</coupon_code>\n  <name>Special $2 off coupon</name>\n  <discount_type>dollars</discount_type>\n  <redeem_by_date>2014-01-01</redeem_by_date>\n  <single_use>true</single_use>\n  <max_redemptions>10</max_redemptions>\n  <applies_to_all_plans>true</applies_to_all_plans>\n  <discount_in_cents>\n    <USD>200</USD>\n  </discount_in_cents>\n</coupon>\n\n// Request for $2 coupon:\n\nAccept: application/xml\nContent-Type: application/xml; charset=utf-8\n<coupon>\n  <coupon_code>special</coupon_code>\n  <name>Special 10% off</name>\n  <discount_type>percent</discount_type>\n  <discount_percent>10</discount_percent>\n  <redeem_by_date>2014-01-01</redeem_by_date>\n  <single_use>true</single_use>\n  <max_redemptions>10</max_redemptions>\n  <applies_to_all_plans>false</applies_to_all_plans>\n  <plan_codes>\n    <plan_code>gold</plan_code>\n    <plan_code>platinum</plan_code>\n  </plan_codes>\n</coupon>"
    servers:
    - url: https://{subdomain}.recurly.com/v2
      variables:
        subdomain:
          description: Subdomain of your Recurly site.
          default: my-super-successful-company
  /coupons/{coupon_code}:
    get:
      summary: Lookup a Coupon
      description: Returns information about an active coupon.
      tags:
      - Coupons
      operationId: lookupACoupon
      parameters:
      - in: path
        name: coupon_code
        schema:
          type: string
          default: ''
        required: true
        description: Unique code to identify and redeem the coupon
      responses:
        '200':
          description: ''
          content:
            application/xml:
              example: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<coupon href=\"https://your-subdomain.recurly.com/v2/coupons/special\">\n  <redemptions href=\"https://your-subdomain.recurly.com/v2/coupons/special/redemptions\"/>\n  <coupon_code>special</coupon_code>\n  <name>Special 10% off</name>\n  <state>redeemable</state>\n  <hosted_description>10% off coupon</hosted_description>\n  <discount_type>percent</discount_type>\n  <discount_percent type=\"integer\">10</discount_percent>\n  <redeem_by_date type=\"datetime\">2014-01-01T07:00:00Z</redeem_by_date>\n  <single_use type=\"boolean\">true</single_use>\n  <applies_for_months nil=\"nil\"></applies_for_months>\n  <max_redemptions type=\"integer\">10</max_redemptions>\n  <applies_to_all_plans type=\"boolean\">false</applies_to_all_plans>\n  <created_at type=\"datetime\">2015-04-10T07:00:00Z</created_at>\n  <plan_codes type=\"array\">\n    <plan_code>gold</plan_code>\n    <plan_code>platinum</plan_code>\n  </plan_codes>\n  <a name=\"redeem\" href=\"https://your-subdomain.recurly.com/v2/coupons/special/redeem\" method=\"post\"/>\n</coupon>"
      x-codeSamples:
      - lang: PHP
        source: "try {\n  $coupon = Recurly_Coupon::get('special');\n  print \"Coupon: $coupon\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Coupon does not exist\";\n}"
      - lang: Ruby
        source: coupon = Recurly::Coupon.find('special')
      - lang: Python
        source: coupon = Coupon.get('special')
      - lang: Dotnet
        source: var coupon = Coupons.Get("special");
    delete:
      summary: Deactivate Coupon
      description: Deactivate the coupon so customers can no longer redeem the coupon.
      tags:
      - Coupons
      operationId: deactivateCoupon
      parameters:
      - in: path
        name: coupon_code
        schema:
          type: string
        required: true
        description: Coupon Code.
      responses:
        '200':
          description: ''
          content:
            application/text:
              example: ''
      x-codeSamples:
      - lang: PHP
        source: "try {\n  $coupon = Recurly_Coupon::get('special');\n  $coupon->delete();\n\n  print \"Coupon: $coupon\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Coupon not found: $e\";\n}"
      - lang: Ruby
        source: 'coupon = Recurly::Coupon.find(''special'')

          coupon.destroy'
      - lang: Python
        source: 'coupon = Coupon.get(''special'')

          coupon.delete()'
      - lang: Dotnet
        source: 'var coupon = Coupons.Get("special");

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