PApaddlehq
Discounts

Update a discount

Changed on

Updates a discount using its ID.

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

To update a checkout recovery discount, configure your checkout recovery settings in the dashboard.

patch/discounts/{discount_id}

Request

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

Path parameters

discount_idstring required

Paddle ID of the discount entity to work with.

Request body

idstring

Unique Paddle ID for this discount, prefixed with dsc_.

status'active' | 'archived'

Whether this entity can be used in Paddle.

descriptionstring

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'

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

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

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.

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

  • v1bbc0c72039c8Revision changes
    • warning

      changed the pattern of the path request parameter discount_id from ^dsc_[a-z\d]{26}(?:@dscrev_[a-z\d]{26})?$ to ^dsc_[a-z\d]{26}$

  • v1e1ac347eb3c5Revision 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 /