Discounts

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

Attributes

idstring

Unique Paddle ID for this discount, prefixed with dsc_.

statusstring

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

external_idstring

An optional reference ID from the originating system. Used when an discount is imported. Can contain any number of characters excluding white space.

descriptionstring

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

enabled_for_checkoutboolean

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.

typestring

Type of discount.

amountstring

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.

recurboolean

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.

times_usedinteger

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

created_atstring<date-time>

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

updated_atstring<date-time>

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

List discounts

gethttps://api.paddle.com/discounts

Create a discount

posthttps://api.paddle.com/discounts

Get a discount

gethttps://api.paddle.com/discounts/{discount_id}

Update a discount

patchhttps://api.paddle.com/discounts/{discount_id}