> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Discounts
> Create promotional codes to drive conversions, run campaigns, and reward customers with percentage discounts across one‑time and subscription purchases.
Discount codes let you run targeted promotions and incentives. Create percentage-based discounts, set limits and expirations, restrict to products, and apply them seamlessly in checkout.
Apply one or more stacked codes during hosted checkout with `discount_codes` and UI controls.
Check if a discount is valid by its ID.
Look up and validate a discount using its code name (e.g., "SAVE20").
Programmatically create new discount codes.
Browse and manage existing discounts; update or delete as needed.
Apply discount codes when upgrading or downgrading subscription plans.
## What Are Discount Codes?
Discount codes are promotional tokens that reduce order totals at checkout. They’re ideal for:
* **Seasonal campaigns**: Black Friday, product launches, or anniversaries
* **Acquisition offers**: First‑purchase incentives or referral rewards
* **Retention**: Win‑back or loyalty rewards for existing customers
* **B2B deals**: Contracted or negotiated pricing via private codes
## Key Benefits
* **Flexible discounts**: Percentage-based or flat-amount discounts
* **Stackable codes**: Apply up to 20 codes per checkout, payment, or subscription — combine campaigns (e.g. `WELCOME10` + `BLACKFRIDAY20`) without creating bespoke codes
* **Targeted control**: Restrict by product, subscription cycles, and customer eligibility
* **Campaign governance**: Scheduled start dates, expiration dates, overall and per-customer usage limits
* **Per-currency pricing**: Set the flat deduction, amount cap, and minimum subtotal per currency
* **Seamless checkout**: UI field and API support via checkout sessions
## Creating Discount Codes
Create discount codes in your Dodo Payments dashboard, then apply them in hosted checkout or via API.
### Dashboard setup
* **Discount Name** (required): Internal and dashboard display name
* **Code** (required): The string customers enter at checkout, or generate a random code using the button provided
* **Type** (required): Choose **Percentage** (a percent off) or **Amount** (a flat deduction)
* **Amount** (required): The percentage value, or the flat amount for an Amount discount
* **Start Date** (optional): Schedule the code to become active later; leave empty to activate immediately
* **Expiration Date** (optional): Date after which the code becomes invalid
* **Usage Limit** (optional): Max total redemptions across all customers
* **Per-Customer Usage Limit** (optional): Max redemptions by any single customer. Must be less than or equal to the overall usage limit when both are set
* **Customer Eligibility** (optional): Restrict who may redeem the code — all customers, first-time customers, existing customers, or a hand-picked list
* **Currency Options** (optional): Per-currency values — see [Per-Currency Options](#per-currency-options)
* **Product Restriction** (optional): Limit applicability to selected products
* **Subscription Cycle Limit** (optional): Number of billing cycles the discount applies to
* **Preserve on Plan Change** (optional): Keep the discount active when the subscription's plan changes (`preserve_on_plan_change`)
* **Metadata** (optional): Attach custom key–value pairs for internal tracking or integrations
The discount details — type, percentage or amount, name, code, and currency options:
Usage and expiry limits, fully configured:
Further down the form — eligibility, restrictions, and advanced options:
Use cycle limits for introductory pricing on subscriptions (e.g., "50% off for 3 months").
A percentage `amount` is expressed in **basis points** over the API — `1500` means 15%. A flat `amount` is a money value and is denominated by the code's currency options.
## Discount Types
| Type | API value | Behaviour |
| ---------- | ------------ | -------------------------------------------------------------------------------------------------------- |
| Percentage | `percentage` | Reduces the price by a percent. Optionally capped per currency with a maximum discount. |
| Amount | `flat` | Deducts a fixed amount. The deduction is pooled across the whole cart rather than applied per line item. |
Both types can be combined in the same `discount_codes` array and are applied in array order.
## Customer Eligibility
Set `customer_eligibility` to control who may redeem a code:
| Value | Who can redeem |
| ------------ | --------------------------------------------------- |
| `any` | Any customer. This is the default. |
| `first_time` | Customers who have not purchased from you before. |
| `existing` | Customers who have purchased from you before. |
| `specific` | Only customers you attach to the code's allow list. |
A `specific` code starts with **zero** eligible customers and rejects every redemption until you attach customers to it. Attach them in the dashboard, or with the discount customers API.
Pair eligibility with **Per-Customer Usage Limit** to cap how often each individual customer can redeem the code, independently of the overall usage limit.
## Per-Currency Options
Currency options let one code behave correctly across the currencies you sell in. Each entry sets, for a single currency:
* **Amount** — for an Amount discount this is the deduction itself; for a Percentage discount it caps how much the code can take off. Maps to `max_amount_possible` over the API.
* **Minimum subtotal** — the code only applies when the cart reaches this subtotal. `0` means no minimum.
* **Default** — one entry can be marked as the default that other, unconfigured currencies convert from.
An Amount discount requires at least one currency option with a resolvable default, since a flat deduction has no meaning without a currency. Currency options are optional for Percentage discounts.
The minimum subtotal is always measured against the cart's original prices, never the running total part-way through a stack. Stacking order therefore never changes whether a minimum is met.
## Checkout Experience
1. Shoppers enter the code in the checkout field.
2. Eligible discounts are applied and totals update immediately.
In Checkout Sessions, pass `discount_codes` (an array) to pre‑apply one or more codes. The discount input field is shown by default — `feature_flags.allow_discount_code` defaults to `true`, so set it to `false` only if you want to hide it. Codes are applied in array order, up to a maximum of 20.
## Stacking Discount Codes
Checkout sessions, payments, and subscriptions accept up to **20 stacked codes** via the `discount_codes` array (max 20 entries). Codes are applied **in array order**, so the first eligible code reduces the starting price first, the next code reduces the already-discounted price, and so on. When [Purchasing Power Parity](/features/purchasing-power-parity) is enabled, the starting price is the PPP-adjusted amount, not the base price. The full set of applied discounts is returned in the response under `discount_ids` (on payments/subscriptions) and `discounts` (richer per-discount detail, including position and remaining subscription cycles).
```typescript theme={null}
const session = await client.checkoutSessions.create({
product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
discount_codes: ['WELCOME10', 'BLACKFRIDAY20'], // applied in this order
customer: { email: 'user@example.com' },
return_url: 'https://yoursite.com/return'
});
```
The singular `discount_code` field is **deprecated** but still fully supported for backward compatibility — existing integrations continue to work without changes. It cannot be combined with `discount_codes` in the same request. We recommend migrating to `discount_codes` (the array form) when convenient, even for single codes, to take advantage of stacking and the richer response shape.
## API Management
Create discount codes programmatically with type and amount.
View the create discount API.
List all discounts or retrieve details for management and auditing.
Browse listing and retrieval APIs.
Look up a discount using its human-readable code (e.g., "SAVE20") instead of the internal ID.
Retrieve discount by code name.
Modify discount configuration such as amount, expiration, or restrictions.
Learn how to update discount details.
Check whether a discount is valid and applicable before applying.
Validate discount usage.
Deactivate or remove discounts that are no longer needed.
Delete a discount.
For a discount with `customer_eligibility` set to `specific`, manage the customers that may redeem it:
* `GET /discounts/{discount_id}/customers` — list the attached customers (paginated, up to 100 per page).
* `POST /discounts/{discount_id}/customers` — attach customers by ID. The call is idempotent and accepts up to 1000 IDs, all of which must already exist in your business. The response echoes only the IDs submitted in that request, so list the endpoint to read the full allow list.
* `DELETE /discounts/{discount_id}/customers/{customer_id}` — detach a single customer.
## Common Use Cases
* **Intro offers**: Limited‑time launch promotions for new products
* **Bulk or B2B**: Contracted discounts for select product sets
* **Retention plays**: Win‑back codes in churn‑prevention workflows
* **Seasonal campaigns**: Holiday or event‑based promotions
## Integration Examples
### Create a discount with metadata
Attach custom key–value pairs for internal tracking.
```typescript theme={null}
const discount = await client.discounts.create({
type: 'percentage',
amount: 1500, // 15%
code: 'SUMMER2025',
metadata: {
campaign: 'summer_promo',
source: 'email_blast'
}
});
```
Use metadata to tag discounts by campaign, source, or internal reference ID so you can reconcile usage and measure ROI later.
### Apply discounts in Checkout Sessions
Pre‑apply one or more stacked discounts and show the code input UI.
```typescript theme={null}
const session = await client.checkoutSessions.create({
product_cart: [
{ product_id: 'pdt_abc', quantity: 1 }
],
discount_codes: ['BLACKFRIDAY2024', 'NEWUSER5'], // stacked in array order
customer: { email: 'user@example.com', name: 'Jane Doe' },
return_url: 'https://yoursite.com/return'
});
```
### Apply discounts during plan changes
Offer promotional pricing when customers upgrade or downgrade their subscription.
```typescript theme={null}
await client.subscriptions.changePlan('sub_123', {
product_id: 'pdt_pro',
quantity: 1,
proration_billing_mode: 'prorated_immediately',
discount_codes: ['UPGRADE20']
});
```
| `discount_codes` value | Behavior on plan change |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `undefined` / `null` (not provided) | Existing discounts with `preserve_on_plan_change=true` are preserved if applicable to the new product. |
| `[]` (empty array) | **All** existing discounts are removed from the subscription. |
| `['CODE_A', 'CODE_B', ...]` | Replaces any existing discounts with this stacked set, applied in array order. |
Read all applied discounts off the subscription via the new `discounts` array on the subscription response. Each entry includes `discount_id`, `position`, `cycles_remaining` (for subscriptions), and the original code.
### Hide the discount code field
The discount input is shown by default, so customers can always enter a code without you passing one upfront. Set `allow_discount_code` to `false` to hide the field entirely.
```typescript theme={null}
const session = await client.checkoutSessions.create({
product_cart: [
{ product_id: 'pdt_abc', quantity: 1 }
],
feature_flags: {
allow_discount_code: false
},
return_url: 'https://yoursite.com/return'
});
```
## Best Practices
* **Name clearly**: Use recognizable codes that match campaign names
* **Time‑box**: Add expirations to drive urgency and prevent misuse
* **Scope wisely**: Limit to specific products to avoid margin leakage
* **Validate early**: Check code applicability before confirming checkout
* **Monitor impact**: Track usage and conversion by campaign
Discount codes are powerful levers for acquisition and retention. Start with simple, well‑named offers, validate thoroughly, and iterate based on performance.