Create and manage discounts

Discounts let you reduce the amount that a customer has to pay. You may run discounts as part of promotions, or as a way to incentivize customers to upgrade or buy more.

How it works

Discounts are applied to the total value of the checkout or transaction. The type of discount determines how the total is impacted.

Redemptions

A transaction can be discounted in two ways:

• Customer applying a discount code

  During checkout, the customer can enter a discount code. You can set whether discounts can be applied at checkout or whether they're turned off when you initialize Paddle.js or open the checkout.

• Applying a discount to a transaction directly

  You can open a checkout with a discount already applied, or add a discount to any transaction that hasn't yet been billed.

You can't apply a discount to a transaction that's already been billed. You should use an adjustment to refund or credit a transaction instead.

Paddle counts when discounts are redeemed so you can keep track of how many times a discount has been used. A redemption counts when a transaction is completed, or on the initial application against a subscription. If a discount is present on a transaction created for subscription renewals, midcycle changes, and one-time charges, this doesn't count as a redemption.

Rules and limits

Discounts in Paddle are flexible and powerful. You can set specific rules and restrictions on how they're applied to a transaction or across multiple transactions to give you the freedom to run promotions and discounts in a way that works for you.

Recurring discounts

By default, discounts are one-time. This means they're only applied on the first transaction or checkout that you add them to.

You can create recurring discounts which apply to the current transaction and future transactions where a customer has a subscription. Discounts can recur forever, or for a number of billing periods you specify.

When recurring discounts start applying to transactions depends on if a subscription has a free trial period:

• With a free trial

  The discount only applies once the trial period ends. For example, a recurring discount set for 4 billing periods applies to the first paid billing period after the trial and the next 3 renewals.

• Without a free trial

  The discount applies immediately. For example, a recurring discount set for 4 billing periods applies to the initial transaction and the next 3 renewals.

In both cases, the discount applies to any subscription changes within those periods.

Usage limits

You can prevent discounts from being valid after certain conditions have been met.

• Time-based

  Once a set date has passed, the discount can no longer be applied to checkouts or transactions.

• Amount-based

  Once a discount has been redeemed a certain amount of times, the discount can no longer be applied to checkouts or transactions.

Amount-based limits are a total limit for the discount, rather than a per-customer limit.

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

Item restrictions

By default, a discount applies to all items on a transaction. You may want a discount to only be applied to specific items at checkout. For example, only annual plans, or specific regional price points.

To achieve this, you can provide a list of:

• Products

  Restricts the discount to apply to all prices for that product.

• Prices

  Restricts the discount to only apply to that specific price for a product.

The discount applies only to the individual item it's restricted to. You can't limit a discount to apply to the full total only when set items are present.

Checkout restrictions

Customers can apply discounts to checkouts using a discount code. You can assign a discount code, or can have Paddle automatically generate one for you.

However, you may not want customers to be able to apply a discount at checkout. This is useful when you want to control who has access to a discount, like with non-transferable custom discounts only valid for particular customers. To achieve this, you can set a discount to be turned off at checkout.

If discounts aren't enabled for use at checkout, Paddle won't automatically generate a code. The discount can only be applied by passing the discount to the checkout or transaction directly using its id.

You can also use the showAddDiscounts parameter to determine whether Paddle Checkout presents customers with the option to enter a discount. See Pass checkout settings

Currency restrictions

Discounts for a flat amount or per-seat amount are currency-specific. They have a currency and can only be applied to transactions in the same currency.

For example, you can't apply a flat amount type discount (type: flat) with a currency of USD (currency_code: USD) to a transaction with the currency of GBP (currency_code: GBP).

Non-catalog discounts use the transaction's currency. A new transaction must have a currency_code if the discount being applied is for a flat amount or per-seat amount.

Discount groups

You can create groups to assign discounts under. Discounts could be categorized by usage or team, like:

• Marketing and new customer prospects that would be used by the marketing team.
• Retention or loyalty that would be used by customer service or operational teams.
• Seasonal promotions or campaigns like Black Friday or Cyber Monday.

This makes your discounts more easily identifiable and easier to manage as your catalog grows or as discounts become redundant.

Non-catalog discounts

When you create a discount, it gets added to your discount catalog. These discounts can be used against any transaction, and at checkout by default. However, you may want to apply a discount to a single transaction which isn't recorded in your catalog.

You should use:

Non-catalog discounts can only be applied directly to a transaction and can't be added by customers using Paddle Checkout. They won't show in the Paddle dashboard or when listing discounts through the API.

You can also turn on checkout recovery to offer discounts to recover abandoned checkouts. These discounts are non-catalog, non-transferable, and only applicable to the transaction that's recovered.

Before you begin

Set your default payment link

To open a checkout with a discount, you'll need to first:

• Set your default payment link under Paddle > Checkout > Checkout settings > Default payment link.
• Get your default payment link domain approved, if you're working with the live environment.

We recommend starting the domain approval early in your integration process, so your domains are approved for when you're ready to go live.

Create a discount

Create discounts to add them to your catalog for usage against checkouts and transactions.

We recommend creating discounts using the Paddle dashboard.

