> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# GET /discounts

**List discounts**

Returns a paginated list of discounts. Use the query parameters to page through results.

By default, Paddle returns discounts that are `active`. Use the `status` query parameter to return discounts that are archived.

**Required permissions:** `discount.read`

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | array | optional | Return only the IDs specified. Use a comma-separated list to get multiple entities. |
| `after` | string | optional | Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations. |
| `per_page` | integer | optional | Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.

Default: `50`; Maximum: `200`. (Max: 200; default: `50`) |
| `include` | array | optional | Include related entities in the response. Use a comma-separated list to specify multiple entities. |
| `code` | array | optional | Return entities that match the discount code. Use a comma-separated list to specify multiple discount codes. |
| `order_by` | string | optional | Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.

Valid fields for ordering: `created_at` and `id`. (default: `"id[DESC]"`) |
| `status` | array | optional | Return entities that match the specified status. Use a comma-separated list to specify multiple status values. (default: `["active"]`) |
| `mode` | string | optional | Return entities that match the specified mode. |
| `discount_group_id` | array | optional | Return entities related to the specified discount group. Use a comma-separated list to specify multiple discount group IDs. |

Values for `include`:

- `discount_group` — Include an object for the discount group entity related to this discount.

Values for `status`:

- `active` — Return discounts where the status is `active`. Returned discounts are active and can be used.
- `archived` — Return discounts where the status is `archived`. Returned discounts are archived, so can't be used.

Values for `mode`:

- `standard` — Return entities where the mode is `standard`. Returned entities can be considered part of your catalog and reused across transactions and subscriptions easily.
- `custom` — Return entities where the mode is `custom`. Returned entities can be considered non-catalog. They can be created via the API, or by Paddle for checkout recovery discounts. Not shown in the Paddle dashboard.

## Response (200)

- `data`: array (required)
  - `id`: string (required) — Unique Paddle ID for this discount, prefixed with `dsc_`. (pattern: `^dsc_[a-z\d]{26}$`)
  - `status`: string (required) — Whether this entity can be used in Paddle. (default: `"active"`)
    - `active` — Entity is active and can be used.
    - `archived` — Entity is archived, so can't be used.
  - `description`: string (required) — Short description for this discount for your reference. Not shown to customers. (Length: 1–500)
  - `enabled_for_checkout`: boolean (required) — Whether this discount can be redeemed by customers at checkout (`true`) or not (`false`). (default: `true`)
  - `code`: string | null (required) — Unique code that customers can use to redeem this discount at checkout. Not case-sensitive. (Length: 1–32; pattern: `^[a-zA-Z0-9]{1,32}$`)
  - `type`: string (required) — Type of discount. Determines how this discount impacts the checkout or transaction total.
    - `flat` — Discounts a checkout or transaction by a flat amount, for example -$100. Requires `currency_code`.
    - `flat_per_seat` — Discounts a checkout or transaction by a flat amount per unit, for example -$100 per user. Requires `currency_code`.
    - `percentage` — Discounts a checkout or transaction by a percentage of the total, for example -10%. Maximum 100%.
  - `mode`: string (required) — Discount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard. (default: `"standard"`)
    - `standard` — Standard discount. Can be considered part of your catalog and reused across transactions and subscriptions easily.
    - `custom` — Non-catalog discount. Can be created via the API, or by Paddle for checkout recovery discounts. Not returned when listing or shown in the Paddle dashboard.
  - `amount`: string (required) — Amount to discount by. For `percentage` discounts, must be an amount between `0.01` and `100`. For `flat` and `flat_per_seat` discounts, amount in the lowest denomination for a currency.
  - `currency_code`: string | null (required) — Supported three-letter ISO 4217 currency code. Required where discount type is `flat` or `flat_per_seat`.
    - `USD` — United States Dollar
    - `EUR` — Euro
    - `GBP` — Pound Sterling
    - `JPY` — Japanese Yen
    - `AUD` — Australian Dollar
    - `CAD` — Canadian Dollar
    - `CHF` — Swiss Franc
    - `HKD` — Hong Kong Dollar
    - `SGD` — Singapore Dollar
    - `SEK` — Swedish Krona
    - `ARS` — Argentine Peso
    - `BRL` — Brazilian Real
    - `CLP` — Chilean Peso
    - `CNY` — Chinese Yuan
    - `COP` — Colombian Peso
    - `CZK` — Czech Koruna
    - `DKK` — Danish Krone
    - `HUF` — Hungarian Forint
    - `ILS` — Israeli Shekel
    - `INR` — Indian Rupee
    - `KRW` — South Korean Won
    - `MXN` — Mexican Peso
    - `NOK` — Norwegian Krone
    - `NZD` — New Zealand Dollar
    - `PEN` — Peruvian Sol
    - `PLN` — Polish Zloty
    - `RUB` — Russian Ruble
    - `THB` — Thai Baht
    - `TRY` — Turkish Lira
    - `TWD` — New Taiwan Dollar
    - `UAH` — Ukrainian Hryvnia
    - `VND` — Vietnamese Dong
    - `ZAR` — South African Rand
  - `recur`: boolean (required) — Whether this discount applies for multiple subscription billing periods (`true`) or not (`false`). (default: `false`)
  - `maximum_recurring_intervals`: integer | null (required) — Number of subscription billing periods that this discount recurs for. Requires `recur`. `null` if this discount recurs forever.

