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

There's no delete operation for discounts. Use the update a discount operation to archive discounts when you no longer need them. To learn more, see Delete entities

Create or a update a discount

Create a transaction

Attributes

idstring

Unique Paddle ID for this discount, prefixed with dsc_.

statusstring

Whether this entity can be used in Paddle.

descriptionstring

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

enabled_for_checkoutboolean

Whether this discount can be redeemed by customers at checkout (true) or not (false).

codestring or null

Unique code that customers can use to redeem this discount at checkout. Not case-sensitive.

typestring

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

modestring

Discount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard.

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 subscription billing periods (true) or not (false).

maximum_recurring_intervalsinteger or null

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

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.

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 redeemed after this date has elapsed. null if this discount can be redeemed forever.

Expired discounts can't be redeemed against transactions or checkouts, but can be applied when updating subscriptions.

custom_dataobject or null

Your own structured key-value data.

times_usedinteger

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.

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.

import_metaobject or null

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

imported_fromstring

Name of the platform or provider where this entity was imported from.

external_idstring or null

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

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}