Account2

Addresses4

Adjustments3

API root1

Businesses4

Checkout domains4

Client tokens4

Countries1

Currencies1

Customer portals1

Customers6

Discount groups4

Discounts4

Event types1

Events1

IP addresses1

Metrics9

Notification logs1

Notification settings5

Notifications3

Payment methods3

Prices4

Pricing preview1

Products4

Reports4

Settings18

Simulation run events3

Simulation runs3

Simulation types1

Simulations4

Subscription history1

Subscriptions11

Transactions7

Verifications2

Webhooks

Addresses3

Adjustments2

API keys6

Businesses3

Client tokens3

Customers3

Discount groups2

Discounts3

Payment methods2

Payouts2

Prices3

Products3

Reports2

Subscriptions9

Transactions10

Discounts

Create a discount

Changed on Jul 9, 2026

Creates a new discount.

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

post/discounts

Request

Base URL
https://sandbox-api.paddle.com
Auth
HTTP bearer

Request body

idstring

Unique Paddle ID for this discount, prefixed with dsc_.

status'active' | 'archived'

Whether this entity can be used in Paddle.

descriptionstring required

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

enabled_for_checkoutboolean

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

codestring

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

type'flat' | 'flat_per_seat' | 'percentage' required

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

mode'standard' | 'custom'

Discount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard.

amountstring 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.

currency_code'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF' | 'HKD' | 'SGD' | 'SEK' | 'ARS' | 'BRL' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'HUF' | 'ILS' | 'INR' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RUB' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'VND' | 'ZAR'

Supported three-letter ISO 4217 currency code.

recurboolean

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

maximum_recurring_intervalsinteger nullable

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.

usage_limitinteger nullable

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.

Paddle checks this limit when a discount is applied to a checkout or transaction, comparing it against times_used at that moment. As times_used only increments when a transaction completes, checkouts that are open at the same time can each pass this check, so in some cases a discount may be redeemed more times than this limit allows.

restrict_toDiscountRestrictTo[] nullable

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_atstring date-time

RFC 3339 datetime string.

custom_dataCustomData

Your own structured key-value data.

times_usedinteger

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.

Incremented when a transaction completes, rather than when a discount is applied to a checkout. See usage_limit for how this affects enforcement of the limit.

created_atstring date-time

RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.

updated_atstring date-time

RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.

discount_group_idstring

Unique Paddle ID for this discount group, prefixed with dsg_.

Example request

{
  "id": "dsc_01gv5kpg05xp104ek2fmgjwttf",
  "expires_at": "2024-10-12T07:20:50.52Z",
  "custom_data": {
    "customer_reference_id": "abcd1234"
  },
  "created_at": "2024-10-12T07:20:50.52Z",
  "updated_at": "2024-10-13T07:20:50.52Z",
  "discount_group_id": "dsg_01js2gqehzccfkywgx1jk2mtsp",
  "import_meta": {
    "external_id": "9b95b0b8-e10f-441a-862e-1936a6d818ab",
    "imported_from": "paddle_classic"
  }
}

Response

The request has succeeded and a new resource has been created as a result.

Example response

{
  "data": {
    "id": "dsc_01gv5kpg05xp104ek2fmgjwttf",
    "expires_at": "2024-10-12T07:20:50.52Z",
    "custom_data": {
      "customer_reference_id": "abcd1234"
    },
    "discount_group_id": "dsg_01js2gqehzccfkywgx1jk2mtsp",
    "created_at": "2024-10-12T07:20:50.52Z",
    "updated_at": "2024-10-13T07:20:50.52Z",
    "import_meta": {
      "external_id": "9b95b0b8-e10f-441a-862e-1936a6d818ab",
      "imported_from": "paddle_classic"
    }
  },
  "meta": {
    "request_id": "b15ec92e-8688-40d4-a04d-f44cbec93355"
  }
}

Changes

Jul 9, 2026v1e1ac347eb3c5 Revision changes
- warning
  added the new CLP enum value to the // response property for the response status
- warning
  added the new PEN enum value to the // response property for the response status
