---
title: "List discounts"
method: GET
path: "/discounts"
tags: ["Discounts"]
---

# List discounts

`GET /discounts`

## Request

- Base URL: `https://sandbox-api.paddle.com`
- URL: `https://sandbox-api.paddle.com/discounts`
- Auth: HTTP bearer

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.

## Query parameters

- `id` string[]
- `after` string
- `per_page` integer
- `include` DiscountIncludeEnum[]
- `code` string[]
- `order_by` string
- `status` DiscountStatusQueryEnum[]
- `mode` 'standard' | 'custom'
- `discount_group_id` string[]

## Headers

- `Skip-Count` string

## Response `200`

The request has succeeded.

- object
  - `data` DiscountIncludes[], required
    - `id` string, required: Unique Paddle ID for this discount, prefixed with `dsc_`.
    - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle.
    - `description` string, required: Short description for this discount for your reference. Not shown to customers.
    - `enabled_for_checkout` boolean, required: Whether this discount can be redeemed by customers at checkout (`true`) or not (`false`).
    - `code` string, required: Unique code that customers can use to apply this discount at checkout. Use letters and numbers only, up to 32 characters. Not case-sensitive.
    - `type` 'flat' | 'flat_per_seat' | 'percentage', required: Type of discount. Determines how this discount impacts the checkout or transaction total.
    - `mode` 'standard' | 'custom', required: Discount mode. Standard discounts are considered part of your catalog and are 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` 'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF' | 'HKD' | 'SGD' | 'SEK' | 'ARS' | 'BRL' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'HUF' | 'ILS' | 'INR' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RUB' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'VND' | 'ZAR', required: Supported three-letter ISO 4217 currency code.
    - `recur` boolean, required: Whether this discount applies for multiple subscription billing periods (`true`) or not (`false`).
    - `maximum_recurring_intervals` integer, nullable, 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.
    - `usage_limit` integer, nullable, 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. Paddle checks this limit when a discount is applied to a checkout or transaction, comparing it against `times_used` at that moment. As `times_used` only increments when a transaction completes, checkouts that are open at the same time can each pass this check, so in some cases a discount may be redeemed more times than this limit allows.
    - `restrict_to` DiscountRestrictTo[], nullable, 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.
    - `expires_at` string, date-time, required: RFC 3339 datetime string.
    - `custom_data` CustomData, 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. Incremented when a transaction completes, rather than when a discount is applied to a checkout. See `usage_limit` for how this affects enforcement of the limit.
    - `discount_group_id` string, required: Unique Paddle ID for this discount group, prefixed with `dsg_`.
    - `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, nullable, required: Import information for this entity. `null` if this entity is not imported.
      - `external_id` string: Reference or identifier for this entity from the provider where it was imported from.
      - `imported_from` string, required: Name of the platform or provider where this entity was imported from.
    - `discount_group` DiscountGroup: Represents a discount group entity.
      - `id` string, required: Unique Paddle ID for this discount group, prefixed with `dsg_`.
      - `name` string, required: Unique name of this discount group, typically something short and memorable for categorization. Not shown to customers.
      - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle.
      - `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, nullable, required: Import information for this entity. `null` if this entity is not imported.
        - `external_id` string: Reference or identifier for this entity from the provider where it was imported from.
        - `imported_from` string, required: Name of the platform or provider where this entity was imported from.
  - `meta` PaginatedMeta, 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` Pagination, 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.

## Other responses

- `default`: An unexpected error response.

## Changes

- **2026-07-09** (v1) `e1ac347eb3c5`: 2 warning, 1 info
  - added the new `CLP` enum value to the `data/items/currency_code/anyOf[subschema #1: Currency code]/` response property for the response status `200`
  - added the new `PEN` enum value to the `data/items/currency_code/anyOf[subschema #1: Currency code]/` response property for the response status `200`
  - added the new optional `header` request parameter `Skip-Count`
- **2026-02-02** (v1) `9ba8be0f2006`: 14 breaking, 1 warning, 47 info
  - for the `query` request parameter `status`, default value `active` was added
  - response property `data/items/maximum_recurring_intervals` list-of-types was widened by adding types `null` to media type `application/json` of response `200`
  - response property `data/items/restrict_to` list-of-types was widened by adding types `null` to media type `application/json` of response `200`
  - response property `data/items/usage_limit` list-of-types was widened by adding types `null` to media type `application/json` of response `200`
  - …58 more
- **2025-05-07** (v1) `aeb882657253`: 2 info
  - added the new optional `query` request parameter `mode`
  - added the optional property `data/items/mode` to the response with the `200` status
- …earlier changes not shown

[Operation history](https://skmtc.dev/paddlehq/apis/paddle-api/changes/discounts/get.md)

---

[API](https://skmtc.dev/paddlehq/apis/paddle-api.md) - [All operations](https://skmtc.dev/paddlehq/apis/paddle-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paddlehq/apis/paddle-api/revisions/bbc0c72039c8?raw)