Run promotions and discounts

Discounts let you reduce the amount that a customer has to pay by a percentage (-10%) or fixed amount (-$10) for an item, transaction, or subscription. They're sometimes called promotions or coupons.

Using discounts, you can:

• Create one-time, or recurring discounts.
• Set up discount codes that customers can apply during checkout.
• Restrict discounts to some products, like subscription plans or addons.
• Limit how many times a discount can be applied.
• Run limited time promos by setting an end date.

You can pass a discount ID or code to Paddle.js to automatically apply it to a checkout — no need for customers to enter a discount code.

Create a one-time discount

One-time discounts are only applied to the current transaction. They don't apply to future transactions. They're good for encouraging customers to sign up without impacting future revenue.

One-time discounts can't be applied to existing subscriptions.

Create a recurring discount

Recurring discounts are applied to the current transaction and transactions for future billing periods. Recurring discounts can recur forever, or only for a set number of billing periods.

Create a limited-time discount

Limited-time discounts can only be used up until a certain date. They have an expiry date and cannot be redeemed after the expiry date. They're ideal for running limited-time promotions, like Black Friday or holiday sales.

Limit discounts to certain products

Discounts may apply to all products in your catalog, or you can limit them to specific products and prices. For example, you may discount your annual plans but not your monthly plans.

See how many times a discount has been redeemed

Paddle keeps track of the amount of times that a discount has been redeemed. This means it's been applied to a checkout or transaction. You might like to display this figure in internal dashboards, or even pull through to your commercial website to generate a sense of popularity or urgency.

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_01gt218xfk7yztpvgmcazkes83",
4    "status": "active",
5    "description": "10% off",
6    "enabled_for_checkout": false,
7    "code": "ILWIWKG7EB",
8    "type": "percentage",
9    "amount": "10",
10    "currency_code": null,
11    "recur": false,
12    "maximum_recurring_intervals": null,
13    "usage_limit": 100,
14    "restrict_to": [
15      "pri_01gsz8z1q1n00f12qt82y31smh",
16      "pri_01gsz8s48pyr4mbhvv2xfggesg"
17    ],
18    "expires_at": null,
19    "times_used": 55,
20    "created_at": "2023-02-24T15:39:38.867Z",

Group your discounts

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 three steps:

1. Build a request

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

2. Create a discount group

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

3. Add discounts to the group

   Make a call to create or update a discount using the id from the discount group as the discount_group_id.

Build request

Request

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

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

Create a discount 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 for the next step.

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 discounts to a group

Once you have a discount group, you can add discounts to it. Discounts can be assigned a discount group through the API when creating or updating a discount.

Build request

If you don't know the id for a discount group, you can list your discount groups to find it.

Send request

Where to send your request depends on if you're creating a new discount or updating an existing one.

1
2
3
4
5
6
7
8
9
10
11
1{
2  "description": "All orders (10% off)",
3  "type": "percentage",
4  "amount": "10",
5  "code": "BF10OFF",
6  "enabled_for_checkout": true,
7  "recur": true,
8  "maximum_recurring_intervals": 3,
9  "expires_at": "2024-12-03T00:00:00Z",
10  "discount_group_id": "dsg_01js2gqehzccfkywgx1jk2mtsp"
11}

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_01hv6scyf7qdnzcdq01t2y8dx4",
4    "status": "active",
5    "description": "All orders (10% off)",
6    "enabled_for_checkout": true,
7    "code": "BF10OFF",
8    "type": "percentage",
9    "mode": "standard",
10    "amount": "10",
11    "currency_code": null,
12    "recur": true,
13    "maximum_recurring_intervals": 3,
14    "usage_limit": null,
15    "restrict_to": null,
16    "expires_at": "2024-12-03T00:00:00Z",
17    "times_used": 0,
18    "discount_group_id": "dsg_01js2gqehzccfkywgx1jk2mtsp",
19    "custom_data": null,
20    "import_meta": null,

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

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}

Related pages