Docs

List discounts

Returns a paginated list of discounts.

GET /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 or expired.

Requires discount.read permission.

Query parameters

idarray
Return only the IDs specified. Use a comma-separated list to get multiple entities.
afterstring
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_pageinteger
Default: 50

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
includearray
Include related entities in the response. Use a comma-separated list to specify multiple entities.
Values
  • discount_group
    Include an object for the discount group entity related to this discount.
codearray
Return entities that match the discount code. Use a comma-separated list to specify multiple discount codes.
order_bystring
Default: id[DESC]

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.

statusarray
Default: active
Return entities that match the specified status. Use a comma-separated list to specify multiple status values.
Values
  • 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.
modestring
Return entities that match the specified mode.
Values
  • 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.
discount_group_idarray
Return entities related to the specified discount group. Use a comma-separated list to specify multiple discount group IDs.

Response (200)

dataarrayrequired
idstringrequired
Example: dsc_01gv5kpg05xp104ek2fmgjwttf
Unique Paddle ID for this discount, prefixed with dsc_.
Pattern: ^dsc_[a-z\d]{26}$
statusstringrequired
Default: active
Whether this entity can be used in Paddle.
Values
  • active
    Entity is active and can be used.
  • archived
    Entity is archived, so can't be used.
descriptionstringrequired
Short description for this discount for your reference. Not shown to customers.
Length: 1–500
enabled_for_checkoutbooleanrequired
Default: true
Whether this discount can be redeemed by customers at checkout (true) or not (false).
codestring | nullrequired
Unique code that customers can use to apply this discount at checkout. Use letters and numbers only, up to 32 characters. Not case-sensitive.
Length: 1–32
Pattern: ^[a-zA-Z0-9]{1,32}$
typestringrequired
Type of discount. Determines how this discount impacts the checkout or transaction total.
Values
  • 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%.
modestringrequired
Default: standard
Discount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard.
Values
  • 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.
amountstringrequired
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_codestring | nullrequired
Supported three-letter ISO 4217 currency code.
Values
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • 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
recurbooleanrequired
Default: false
Whether this discount applies for multiple subscription billing periods (true) or not (false).
maximum_recurring_intervalsinteger | nullrequired

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_limitinteger | nullrequired

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_toarray | nullrequired
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_atstring (date-time) | nullrequired
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string.
custom_dataobject | nullrequired
Example: {"customer_reference_id":"abcd1234"}
Your own structured key-value data.
times_usedintegerrequired

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_idstring | nullrequired
Example: dsg_01js2gqehzccfkywgx1jk2mtsp
Unique Paddle ID for this discount group, prefixed with dsg_.
Pattern: ^dsg_[a-z\d]{26}$
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
import_metaobject | nullrequired
Import information for this entity. null if this entity is not imported.
external_idstring | null
Example: 9b95b0b8-e10f-441a-862e-1936a6d818ab
Reference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example: paddle_classic
Name of the platform or provider where this entity was imported from.
Length: 1–200
discount_groupobject
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.
idstringrequired
Example: dsg_01js2gqehzccfkywgx1jk2mtsp
Unique Paddle ID for this discount group, prefixed with dsg_.
Pattern: ^dsg_[a-z\d]{26}$
namestringrequired
Unique name of this discount group, typically something short and memorable for categorization. Not shown to customers.
Length: 1–500
statusstringrequired
Whether this entity can be used in Paddle.
Values
  • active
    Entity is active and can be used.
  • archived
    Entity is archived, so can't be used.
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
import_metaobject | nullrequired
Import information for this entity. null if this entity is not imported.
external_idstring | null
Example: 9b95b0b8-e10f-441a-862e-1936a6d818ab
Reference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example: paddle_classic
Name of the platform or provider where this entity was imported from.
Length: 1–200
metaobjectrequired
Information about this response.
request_idstringrequired
Example: b15ec92e-8688-40d4-a04d-f44cbec93355
Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
paginationobjectrequired
Keys used for working with paginated results.
per_pageintegerrequired
Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
nextstring (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_morebooleanrequired
Whether this response has another page.
estimated_totalinteger
Example: 999
Estimated number of entities for this response.
Response
{
  "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
    }
  }
}

Was this page helpful?