- info
  added the new CLP enum value to the request property /
- info
  added the new PEN enum value to the request property /
Feb 2, 2026v19ba8be0f2006 Revision changes
- breaking
  request body became required
- breaking
  added to the request property allOf list
- breaking
  added to the request property allOf list
- breaking
  added to the request property allOf list
- breaking
  added to the request property allOf list
- breaking
  added to the request property allOf list
- breaking
  added to the request property allOf list
- breaking
  the request property became not nullable
- breaking
  the request property became not nullable
- breaking
  the request property became not nullable
- breaking
  removed the enum value custom of the request property
- breaking
  removed the enum value flat of the request property
- breaking
  removed the enum value flat_per_seat of the request property
- breaking
  removed the enum value percentage of the request property
- breaking
  removed the enum value standard of the request property
- breaking
  removed subschema #2 from the request property oneOf list
- breaking
  removed subschema #2 from the request property oneOf list
- breaking
  removed subschema #2 from the request property oneOf list
- breaking
  removed subschema #2 from the request property oneOf list
- breaking
  removed subschema #2 from the request property oneOf list
- breaking
  the request property type changed from string to no type
- breaking
  the request property type changed from string to no type
- breaking
  response property data/maximum_recurring_intervals list-of-types was widened by adding types null to media type application/json of response 201
- breaking
  response property data/restrict_to list-of-types was widened by adding types null to media type application/json of response 201
- breaking
  response property data/usage_limit list-of-types was widened by adding types null to media type application/json of response 201
- breaking
  the / response's property type changed from string to no type, and format from date-time to no format for status
- breaking
  the / response's property type changed from string to no type for status
- breaking
  the / response's property type changed from string to no type for status
- breaking
  the / response's property type changed from string to no type for status
- breaking
  the / response's property type changed from string to no type, and format from date-time to no format for status
- breaking
  the response's property type changed from object to no type for status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- warning
  removed the optional property / from the response with the status
- info
  added the new optional request property
- info
  the request optional property became not read-only
- info
  added subschema #2 to the request property anyOf list
- info
  added subschema #2 to the request property anyOf list
- info
  added subschema #2 to the request property anyOf list
- info
  added subschema #2 to the request property anyOf list
- info
  added subschema #2 to the request property anyOf list
- info
  request property list-of-types was widened by adding types null to media type application/json
- info
  request property list-of-types was widened by adding types null to media type application/json
- info
  request property list-of-types was widened by adding types null to media type application/json
- info
  removed the pattern ^dsc_[a-z\d]{26}$ from the request property
- info
  removed the enum value active of the request read-only property status
- info
  removed the enum value archived of the request read-only property status
- info
  the response optional property / became not read-only for the status
- info
  added to the response property allOf list for the response status
- info
  added to the / response property allOf list for the response status
- info
  added to the / response property allOf list for the response status
- info
  added to the / response property allOf list for the response status
- info
  added to the / response property allOf list for the response status
- info
  added to the / response property allOf list for the response status
- info
  added subschema #2 to the / response property anyOf list for the response status
- info
  added subschema #2 to the / response property anyOf list for the response status
- info
  added subschema #2 to the / response property anyOf list for the response status
- info
  added subschema #2 to the / response property anyOf list for the response status
- info
  added subschema #2 to the / response property anyOf list for the response status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  removed the active enum value from the / response property for the response status
- info
  removed the archived enum value from the / response property for the response status
- info
  removed the custom enum value from the / response property for the response status
- info
  removed the standard enum value from the / response property for the response status
- info
  removed subschema #2 from the / response property oneOf list for the response status
- info
  removed subschema #2 from the / response property oneOf list for the response status
- info
  removed subschema #2 from the / response property oneOf list for the response status
- info
  removed subschema #2 from the / response property oneOf list for the response status
- info
  removed subschema #2 from the / response property oneOf list for the response status
- info
  the / response's property pattern ^dsc_[a-z\d]{26}$ was removed for the status
- info
  added the required property / to the response with the status

Operation history (9 revisions)