For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Docs

Create a discount

Creates a new discount.

POST /discounts

Creates a new discount.

If successful, your response includes a copy of the new discount entity.

Requires discount.write permission.

Request body

descriptionstringrequired
Short description for this discount for your reference. Not shown to customers.
Length: 1–500
enabled_for_checkoutboolean
Default: true
Whether this discount can be redeemed by customers at checkout (true) or not (false).
codestring | 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.

Length: 1–32
Pattern: ^[a-zA-Z0-9]{1,32}$
typestringrequired
Type of discount. Determines how this discount impacts the checkout or transaction total.
Values
  • flat
    Discounts a checkout or transaction by a flat amount, for example -$100. Requires currency_code.
  • flat_per_seat
    Discounts a checkout or transaction by a flat amount per unit, for example -$100 per user. Requires currency_code.
  • percentage
    Discounts a checkout or transaction by a percentage of the total, for example -10%. Maximum 100%.
modestring
Default: standard
Discount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard. If omitted, defaults to standard.
Values
  • standard
    Standard discount. Can be considered part of your catalog and reused across transactions and subscriptions easily.
  • custom
    Non-catalog discount. Can be created via the API, or by Paddle for checkout recovery discounts. Not returned when listing or shown in the Paddle dashboard.
amountstringrequired
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 | null
Supported three-letter ISO 4217 currency code. Required where discount type is flat or flat_per_seat.
Values
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • HKD
    Hong Kong Dollar
  • SGD
    Singapore Dollar
  • SEK
    Swedish Krona
  • ARS
    Argentine Peso
  • BRL
    Brazilian Real
  • CLP
    Chilean Peso
  • CNY
    Chinese Yuan
  • COP
    Colombian Peso
  • CZK
    Czech Koruna
  • DKK
    Danish Krone
  • HUF
    Hungarian Forint
  • ILS
    Israeli Shekel
  • INR
    Indian Rupee
  • KRW
    South Korean Won
  • MXN
    Mexican Peso
  • NOK
    Norwegian Krone
  • NZD
    New Zealand Dollar
  • PEN
    Peruvian Sol
  • PLN
    Polish Zloty
  • RUB
    Russian Ruble
  • THB
    Thai Baht
  • TRY
    Turkish Lira
  • TWD
    New Taiwan Dollar
  • UAH
    Ukrainian Hryvnia
  • VND
    Vietnamese Dong
  • ZAR
    South African Rand
recurboolean
Default: false
Whether this discount applies for multiple subscription billing periods (true) or not (false). If omitted, defaults to false.
maximum_recurring_intervalsinteger | 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.

Min: 1
usage_limitinteger | 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.

Min: 1
restrict_toarray | 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.
Items: unique
expires_atstring (date-time) | null
Example: 2024-10-12T07:20:50.52Z

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 | null
Example: {"customer_reference_id":"abcd1234"}
Your own structured key-value data.
discount_group_idstring | null
Example: dsg_01js2gqehzccfkywgx1jk2mtsp
Paddle ID for the discount group related to this discount, prefixed with dsg_. null if not in a discount group.
Pattern: ^dsg_[a-z\d]{26}$

Response (201)

dataobjectrequired
Represents a discount entity.
idstringrequired
Example: dsc_01gv5kpg05xp104ek2fmgjwttf
Unique Paddle ID for this discount, prefixed with dsc_.
Pattern: ^dsc_[a-z\d]{26}$
statusstringrequired
Default: active
Whether this entity can be used in Paddle.
Values
  • active
    Entity is active and can be used.
  • archived
    Entity is archived, so can't be used.
descriptionstringrequired
Short description for this discount for your reference. Not shown to customers.
Length: 1–500
enabled_for_checkoutbooleanrequired
Default: true
Whether this discount can be redeemed by customers at checkout (true) or not (false).
codestring | nullrequired
Unique code that customers can use to redeem this discount at checkout. Not case-sensitive.
Length: 1–32
Pattern: ^[a-zA-Z0-9]{1,32}$
typestringrequired
Type of discount. Determines how this discount impacts the checkout or transaction total.
Values
  • flat
    Discounts a checkout or transaction by a flat amount, for example -$100. Requires currency_code.
  • flat_per_seat
    Discounts a checkout or transaction by a flat amount per unit, for example -$100 per user. Requires currency_code.
  • percentage
    Discounts a checkout or transaction by a percentage of the total, for example -10%. Maximum 100%.
