---
updatedAt: 2026-05-05T19:53:57.000Z
agentTools:
  siteIndex: https://docs.recurly.com/llms.txt
  projectIndex: https://docs.recurly.com/recurly-subscriptions/v2021-02-25/llms.txt
---

# List a site's coupons

See the [Pagination Guide](/developers/guides/pagination.html) to learn how to use pagination in the API and Client Libraries.

# OpenAPI definition

````json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Recurly V3 API",
    "description": "# Getting Started\n\n## Versioning\nThe V3 API is versioned to allow stability for integrators and\nflexibility for Recurly to continue making improvements.\n\nThe versions follow a format that incorporates the approximate date the\nchanges were released in a YYYY-MM-DD format, e.g. `v2021-02-25`.\n\n> *WARNING*: Specifying a version is required to get a successful response.\n\nEach request should specify a version using the `Accept` header:\n* `Accept: application/vnd.recurly.v2021-02-25`\n* `Accept: application/vnd.recurly.v2021-02-25+json`\n\nAll responses will include a `Recurly-Version` header with the API version\nused to process the request:\n```\nRecurly-Version: recurly.v2021-02-25\n```\n\nRecurly's client libraries correspond with API versions as listed below.\n\n<table>\n  <tr>\n    <th>API Version</th>\n    <th>Client Library Version</th>\n  </tr>\n  <tr>\n    <td>v2021-02-25</td>\n    <td>4.x</td>\n  </tr>\n  <tr>\n    <td>v2019-10-10</td>\n    <td>3.x</td>\n  </tr>\n</table>\n\nClient library releases:\n\n* [Node.js](https://github.com/recurly/recurly-client-node/releases)\n* [Python](https://github.com/recurly/recurly-client-python/releases)\n* [.NET](https://github.com/recurly/recurly-client-dotnet/releases)\n* [Ruby](https://github.com/recurly/recurly-client-ruby/releases)\n* [Java](https://github.com/recurly/recurly-client-java/releases)\n* [PHP](https://github.com/recurly/recurly-client-php/releases)\n* [Go](https://github.com/recurly/recurly-client-go/releases)\n\nClient libraries follow semantic versioning. For example, [Ruby client library\nversion 3.18.1](https://github.com/recurly/recurly-client-ruby/releases/tag/3.18.1)\nrepresents major version `3`, minor version `18` with patch `1`.\n\nWe encourage you to update to the latest version of the API and corresponding client library,\nas most recent versions are more performant than their predecessors. See the\n[changelog](https://recurly.com/developers/api/changelog.html) for a comprehensive list of changes\nintroduced in the latest API version.\n\n### Default Versions\nSpecifying a version is required to get a successful response. If you wish to\nreceive the latest version and are willing to accept the risk of breaking changes,\nyou may specify a version of `latest`.\n\nThe following media types will default the newest version of\nthe API:\n\n* `application/vnd.recurly.latest`\n* `application/vnd.recurly.latest+json`\n\n### Deprecation\nResponses for a deprecated version request will return two headers:\n```\nRecurly-Deprecated: TRUE\nRecurly-Sunset-Date: 2017-06-01T00:00:00+00:00\n```\nThe sunset date is an ISO-8601 formatted date time after which the version\nwill no longer be accessible.\n\n### Unsupported Versions\nA request for an unsupported version will return a status code of 406 and\nthe body will include a list of supported versions:\n```\n{\n  \"error\": {\n    \"type\": \"invalid_api_version\",\n    \"message\": \"That accept header isn't in the format we use to specify an API version. Try one of these instead:\",\n    \"acceptable_accept_headers\": [\n      \"application/vnd.recurly.v2016-03-01\",\n      \"application/vnd.recurly.v2016-04-27\",\n      \"application/vnd.recurly.v2016-07-27\",\n      \"application/vnd.recurly.v2016-12-15\",\n      \"application/vnd.recurly.v2017-01-12\",\n      \"application/vnd.recurly.v2017-09-30\",\n      \"application/vnd.recurly.v2018-01-24\",\n      \"application/vnd.recurly.v2018-05-10\",\n      \"application/vnd.recurly.v2018-06-06\",\n      \"application/vnd.recurly.v2018-08-09\",\n      \"application/vnd.recurly.v2019-10-10\",\n      \"application/vnd.recurly.v2021-02-25\"\n    ]\n  }\n}\n```\n\n## Error Messages\nError messages sent via the Recurly API are generally directed at\ndevelopers and those who are familiar with API technology. When using the\nAPI and passing error messages to target systems, be mindful that\nthese messages may not make sense in the context of the target system.\nPlease consider changing these messages in the target system to be better\nsuited to the audience of the system.\n\nPlease see [transaction error codes](https://recurly.com/developers/pages/api-transaction-errors.html) for more details.\n\n## Pagination\n### Response Schema\nEvery GET listing endpoint returns a response with the same schema:\n\n```\n{\n  \"object\":   \"list\",         // Always \"list\"\n  \"has_more\": true,           // false if this is the last page of data\n  \"next\":     \"https://...\",  // A URL pointing to the next page of data\n  \"data\":     []              // The data for this page as an array\n}\n```\n\nTo page through every record, your code should continually call the URL\nat `next` until `has_more` is `false`.\n\n### Query Parameters\nMost GET listing endpoints take query parameters that allow filtering\nand sorting the results. Some endpoints have additional parameters, which are\ndocumented on the respective endpoints, but most support the\nfollowing parameters:\n\n* `ids`: A comma separated list of ids to match.\n* `limit`: The number of records to return per page.\n* `order`: The sort order of records.\n* `sort`: The date field to use in sorting.\n* `begin_time`: The start datetime to filter (ISO 8601).\n* `end_time`: The end datetime to filter (ISO 8601).\n\n### Counting with HEAD\nEvery GET listing endpoint also supports the HEAD HTTP method. Making a\nhead request to the endpoint results in an empty body and an additional\n`Recurly-Total-Records` header. This is a count of the total number of records\nthat the endpoint will return, taking into account the current filtering query\nparameters.\n\n## Limits\nIn order to provide a fast response time to all our customers, we may rate\nlimit excessive requests. By default, new Recurly sites have the following\nAPI rate limits:\n\n* Sandbox sites: 400 requests/min. All requests count towards the rate limit.\n* Production sites: 1,000 requests/min. Only GET requests count towards the rate limit.\n\nOnce your site moves into production mode, Recurly will only rate limit\nGET requests. New subscriptions, account modifications, and other requests\nusing POST, PUT, or DELETE methods will not count against your rate limit.\n\nThe rate limit is calculated over a sliding 5 minute window. This means a\nproduction site could make 4,000 requests within one minute and not hit\nthe rate limit so long as the site made less than 1,000 requests during\nthe prior 4 minutes.\n\nIf an API request exceeds the rate limit, the API will return a\n`429 Too Many Requests` HTTP status. If your business needs a higher\nlimit, please contact support.\n\nThe rate limit applied to your client can be determined with the\n`X-RateLimit-Limit` header, and the number of remaining requests is sent\nin the `X-RateLimit-Remaining` header. Finally, the `X-RateLimit-Reset`\nheader contains an integer value representing the time, measured in\nseconds since the UNIX Epoch, at which the request count will be reset.\n\n## Idempotent Requests\n\nRecurly supports idempotent requests via the `Idempotency-Key` header for\n`POST`, `PUT`, `PATCH`, and `DELETE` requests. This allows API clients to\nsafely retry these requests without risk of duplicate operations.\n\nWhen you send a request with an `Idempotency-Key` header, Recurly stores the\nresponse for **1 hour**. If you send an identical request (same key, method,\npath, and API key) within that window, Recurly replays the original response\nrather than processing a new one. The replay response includes an\n`Idempotency-Prior: true` header.\n\nIf a request with the same key is **already in flight** when a second arrives,\nthe server returns `409 Conflict` with `Recurly-Should-Retry: true` and a\n`Retry-After` header indicating how long to wait in seconds before retrying.\n\n> **Note:** `429 Too Many Requests` responses are intentionally **not** cached.\n> You may retry freely once your rate limit resets without risk of unintended\n> replay behavior.\n\nKeys must be **255 characters or fewer**. Keys exceeding this limit will\nreceive a `400 Bad Request` response. We recommend using a UUID v4 as your\nkey to guarantee uniqueness.\n\n> **SDK support:** Native `Idempotency-Key` management (automatic key\n> generation, retry handling, and replay detection) is currently supported only\n> in the **Ruby SDK**. When using other SDKs or raw HTTP clients, you must\n> supply and manage the `Idempotency-Key` header yourself.\n\n## Change Log\n\nA list of changes for this version can be found [in the changelog](https://recurly.com/developers/api/changelog.html#v2021-02-25---current-ga-version).\n",
    "version": "v2021-02-25"
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "x-tagGroups": [
    {
      "name": "Customers",
      "tags": [
        "Account",
        "Account Note",
        "Account Acquisition Info",
        "Billing Info",
        "Billing Infos",
        "Coupon Redemption",
        "Subscription",
        "Subscription Change",
        "Usage",
        "Shipping Address"
      ]
    },
    {
      "name": "Invoices and Payments",
      "tags": [
        "Purchase",
        "Invoice",
        "Line Item",
        "Credit Payment",
        "Transaction",
        "Revenue Recovery",
        "Gift Cards"
      ]
    },
    {
      "name": "Products and Promotions",
      "tags": [
        "Item",
        "Plan",
        "Add-on",
        "Measured Unit",
        "Coupon",
        "Unique Coupon Code",
        "Price Segment"
      ]
    },
    {
      "name": "Configuration",
      "tags": [
        "Site",
        "Custom Field Definition",
        "Shipping Method",
        "Dunning Campaigns",
        "Business Entities",
        "Automated Exports",
        "General Ledger Account",
        "Performance Obligations",
        "Invoice Templates"
      ]
    },
    {
      "name": "App Management",
      "tags": [
        "External Subscription",
        "External Invoice",
        "External Product",
        "External Account",
        "External Product Reference",
        "External Payment Phase"
      ]
    }
  ],
  "tags": [
    {
      "name": "Coupon",
      "description": "Coupons can either be single codes that easily allow mass distribution by many customers or bulk coupons that can generate many unique coupons that can allow for individual delivery and tracking."
    }
  ],
  "paths": {
    "/coupons": {
      "get": {
        "tags": [
          "Coupon"
        ],
        "operationId": "list_coupons",
        "summary": "List a site's coupons",
        "description": "See the [Pagination Guide](/developers/guides/pagination.html) to learn how to use pagination in the API and Client Libraries.",
        "parameters": [
          {
            "$ref": "#/components/parameters/accept_header"
          },
          {
            "$ref": "#/components/parameters/ids"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/order"
          },
          {
            "$ref": "#/components/parameters/sort_dates"
          },
          {
            "$ref": "#/components/parameters/filter_begin_time"
          },
          {
            "$ref": "#/components/parameters/filter_end_time"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of the site's coupons.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CouponList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid or unpermitted parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Incorrect site ID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-code-samples": [
          {
            "lang": "Node.js",
            "source": "const coupons = client.listCoupons({ params: { limit: 200 } })\n\nfor await (const coupon of coupons.each()) {\n  console.log(coupon.code)\n}\n"
          },
          {
            "lang": "Python",
            "source": "params = {\"limit\": 200}\ncoupons = client.list_coupons(params=params).items()\nfor coupon in coupons:\n    print(coupon.code)\n"
          },
          {
            "lang": ".NET",
            "source": "var optionalParams = new ListCouponsParams()\n{\n    Limit = 200\n};\nvar coupons = client.ListCoupons(optionalParams);\nforeach(Coupon coupon in coupons)\n{\n    Console.WriteLine(coupon.Code);\n}\n"
          },
          {
            "lang": "Ruby",
            "source": "params = {\n  limit: 200\n}\ncoupons = @client.list_coupons(params: params)\ncoupons.each do |coupon|\n  puts \"coupon: #{coupon.code}\"\nend\n"
          },
          {
            "lang": "Java",
            "source": "ListCouponsParams params = new ListCouponsParams();\nparams.setLimit(200); // Pull 200 records at a time\nfinal Pager<Coupon> coupons = client.listCoupons(params);\n\nfor (Coupon coupon : coupons) {\n    System.out.println(coupon.getCode());\n}\n"
          },
          {
            "lang": "PHP",
            "source": "$options = [\n  'params' => [\n    'limit' => 200\n  ]\n];\n$coupons = $client->listCoupons($options);\n\nforeach($coupons as $coupon) {\n  echo 'Coupon: ' . $coupon->getCode() . PHP_EOL;\n}\n"
          },
          {
            "lang": "Go",
            "source": "listParams := &recurly.ListCouponsParams{\n\tSort:  recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\ncoupons, err := client.ListCoupons(listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor coupons.HasMore() {\n\terr := coupons.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, coupon := range coupons.Data() {\n\t\tfmt.Printf(\"Coupon %3d: %s, %s\\n\",\n\t\t\ti,\n\t\t\tcoupon.Id,\n\t\t\tcoupon.Code,\n\t\t)\n\t}\n}"
          }
        ],
        "x-readme": {
          "code-samples": [
            {
              "language": "node",
              "code": "const coupons = client.listCoupons({ params: { limit: 200 } })\n\nfor await (const coupon of coupons.each()) {\n  console.log(coupon.code)\n}\n",
              "name": "Node.js"
            },
            {
              "language": "python",
              "code": "params = {\"limit\": 200}\ncoupons = client.list_coupons(params=params).items()\nfor coupon in coupons:\n    print(coupon.code)\n",
              "name": "Python"
            },
            {
              "language": "csharp",
              "code": "var optionalParams = new ListCouponsParams()\n{\n    Limit = 200\n};\nvar coupons = client.ListCoupons(optionalParams);\nforeach(Coupon coupon in coupons)\n{\n    Console.WriteLine(coupon.Code);\n}\n",
              "name": ".NET"
            },
            {
              "language": "ruby",
              "code": "params = {\n  limit: 200\n}\ncoupons = @client.list_coupons(params: params)\ncoupons.each do |coupon|\n  puts \"coupon: #{coupon.code}\"\nend\n",
              "name": "Ruby"
            },
            {
              "language": "java",
              "code": "ListCouponsParams params = new ListCouponsParams();\nparams.setLimit(200); // Pull 200 records at a time\nfinal Pager<Coupon> coupons = client.listCoupons(params);\n\nfor (Coupon coupon : coupons) {\n    System.out.println(coupon.getCode());\n}\n",
              "name": "Java"
            },
            {
              "language": "php",
              "code": "$options = [\n  'params' => [\n    'limit' => 200\n  ]\n];\n$coupons = $client->listCoupons($options);\n\nforeach($coupons as $coupon) {\n  echo 'Coupon: ' . $coupon->getCode() . PHP_EOL;\n}\n",
              "name": "PHP"
            },
            {
              "language": "go",
              "code": "listParams := &recurly.ListCouponsParams{\n\tSort:  recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\ncoupons, err := client.ListCoupons(listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor coupons.HasMore() {\n\terr := coupons.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, coupon := range coupons.Data() {\n\t\tfmt.Printf(\"Coupon %3d: %s, %s\\n\",\n\t\t\ti,\n\t\t\tcoupon.Id,\n\t\t\tcoupon.Code,\n\t\t)\n\t}\n}",
              "name": "Go"
            }
          ]
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://v3.recurly.com"
    },
    {
      "url": "https://v3.eu.recurly.com"
    }
  ],
  "components": {
    "parameters": {
      "accept_header": {
        "name": "Accept",
        "in": "header",
        "description": "The API version to use for this request, e.g. `application/vnd.recurly.v2021-02-25`. Requests without a versioned `Accept` header return a 406 response.",
        "required": true,
        "schema": {
          "default": "application/vnd.recurly.v2021-02-25",
          "type": "string",
          "enum": [
            "application/vnd.recurly.v2021-02-25",
            "application/vnd.recurly.v2021-02-25+json"
          ]
        }
      },
      "ids": {
        "name": "ids",
        "in": "query",
        "description": "Filter results by their IDs. Up to 200 IDs can be passed at once using\ncommas as separators, e.g. `ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6`.\n\n**Important notes:**\n\n* The `ids` parameter cannot be used with any other ordering or filtering\n  parameters (`limit`, `order`, `sort`, `begin_time`, `end_time`, etc)\n* Invalid or unknown IDs will be ignored, so you should check that the\n  results correspond to your request.\n* Records are returned in an arbitrary order. Since results are all\n  returned at once you can sort the records yourself.\n",
        "style": "form",
        "explode": false,
        "schema": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "limit": {
        "name": "limit",
        "in": "query",
        "description": "Limit number of records 1-200.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 20
        }
      },
      "order": {
        "name": "order",
        "in": "query",
        "description": "Sort order.",
        "schema": {
          "default": "desc",
          "type": "string",
          "enum": [
            "asc",
            "desc"
          ]
        }
      },
      "sort_dates": {
        "name": "sort",
        "in": "query",
        "description": "Sort field. You *really* only want to sort by `updated_at` in ascending\norder. In descending order updated records will move behind the cursor and could\nprevent some records from being returned.\n",
        "schema": {
          "default": "created_at",
          "type": "string",
          "enum": [
            "created_at",
            "updated_at"
          ]
        }
      },
      "filter_begin_time": {
        "name": "begin_time",
        "in": "query",
        "description": "Inclusively filter by begin_time when `sort=created_at` or `sort=updated_at`.\n**Note:** this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.\n",
        "schema": {
          "type": "string",
          "format": "date-time"
        }
      },
      "filter_end_time": {
        "name": "end_time",
        "in": "query",
        "description": "Inclusively filter by end_time when `sort=created_at` or `sort=updated_at`.\n**Note:** this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.\n",
        "schema": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "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"
      }
    },
    "schemas": {
      "CouponList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "title": "Object type",
            "description": "Will always be List."
          },
          "has_more": {
            "type": "boolean",
            "description": "Indicates there are more results on subsequent pages."
          },
          "next": {
            "type": "string",
            "description": "Path to subsequent page of results."
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Coupon"
            }
          }
        }
      },
      "Coupon": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "title": "Coupon ID",
            "readOnly": true
          },
          "object": {
            "type": "string",
            "title": "Object type",
            "readOnly": true
          },
          "code": {
            "type": "string",
            "title": "Coupon code",
            "description": "The code the customer enters to redeem the coupon."
          },
          "name": {
            "type": "string",
            "title": "Name",
            "description": "The internal name for the coupon."
          },
          "state": {
            "title": "State",
            "description": "Indicates if the coupon is redeemable, and if it is not, why.",
            "type": "string",
            "enum": [
              "expired",
              "maxed_out",
              "redeemable"
            ]
          },
          "max_redemptions": {
            "type": "integer",
            "title": "Max redemptions",
            "description": "A maximum number of redemptions for the coupon. The coupon will expire when it hits its maximum redemptions."
          },
          "max_redemptions_per_account": {
            "type": "integer",
            "title": "Max redemptions per account",
            "description": "Redemptions per account is the number of times a specific account can redeem the coupon. Set redemptions per account to `1` if you want to keep customers from gaming the system and getting more than one discount from the coupon campaign."
          },
          "unique_coupon_codes_count": {
            "type": "integer",
            "title": "Unique coupon codes count",
            "description": "When this number reaches `max_redemptions` the coupon will no longer be redeemable.",
            "readOnly": true
          },
          "unique_code_template": {
            "type": "string",
            "title": "Unique code template",
            "description": "On a bulk coupon, the template from which unique coupon codes are generated."
          },
          "unique_coupon_code": {
            "allOf": [
              {
                "$ref": "#/components/schemas/UniqueCouponCode"
              }
            ],
            "type": "object",
            "description": "Will be populated when the Coupon being returned is a `UniqueCouponCode`."
          },
          "duration": {
            "title": "Duration",
            "description": "- \"single_use\" coupons applies to the first invoice only.\n- \"temporal\" coupons will apply to invoices for the duration determined by the `temporal_unit` and `temporal_amount` attributes.\n",
            "type": "string",
            "enum": [
              "forever",
              "single_use",
              "temporal",
              "billing_periods"
            ]
          },
          "temporal_amount": {
            "type": "integer",
            "title": "Temporal amount",
            "description": "If `duration` is \"temporal\" than `temporal_amount` is an integer which is multiplied by `temporal_unit` to define the duration that the coupon will be applied to invoices for. When `temporal_unit` is \"billing_period\", this is the number of complete billing cycles."
          },
          "temporal_unit": {
            "title": "Temporal unit",
            "description": "The temporal unit for the coupon's duration. Used with temporal_amount to define how long the coupon applies. When temporal_unit is billing_period, the coupon applies for temporal_amount complete billing cycles rather than a fixed calendar duration. billing_period requires redemption_resource=subscription.",
            "type": "string",
            "enum": [
              "day",
              "month",
              "week",
              "year",
              "billing_period"
            ]
          },
          "free_trial_unit": {
            "title": "Free trial unit",
            "description": "Description of the unit of time the coupon is for. Used with `free_trial_amount` to determine the duration of time the coupon is for.",
            "type": "string",
            "enum": [
              "day",
              "month",
              "week",
              "billing_period"
            ]
          },
          "free_trial_amount": {
            "type": "integer",
            "title": "Free trial amount",
            "description": "Sets the duration of time the `free_trial_unit` is for.",
            "minimum": 1,
            "maximum": 9999
          },
          "applies_to_all_plans": {
            "type": "boolean",
            "title": "Applies to all plans?",
            "description": "The coupon is valid for all plans if true. If false then `plans` will list the applicable plans.",
            "default": true
          },
          "applies_to_all_items": {
            "type": "boolean",
            "title": "Applies to all items?",
            "description": "The coupon is valid for all items if true. If false then `items`\nwill list the applicable items.\n",
            "default": false
          },
          "applies_to_non_plan_charges": {
            "type": "boolean",
            "title": "Applied to all non-plan charges?",
            "description": "The coupon is valid for one-time, non-plan charges if true.",
            "default": false
          },
          "plans": {
            "type": "array",
            "title": "Plans",
            "description": "A list of plans for which this coupon applies. This will be `null` if `applies_to_all_plans=true`.",
            "items": {
              "$ref": "#/components/schemas/PlanMini"
            }
          },
          "items": {
            "type": "array",
            "title": "Items",
            "description": "A list of items for which this coupon applies. This will be\n`null` if `applies_to_all_items=true`.\n",
            "items": {
              "$ref": "#/components/schemas/ItemMini"
            }
          },
          "redemption_resource": {
            "title": "Redemption resource",
            "description": "Whether the discount is for all eligible charges on the account, or only a specific subscription.",
            "default": "account",
            "type": "string",
            "enum": [
              "account",
              "subscription"
            ]
          },
          "discount": {
            "$ref": "#/components/schemas/CouponDiscount"
          },
          "discount_application_mode": {
            "title": "Discount application mode",
            "description": "How the coupon's discount applies over the life of a redemption.\n- \"full_amount\": The discount reapplies each billing period for each subscription for as long as the redemption is active.\n- \"draw_down\": The discount amount acts as a budget drawn down against the redemption; with a time-limited duration the budget refills each discount period.\n",
            "default": "full_amount",
            "type": "string",
            "enum": [
              "full_amount",
              "draw_down"
            ]
          },
          "discount_periods": {
            "type": "integer",
            "title": "Discount periods",
            "description": "Number of discount periods for draw-down application mode with a time-limited duration. Required when discount_application_mode is draw_down and the duration is temporal. Minimum 1, maximum 9999.",
            "minimum": 1,
            "maximum": 9999
          },
          "coupon_type": {
            "title": "Coupon type (TODO: implement coupon generation)",
            "description": "Whether the coupon is \"single_code\" or \"bulk\". Bulk coupons will require a `unique_code_template` and will generate unique codes through the `/generate` endpoint.",
            "type": "string",
            "enum": [
              "bulk",
              "single_code"
            ]
          },
          "hosted_page_description": {
            "type": "string",
            "title": "Hosted Payment Pages description",
            "description": "This description will show up when a customer redeems a coupon on your Hosted Payment Pages, or if you choose to show the description on your own checkout page."
          },
          "invoice_description": {
            "type": "string",
            "title": "Invoice description",
            "description": "Description of the coupon on the invoice.",
            "maxLength": 255
          },
          "redeem_by": {
            "type": "string",
            "title": "Redeem by",
            "description": "The date and time the coupon will expire and can no longer be redeemed. Time is always 11:59:59, the end-of-day Pacific time. Null for bulk coupons configured with a relative redeem-by interval (see redeem_by_interval_unit and redeem_by_interval_amount).",
            "format": "date-time"
          },
          "redeem_by_interval_unit": {
            "title": "Redeem by interval unit",
            "description": "Unit of the relative redemption window. Bulk coupons only.",
            "readOnly": true,
            "type": "string",
            "enum": [
              "day",
              "week",
              "month",
              "year"
            ]
          },
          "redeem_by_interval_amount": {
            "type": "integer",
            "title": "Redeem by interval amount",
            "description": "For a bulk coupon with a relative redeem-by, the number of redeem_by_interval_unit intervals after a code's generation that it remains redeemable. Null unless the coupon uses a relative redeem-by.",
            "readOnly": true
          },
          "created_at": {
            "type": "string",
            "title": "Created at",
            "format": "date-time",
            "readOnly": true
          },
          "updated_at": {
            "type": "string",
            "title": "Last updated at",
            "format": "date-time",
            "readOnly": true
          },
          "expired_at": {
            "type": "string",
            "title": "Expired at",
            "description": "The date and time the coupon was expired early or reached its `max_redemptions`.",
            "format": "date-time"
          }
        }
      },
      "CouponDiscount": {
        "type": "object",
        "description": "Details of the discount a coupon applies. Will contain a `type`\nproperty and one of the following properties: `percent`, `fixed`, `trial`.\n",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "fixed",
              "free_trial",
              "percent"
            ]
          },
          "percent": {
            "description": "This is only present when `type=percent`.",
            "type": "integer"
          },
          "currencies": {
            "type": "array",
            "description": "This is only present when `type=fixed`.",
            "items": {
              "$ref": "#/components/schemas/CouponDiscountPricing"
            }
          },
          "trial": {
            "type": "object",
            "x-class-name": "CouponDiscountTrial",
            "description": "This is only present when `type=free_trial`.",
            "properties": {
              "unit": {
                "title": "Trial unit",
                "description": "Temporal unit of the free trial. When `billing_period`, `length` represents the number of billing cycles.",
                "type": "string",
                "enum": [
                  "day",
                  "month",
                  "week",
                  "billing_period"
                ]
              },
              "length": {
                "type": "integer",
                "title": "Trial length",
                "description": "Trial length measured in the units specified by the sibling `unit` property"
              }
            }
          }
        }
      },
      "CouponDiscountPricing": {
        "type": "object",
        "properties": {
          "currency": {
            "type": "string",
            "title": "Currency",
            "description": "3-letter ISO 4217 currency code.",
            "maxLength": 3
          },
          "amount": {
            "type": "number",
            "format": "float",
            "title": "Discount Amount",
            "description": "Value of the fixed discount that this coupon applies."
          }
        }
      },
      "ItemMini": {
        "type": "object",
        "title": "Item mini details",
        "description": "Just the important parts.",
        "properties": {
          "id": {
            "type": "string",
            "title": "Item ID",
            "maxLength": 13,
            "readOnly": true
          },
          "object": {
            "type": "string",
            "title": "Object type",
            "readOnly": true
          },
          "code": {
            "type": "string",
            "title": "Item code",
            "description": "Unique code to identify the item.",
            "pattern": "/^[a-z0-9_+-]+$/",
            "maxLength": 50
          },
          "state": {
            "title": "State",
            "description": "The current state of the item.",
            "readOnly": true,
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ]
          },
          "name": {
            "type": "string",
            "title": "Name",
            "description": "This name describes your item and will appear on the invoice when it's purchased on a one time basis.",
            "maxLength": 255
          },
          "description": {
            "type": "string",
            "title": "Description",
            "description": "Optional, description."
          }
        }
      },
      "PlanCode": {
        "type": "string",
        "title": "Plan code",
        "description": "Unique code to identify the plan. This is used in Hosted Payment Page URLs and in the invoice exports.",
        "pattern": "/^[a-z0-9_+-]+$/",
        "maxLength": 50
      },
      "PlanName": {
        "type": "string",
        "title": "Name",
        "description": "This name describes your plan and will appear on the Hosted Payment Page and the subscriber's invoice.",
        "maxLength": 255
      },
      "PlanMini": {
        "type": "object",
        "title": "Plan mini details",
        "description": "Just the important parts.",
        "properties": {
          "id": {
            "type": "string",
            "title": "Plan ID",
            "maxLength": 13,
            "readOnly": true
          },
          "object": {
            "type": "string",
            "title": "Object type",
            "readOnly": true
          },
          "code": {
            "$ref": "#/components/schemas/PlanCode"
          },
          "name": {
            "$ref": "#/components/schemas/PlanName"
          }
        }
      },
      "UniqueCouponCode": {
        "type": "object",
        "description": "A unique coupon code for a bulk coupon.",
        "properties": {
          "id": {
            "type": "string",
            "title": "Unique Coupon Code ID",
            "readOnly": true
          },
          "object": {
            "type": "string",
            "title": "Object type",
            "readOnly": true
          },
          "code": {
            "type": "string",
            "title": "Coupon code",
            "description": "The code the customer enters to redeem the coupon."
          },
          "state": {
            "title": "State",
            "description": "Indicates if the unique coupon code is redeemable or why not.",
            "type": "string",
            "enum": [
              "expired",
              "inactive",
              "maxed_out",
              "redeemable"
            ]
          },
          "bulk_coupon_id": {
            "type": "string",
            "title": "Bulk Coupon ID",
            "description": "The Coupon ID of the parent Bulk Coupon",
            "readOnly": true
          },
          "bulk_coupon_code": {
            "type": "string",
            "title": "Bulk Coupon code",
            "description": "The Coupon code of the parent Bulk Coupon"
          },
          "created_at": {
            "type": "string",
            "title": "Created at",
            "format": "date-time",
            "readOnly": true
          },
          "updated_at": {
            "type": "string",
            "title": "Updated at",
            "format": "date-time",
            "readOnly": true
          },
          "redeemed_at": {
            "type": "string",
            "title": "Redeemed at",
            "description": "The date and time the unique coupon code was redeemed.",
            "format": "date-time",
            "readOnly": true
          },
          "expired_at": {
            "type": "string",
            "title": "Expired at",
            "description": "The date and time the coupon was expired early or reached its `max_redemptions`.",
            "format": "date-time"
          },
          "redeem_by_date": {
            "type": "string",
            "title": "Redeem by",
            "description": "Absolute expiry computed and stored at code-generation time. Set only for Window (relative redeem-by) coupons. Null for Anytime coupons and Specific Date coupons — those resolve expiry from the parent coupon's redeem_by at redemption time, not at code-generation time.",
            "format": "date-time",
            "readOnly": true
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "type": {
            "title": "Type",
            "type": "string",
            "enum": [
              "bad_request",
              "immutable_subscription",
              "internal_server_error",
              "invalid_api_key",
              "invalid_api_version",
              "invalid_content_type",
              "invalid_permissions",
              "invalid_token",
              "missing_feature",
              "not_found",
              "rate_limited",
              "service_not_available",
              "simultaneous_request",
              "tax_service_error",
              "transaction",
              "unauthorized",
              "unavailable_in_api_version",
              "unknown_api_version",
              "validation"
            ]
          },
          "message": {
            "type": "string",
            "title": "Message"
          },
          "params": {
            "type": "array",
            "title": "Parameter specific errors",
            "items": {
              "type": "object",
              "properties": {
                "param": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}
````

# Sibling pages

* [Create a new coupon](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/create_coupon.md)
* [Fetch a coupon](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/get_coupon.md)
* [Update an active coupon](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/update_coupon.md)
* [Expire a coupon](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/deactivate_coupon.md)
* [Restore an inactive coupon](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/restore_coupon.md)