Skip to main content
POST
/
discounts
Create a discount
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    description: 'Seasonal sale',
    type: 'percentage',
    amount: '10',
    enabled_for_checkout: true,
    recur: true,
    maximum_recurring_intervals: 3,
    expires_at: '2024-12-03T00:00:00Z'
  })
};

fetch('https://api.paddle.com/discounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "data": {
    "id": "dsc_01hv6scyf7qdnzcdq01t2y8dx4",
    "status": "active",
    "description": "Seasonal sale",
    "enabled_for_checkout": true,
    "code": "SEWRGPB9WY",
    "type": "percentage",
    "mode": "standard",
    "amount": "10",
    "currency_code": null,
    "recur": true,
    "maximum_recurring_intervals": 3,
    "usage_limit": null,
    "restrict_to": null,
    "expires_at": "2024-12-03T00:00:00Z",
    "times_used": 0,
    "custom_data": null,
    "import_meta": null,
    "created_at": "2024-04-11T14:36:14.695Z",
    "updated_at": "2024-04-11T14:36:14.695Z"
  },
  "meta": {
    "request_id": "1681f87f-9c36-4557-a1da-bbb622afa0cc"
  }
}

Authorizations

​
Authorization
string
header
required

Requests are authenticated with API keys. Provide your API key as a Bearer token in the Authorization header.

API keys are assigned permissions, granting them access to entities and operations. Each endpoint may require one or more permissions, defined with the x-permissions extension. Values for include parameters may require specific permissions as defined in the x-enum-permissions extension. See all available permissions in the permission schema or documentation.

Get an API key and select the permissions you need from the Paddle dashboard under Paddle > Developer Tools > Authentication.

Body

application/json

Represents a discount entity when creating discounts.

​
description
string
required

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

Required string length: 1 - 500
​
type
enum<string>
required

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

Available options:
flat,
flat_per_seat,
percentage
​
amount
string
required

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.

​
enabled_for_checkout
boolean
default:true

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

​
code
string | null

Unique code that customers can use to redeem this discount at checkout. Use letters and numbers only, up to 32 characters. Not case-sensitive.

If omitted and enabled_for_checkout is true, Paddle generates a random 10-character code.

Required string length: 1 - 32
​
mode
enum<string>
default:standard

Discount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard. If omitted, defaults to standard.

Available options:
standard,
custom
​
currency_code
enum<string> | null

Supported three-letter ISO 4217 currency code. Required where discount type is flat or flat_per_seat.

Available options:
USD,
EUR,
GBP,
JPY,
AUD,
CAD,
CHF,
HKD,
SGD,
SEK,
ARS,
BRL,
CNY,
COP,
CZK,
DKK,
HUF,
ILS,
INR,
KRW,
MXN,
NOK,
NZD,
PLN,
RUB,
THB,
TRY,
TWD,
UAH,
VND,
ZAR
Required string length: 3
​
recur
boolean
default:false

Whether this discount applies for multiple subscription billing periods (true) or not (false). If omitted, defaults to false.

​
maximum_recurring_intervals
integer | 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.

Required range: x >= 1
​
usage_limit
integer | 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.

Required range: x >= 1
​
restrict_to
string[] | 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_at
string<date-time> | 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.

Example:

"2024-10-12T07:20:50.52Z"

​
custom_data
Custom data · object

Your own structured key-value data.

Example:
{ "customer_reference_id": "abcd1234" }

Response

OK

​
data
Discount · object
required

Represents a discount entity.

​
meta
Meta · object
required

Information about this response.