Paddle Billing


Discount entities describe percentage or amount-based discounts for transactions. They're sometimes called coupons or promo codes.

Discounts let you reduce a transaction total by a percentage, a flat amount per transaction, or a flat amount per unit on a transaction.

Discount entities hold information like:

  • How the discount reduces the total of the transaction
  • Whether the discount is one-time or recurring
  • When the discount is valid to
  • Which items in your catalog the discount applies to
  • Whether this discount can be applied by customers using a code

Discounts work with prices, transactions, checkouts, and subscriptions.

By default, discounts apply to the entire value of a transaction. You can link discounts to price entities to limit them to certain prices. For example, you can create a discount for subscription plans that won't work on other items.

Use discount codes to let your customers apply discounts themselves at checkout, or pass a discount to a checkout to apply it automatically.

Discounts don't have to have codes. They can be applied manually to transactions as part of the sales process.

Learn how to create different kinds of discount and pre-fill them on a checkout. See: Run promotions and discounts

There's no delete operation for discounts. Use the update a discount operation to archive discounts when you no longer need them. See: Delete entities



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 customers at checkout.

codestring or null

Unique code that customers can use to apply this discount at checkout.


Type of discount. Determines how this discount impacts the transaction total.


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 subscription 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.


Name of the platform where this entity was imported from.

external_idstring or null

Reference or identifier for this entity from the solution where it was imported from.

List discounts
Create a discount
Get a discount
Update a discount