modestringrequired
Default: standard
Discount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard.
Values
  • standard
    Standard discount. Can be considered part of your catalog and reused across transactions and subscriptions easily.
  • custom
    Non-catalog discount. Can be created via the API, or by Paddle for checkout recovery discounts. Not returned when listing or shown in the Paddle dashboard.
amountstringrequired
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 | nullrequired
Supported three-letter ISO 4217 currency code. Required where discount type is flat or flat_per_seat.
Values
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • HKD
    Hong Kong Dollar
  • SGD
    Singapore Dollar
  • SEK
    Swedish Krona
  • ARS
    Argentine Peso
  • BRL
    Brazilian Real
  • CLP
    Chilean Peso
  • CNY
    Chinese Yuan
  • COP
    Colombian Peso
  • CZK
    Czech Koruna
  • DKK
    Danish Krone
  • HUF
    Hungarian Forint
  • ILS
    Israeli Shekel
  • INR
    Indian Rupee
  • KRW
    South Korean Won
  • MXN
    Mexican Peso
  • NOK
    Norwegian Krone
  • NZD
    New Zealand Dollar
  • PEN
    Peruvian Sol
  • PLN
    Polish Zloty
  • RUB
    Russian Ruble
  • THB
    Thai Baht
  • TRY
    Turkish Lira
  • TWD
    New Taiwan Dollar
  • UAH
    Ukrainian Hryvnia
  • VND
    Vietnamese Dong
  • ZAR
    South African Rand
recurbooleanrequired
Default: false
Whether this discount applies for multiple subscription billing periods (true) or not (false).
maximum_recurring_intervalsinteger | nullrequired

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.

Min: 1
usage_limitinteger | nullrequired

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.

Min: 1
restrict_toarray | nullrequired
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.
Items: unique
expires_atstring (date-time) | nullrequired
Example: 2024-10-12T07:20:50.52Z

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 | nullrequired
Example: {"customer_reference_id":"abcd1234"}
Your own structured key-value data.
times_usedintegerrequired

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.

discount_group_idstring | nullrequired
Example: dsg_01js2gqehzccfkywgx1jk2mtsp
Paddle ID for the discount group related to this discount, prefixed with dsg_. null if not in a discount group.
Pattern: ^dsg_[a-z\d]{26}$
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
import_metaobject | nullrequired
Import information for this entity. null if this entity is not imported.
external_idstring | null
Example: 9b95b0b8-e10f-441a-862e-1936a6d818ab
Reference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example: paddle_classic
Name of the platform or provider where this entity was imported from.
Length: 1–200
metaobjectrequired
Information about this response.
request_idstringrequired
Example: b15ec92e-8688-40d4-a04d-f44cbec93355
Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
Request
{
  "description": "All orders (10% off)",
  "type": "percentage",
  "amount": "10",
  "code": "BF10OFF",
  "enabled_for_checkout": true,
  "recur": true,
  "maximum_recurring_intervals": 3,
  "expires_at": "2024-12-03T00:00:00Z",
  "discount_group_id": "dsg_01js2gqehzccfkywgx1jk2mtsp"
}
Response
{
  "data": {
    "id": "dsc_01hv6scyf7qdnzcdq01t2y8dx4",
    "status": "active",
    "description": "All orders (10% off)",
    "enabled_for_checkout": true,
    "code": "BF10OFF",
    "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,
    "discount_group_id": "dsg_01js2gqehzccfkywgx1jk2mtsp",
    "custom_data": null,
    "import_meta": null,
    "created_at": "2024-11-28T14:36:14.695Z",
    "updated_at": "2024-11-28T14:36:14.695Z"
  },
  "meta": {
    "request_id": "1681f87f-9c36-4557-a1da-bbb622afa0cc"
  }
}

Was this page helpful?