Subscription renewals, midcycle changes, and one-time charges billed to a subscription aren't considered a redemption. `times_used` is not incremented in these cases. (Min: 1)
  - `usage_limit`: integer | null (required) — Maximum number of times this discount can be redeemed. This is an overall limit for this discount, rather than a per-customer limit. `null` if this discount can be redeemed an unlimited amount of times.

Paddle counts a usage as a redemption on a checkout, transaction, or the initial application against a subscription. Transactions created for subscription renewals, midcycle changes, and one-time charges aren't considered a redemption. (Min: 1)
  - `restrict_to`: array | null (required) — Product or price IDs that this discount is for. When including a product ID, all prices for that product can be discounted. `null` if this discount applies to all products and prices. (Items: unique)
  - `expires_at`: string (date-time) | null (required) — RFC 3339 datetime string of when this discount expires. Discount can no longer be redeemed after this date has elapsed. `null` if this discount can be redeemed forever.

Expired discounts can't be redeemed against transactions or checkouts, but can be applied when updating subscriptions.
  - `custom_data`: object | null (required) — Your own structured key-value data.
  - `times_used`: integer (required) — How many times this discount has been redeemed. Automatically incremented by Paddle.

Paddle counts a usage as a redemption on a checkout, transaction, or subscription. Transactions created for subscription renewals, midcycle changes, and one-time charges aren't considered a redemption.
  - `discount_group_id`: string | null (required) — Paddle ID for the discount group related to this discount, prefixed with `dsg_`. `null` if not in a discount group. (pattern: `^dsg_[a-z\d]{26}$`)
  - `created_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
  - `updated_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
  - `import_meta`: object | null (required) — Import information for this entity. `null` if this entity is not imported.
    - `external_id`: string | null — Reference or identifier for this entity from the provider where it was imported from. (Length: 1–200)
    - `imported_from`: string (required) — Name of the platform or provider where this entity was imported from. (Length: 1–200)
  - `discount_group`: object — Discount group for this discount. Returned when the `include` parameter is used with the `discount_group` value and the discount has a `discount_group_id`.
    - `id`: string (required) — Unique Paddle ID for this discount group, prefixed with `dsg_`. (pattern: `^dsg_[a-z\d]{26}$`)
    - `name`: string (required) — Unique name of this discount group, typically something short and memorable for categorization. Not shown to customers. (Length: 1–500)
    - `status`: string (required) — Whether this entity can be used in Paddle.
      - `active` — Entity is active and can be used.
      - `archived` — Entity is archived, so can't be used.
    - `created_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
    - `updated_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
    - `import_meta`: object | null (required) — Import information for this entity. `null` if this entity is not imported.
      - `external_id`: string | null — Reference or identifier for this entity from the provider where it was imported from. (Length: 1–200)
      - `imported_from`: string (required) — Name of the platform or provider where this entity was imported from. (Length: 1–200)
