Paddle Billing

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

Query Parameters


Return entities after the specified Paddle ID when working with paginated endpoints. Used in the URL in responses for list operations.


Return entities that match the discount code. Use a comma-separated list to specify multiple discount codes.


Return only the IDs specified. Use a comma-separated list to get multiple entities.


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.


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.


Return entities that match the specified status. Use a comma-separated list to specify multiple status values.



Represents a discount entity.


Unique Paddle ID for this discount, prefixed with dsc_.


Whether this entity can be used in Paddle. expired and used are set automatically by Paddle.


Short description for this discount for your reference. Not shown to customers.


Whether this discount can be applied by a customer at checkout.

codestring or null

Unique code that customers can use to apply this discount at checkout. Use letters and numbers only, up to 16 characters. Paddle generates a random 10-character code if a code is not provided and enabled_for_checkout is true.


Type of discount.


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 or null

Supported three-letter ISO 4217 currency code. Required where discount type is flat or flat_per_seat.


Whether this discount applies for multiple billing periods.

maximum_recurring_intervalsinteger or null

Amount of subscription billing periods that this discount recurs for. Requires recur. null if this discount recurs forever.

usage_limitinteger or null

Maximum amount of times this discount can be used. This is an overall limit, rather than a per-customer limit. null if this discount can be used an unlimited amount of times.

restrict_toarray[string] or null

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_atstring<date-time> or null

RFC 3339 datetime string of when this discount expires. Discount can no longer be applied after this date has elapsed. null if this discount can be applied forever.

custom_dataobject or null

Your own structured key-value data.


How many times this discount has been redeemed. Automatically incremented by Paddle when an order completes.


RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.


RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.

import_metaobject or null

Import information for this entity. null if this entity is not imported.


Information about this response.


Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.


Keys used for working with paginated results.