Run promotions and discounts
Attract new customers and entice existing ones to upgrade using discounts. They're sometimes called promotions or coupons.
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.
Head to Paddle > Catalog > Discounts and click New discount, or edit an existing discount using the … menu next to the discount in the list.
Fill out the details to create or edit your discount.
Set the "Recurring discount" slider off.
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.
Head to Paddle > Catalog > Discounts and click New discount, or edit an existing discount using the … menu next to the discount in the list.
Fill out the details to create or edit your discount.
Set the Recurring discount slider on, then choose either:
- Until further notice: the discount should recur forever
- For a custom number of billing periods: the discount should recur 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.
Head to Paddle > Catalog > Discounts and click New discount, or edit an existing discount using the … menu next to the discount in the list.
Fill out the details to create or edit your discount.
Check the Set an expiration date for the discount box, then enter a date and time.
Paddle supports over 200 countries and territories, so dates and times are UTC. You can search online to convert your local time to UTC.
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.
Head to Paddle > Catalog > Discounts and click New discount, or edit an existing discount using the … menu next to the discount in the list.
Fill out the details to create or edit your discount.
Set the Limit discount to selected products slider on, then use the products and prices dropdowns to choose which products and prices this discount applies to.
Add a product, then leave the prices box blank to set a discount to apply to all prices for that product.
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.
To see how many times a discount has been redeemed, send a GET request to the /discounts/{discount_id}
endpoint.
Paddle ID of the discount entity to work with.
Response
If successful, Paddle responds with the complete discount entity, including times_used
.
12345678910111213141516171819201{
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",
Paddle also returns the maximum number of times a discount can be redeemed as the usage_limit
. You can take times_used
from the usage_limit
to calculate how many redemptions are left.
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:
Build a request that includes the name of the discount group.
Send the request to create the discount group. Paddle creates it and returns the
id
of the discount group.Make a call to create or update a discount using the
id
from the discount group as thediscount_group_id
.
Build request
Build a request that includes the name of the discount group.
Make it descriptive, short, and memorable to help you identify the purpose of the discount group. This isn't shown to customers.
Name of this discount group.
Request
This example creates a discount group called "Black Friday 2024."
1231{
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.
123456789101112131{
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
Provide a discount_group_id
field when creating or updating a discount.
The value of this field is the id
of the discount group you want to add the discount to.
Paddle ID for the discount group related to this discount, prefixed with dsg_
.
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.
Send the request you built to the /discounts
endpoint. When creating a discount, you must include all other required fields at a minimum.
Request
This example creates a discount called "All orders (10% off)" and adds it to the "Black Friday 2024" discount group.
12345678910111{
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}
Response
If successful, Paddle responds with a copy of the created discount entity, containing the discount_group_id
field.
12345678910111213141516171819201{
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,
Send the request you built to the /discounts/{discount_id}
endpoint.
Request
This example updates a discount called "All orders (10% off)" to add it to the "Black Friday 2024" discount group.
1231{
2 "discount_group_id": "dsg_01js2gqehzccfkywgx1jk2mtsp"
3}
Response
If successful, Paddle responds with a copy of the created or updated discount entity, containing the discount_group_id
field.
1213141516171819202122232425262728293012 "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}