- `meta`: object (required) — Information about this response.
  - `request_id`: string (required) — Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
  - `pagination`: object (required) — Keys used for working with paginated results.
    - `per_page`: integer (required) — Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
    - `next`: string (uri) (required) — URL containing the query parameters of the original request, along with the `after` parameter that marks the starting point of the next page. Always returned, even if `has_more` is `false`.
    - `has_more`: boolean (required) — Whether this response has another page.
    - `estimated_total`: integer — Estimated number of entities for this response.

For datasets with 100,000 or fewer matches, returns the exact count. For datasets with more than 100,000 matches, returns `100001` to indicate that more than 100,000 entities match. Returns `-1` when counting is skipped or couldn't be calculated.

Use `has_more` and `next` to page through all results rather than relying on `estimated_total` for an exact count.

### Response example

```json
{
  "data": [
    {
      "id": "dsc_01gtgztp8fpchantd5g1wrksa3",
      "status": "active",
      "description": "Black Friday 2024",
      "enabled_for_checkout": true,
      "code": "BF10OFF",
      "type": "percentage",
      "mode": "standard",
      "amount": "10",
      "currency_code": "USD",
      "recur": false,
      "maximum_recurring_intervals": null,
      "usage_limit": 1000,
      "restrict_to": null,
      "expires_at": "2024-12-03T00:00:00Z",
      "times_used": 0,
      "discount_group_id": "dsg_01js2gqehzccfkywgx1jk2mtsp",
      "custom_data": null,
      "import_meta": null,
      "created_at": "2024-11-28T14:36:14.695Z",
      "updated_at": "2024-11-28T14:36:14.695Z"
    },
    {
      "id": "dsc_01gtf15svsqzgp9325ss4ebmwt",
      "status": "active",
      "description": "Introductory offer: $10 off per user for Pro",
      "enabled_for_checkout": true,
      "code": "10OFFPRO",
      "type": "flat_per_seat",
      "mode": "standard",
      "amount": "1000",
      "currency_code": "USD",
      "recur": false,
      "maximum_recurring_intervals": null,
      "usage_limit": null,
      "restrict_to": [
        "pri_01gsz8x8sawmvhz1pv30nge1ke"
      ],
      "expires_at": "2023-12-05T15:00:00Z",
      "times_used": 0,
      "discount_group_id": null,
      "custom_data": null,
      "import_meta": null,
      "created_at": "2023-03-01T16:48:04.473Z",
      "updated_at": "2023-12-05T14:27:26.844Z"
    },
    {
      "id": "dsc_01gtgraak4chyhnp47rrdv89ad",
      "status": "active",
      "description": "Nonprofit discount",
      "enabled_for_checkout": true,
      "code": "98XFAUR91R",
      "type": "percentage",
      "mode": "standard",
      "amount": "10",
      "currency_code": null,
      "recur": true,
      "maximum_recurring_intervals": 3,
      "usage_limit": null,
      "restrict_to": [],
      "expires_at": null,
      "times_used": 6,
      "discount_group_id": null,
      "custom_data": null,
      "import_meta": null,
      "created_at": "2023-03-02T08:51:44.356Z",
      "updated_at": "2023-11-07T14:37:41.459Z"
    },
    {
      "id": "dsc_01h83xenpcfjyhkqr4x214m02x",
      "status": "active",
      "description": "Nonprofit discount",
      "enabled_for_checkout": false,
      "code": null,
      "type": "percentage",
      "mode": "standard",
      "amount": "10",
      "currency_code": null,
      "recur": true,
      "maximum_recurring_intervals": null,
      "usage_limit": null,
      "restrict_to": [
        "pri_01h83xenpcfjyhkqr4x214m02x"
      ],
      "expires_at": null,
      "times_used": 0,
      "discount_group_id": null,
      "custom_data": null,
      "import_meta": null,
      "created_at": "2023-08-18T08:51:07.596Z",
      "updated_at": "2023-08-18T09:05:17.05Z"
    }
  ],
  "meta": {
    "request_id": "d8f286a6-e049-4a6e-8fa8-a6f145ac3ecf",
    "pagination": {
      "per_page": 50,
      "next": "https://api.paddle.com/discounts?after=dsc_01h83xenpcfjyhkqr4x214m02x",
      "has_more": false,
      "estimated_total": 4
    }
  }
}
```