# POST /discounts

**Create a discount**

Creates a new discount.

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

**Required permissions:** `discount.write`

## Request body

- `description`: string (required) — Short description for this discount for your reference. Not shown to customers. (Length: 1–500)
- `enabled_for_checkout`: boolean — Whether this discount can be redeemed by customers at checkout (`true`) or not (`false`).
- `code` — 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.
- `type`: string (required) — Type of discount. Determines how this discount impacts the checkout or transaction total.
- `mode`: string — Discount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard. If omitted, defaults to `standard`.
- `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.
- `currency_code` — Supported three-letter ISO 4217 currency code. Required where discount type is `flat` or `flat_per_seat`.
- `recur`: boolean — Whether this discount applies for multiple subscription billing periods (`true`) or not (`false`). If omitted, defaults to `false`.
- `maximum_recurring_intervals` — 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_limit` — 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_to` — 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_at` — 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_data` — Your own structured key-value data.
- `discount_group_id` — Paddle ID for the discount group related to this discount, prefixed with `dsg_`. `null` if not in a discount group.

### Request example

```json
{
  "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 (201)

- `data`: object (required) — Represents a discount entity.
  - `id`: string (required) — Unique Paddle ID for this discount, prefixed with `dsc_`. (pattern: `^dsc_[a-z\d]{26}$`)
  - `status`: string (required) — Whether this entity can be used in Paddle.
  - `description`: string (required) — Short description for this discount for your reference. Not shown to customers. (Length: 1–500)
  - `enabled_for_checkout`: boolean (required) — Whether this discount can be redeemed by customers at checkout (`true`) or not (`false`).
  - `code` (required) — Unique code that customers can use to redeem this discount at checkout. Not case-sensitive.
  - `type`: string (required) — Type of discount. Determines how this discount impacts the checkout or transaction total.
  - `mode`: string (required) — Discount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard.
  - `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.
  - `currency_code` (required) — Supported three-letter ISO 4217 currency code. Required where discount type is `flat` or `flat_per_seat`.
  - `recur`: boolean (required) — Whether this discount applies for multiple subscription billing periods (`true`) or not (`false`).
  - `maximum_recurring_intervals` (required) — 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_limit` (required) — 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_to` (required) — 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_at` (required) — 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_data` (required)
  - `times_used`: integer (required) — 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_id` (required) — Paddle ID for the discount group related to this discount, prefixed with `dsg_`. `null` if not in a discount group.
  - `created_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
  - `updated_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
  - `import_meta` (required) — Import information for this entity. `null` if this entity is not imported.
- `meta`: object (required) — Information about this response.
  - `request_id`: string (required) — Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.

### Response example

```json
{
  "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"
  }
}
```