Apply a discount

Customers can apply discounts to a checkout by using a discount code during their transaction. You can also automatically apply a discount to a checkout when you open it in your frontend, or directly to a transaction using the API.

You can apply non-catalog discounts directly to transactions through the API. Non-catalog discounts are intended as custom, one-off discounts which aren't part of your catalog. They can't be applied at checkout by customers, or applied automatically to a checkout when opened.

enabled_for_checkout must be true against the discount entity to apply it to a checkout. Non-catalog discounts always have enabled_for_checkout set to false.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1Paddle.Checkout.open({
2  settings: {
3    theme: "light",
4    locale: "en"
5  },
6  discountId: "dsc_01gp0ynsntfpyw2spd2md1wqx1",
7  items: [
8    {
9      priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
10      quantity: 1
11    },
12    {
13      priceId: 'pri_01gm82kny0ad1tk358gxmsq87m',
14      quantity: 1
15    },
16    {
17      priceId: 'pri_01gm82v81g69n9hdb0v9sw6j40',
18      quantity: 1
19    }
20  ]

See how many times a discount has been redeemed

You may want to understand how many times a discount has been redeemed to understand its performance, track how many usages it has left, or expose it to customers to promote a sense of urgency against a limit to the discount.

You can see this against a discount entity when you fetch or list discounts as times_used. If a discount has a limit, you can compare this to the value of usage_limit to calculate and show how many redemptions are left.

Send a GET request to the /discount/{discount_id} endpoint.

Response

This example is a discount entity with a usage limit for how many times this discount can be redeemed as usage_limit. It shows how many times the discount has been redeemed as times_used.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "dsc_01jxw1svzg816ptbzkzf7w12rw",
4    "status": "active",
5    "description": "25% off (All)",
6    "enabled_for_checkout": true,
7    "code": "138ETPB5NN",
8    "type": "percentage",
9    "amount": "25",
10    "currency_code": null,
11    "recur": false,
12    "maximum_recurring_intervals": null,
13    "usage_limit": 100,
14    "times_used": 79,
15    "restrict_to": null,
16    "expires_at": null,
17    "mode": "standard",
18    "custom_data": null,
19    "import_meta": null,
20    "discount_group_id": "dsg_01jxyv6jh22m3bav2e3srk1a2t",

Create a discount group

Discounts can be grouped together to make them easier to manage. For example, you might create a group for your Black Friday discounts, and then add all your Black Friday discounts to the group.

You can group your discounts in two steps:

1. Build a request

   Build a request that includes the name of the discount group.

2. Create the group

   Send the request to create the discount group. Paddle creates it and returns the id of the discount group.

Build request

Request

This example creates a discount group called "Black Friday 2024."

1
2
3
1{
2  "name": "Black Friday 2024"
3}

Create the group

Send a POST request to the /discount-groups endpoint with the request you built.

Response

If successful, Paddle responds with a copy of the new discount group entity. You should take the id of the discount group if you want to add a discount to it.

1
2
3
4
5
6
7
8
9
10
11
12
13
1{
2  "data": {
3    "id": "dsg_01js2gqehzccfkywgx1jk2mtsp",
4    "status": "active",
5    "name": "Black Friday 2024",
6    "import_meta": null,
7    "created_at": "2024-11-28T14:36:14.695Z",
8    "updated_at": "2024-11-28T14:36:14.695Z"
9  },
10  "meta": {
11    "request_id": "1681f87f-9c36-4557-a1da-bbb622afa0cc"
12  }
13}

Add a discount to a discount group

You can add a new or existing discount to a discount group. This example covers updating an existing discount to add it to a discount group. You can do so in two steps:

1. Build request

   Build a request with the discount group you want to add the discount to.

2. Add the discount to the group

   Send the request to update the discount with the new discount group.

Build request

Request

This example updates a discount called "All orders (10% off)" to add it to the "Black Friday 2024" discount group.

1
2
3
1{
2  "discount_group_id": "dsg_01js2gqehzccfkywgx1jk2mtsp"
3}

Add the discount to the group

Send a PATCH request to the /discounts/{discount_id} endpoint with the request you built.

Response

If successful, Paddle responds with a copy of the created or updated discount entity, containing the discount_group_id field.

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
12    "recur": true,
13    "maximum_recurring_intervals": 3,
14    "usage_limit": null,
15    "restrict_to": [
16      "pro_01gsz4t5hdjse780zja8vvr7jg",
17      "pro_01gsz4s0w61y0pp88528f1wvvb"
18    ],
19    "expires_at": "2024-12-03T00:00:00Z",
20    "times_used": 0,
21    "discount_group_id": "dsg_01js2gqehzccfkywgx1jk2mtsp",
22    "custom_data": null,
23    "import_meta": null,
24    "created_at": "2024-11-28T14:36:14.695Z",
25    "updated_at": "2024-11-28T14:38:12.331Z"
26  },
27  "meta": {
28    "request_id": "dd850364-99f7-4e27-bb1e-0a477bdb320b"
29  }
30}

Common errors

These are the most common errors you might encounter when working with discounts. See a full list at Discount errors.

Events

Related pages