Discounts

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.

Checkout Sessions

Apply one or more stacked codes during hosted checkout with discount_codes and UI controls.

Validate Discount

Check if a discount is valid by its ID.

Get Discount by Code

Look up and validate a discount using its code name (e.g., “SAVE20”).

Create Discount (API)

Programmatically create new discount codes.

List & Update Discounts

Browse and manage existing discounts; update or delete as needed.

Plan Change Discounts

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, maximum discount, and minimum cart value 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
Product Restriction (optional): Limit applicability to selected products
Subscription Cycle Limit (optional): Number of billing cycles the discount applies to
Metadata (optional): Attach custom key–value pairs for internal tracking or integrations

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:

Maximum discount — for an Amount discount this is the deduction itself; for a Percentage discount it caps how much the code can take off.
Minimum cart value — 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 cart value 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

Shoppers enter the code in the checkout field.
Eligible discounts are applied and totals update immediately.

In Checkout Sessions, pass discount_codes (an array) to pre‑apply one or more codes, and set feature_flags.allow_discount_code to show the input field. 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 base price first, the next code reduces the already-discounted price, and so on. 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).

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_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 discounts

Create discount codes programmatically with type and amount.

API Reference

View the create discount API.

List and retrieve

List all discounts or retrieve details for management and auditing.

API Reference

Browse listing and retrieval APIs.

Get discount by code

Look up a discount using its human-readable code (e.g., “SAVE20”) instead of the internal ID.

API Reference

Retrieve discount by code name.

Update discounts

Modify discount configuration such as amount, expiration, or restrictions.

API Reference

Learn how to update discount details.

Validate discounts

Check whether a discount is valid and applicable before applying.

API Reference

Validate discount usage.

Delete discounts

Deactivate or remove discounts that are no longer needed.

API Reference

Delete a discount.

Manage the customer allow list

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.

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.

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'prod_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.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_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.

Enable discount entry without pre‑applying

Let customers enter a code at checkout without passing one upfront.

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'prod_abc', quantity: 1 }
  ],
  feature_flags: {
    allow_discount_code: true
  },
  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.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions

Validate Discount

Get Discount by Code

Create Discount (API)

List & Update Discounts

Plan Change Discounts

What Are Discount Codes?

Key Benefits

Creating Discount Codes

Dashboard setup

Discount Types

Customer Eligibility

Per-Currency Options

Checkout Experience

Stacking Discount Codes

API Management

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

Common Use Cases

Integration Examples

Create a discount with metadata

Apply discounts in Checkout Sessions

Apply discounts during plan changes

Enable discount entry without pre‑applying

Best Practices

Checkout Sessions

Validate Discount

Get Discount by Code

Create Discount (API)

List & Update Discounts

Plan Change Discounts

​What Are Discount Codes?

​Key Benefits

​Creating Discount Codes

​Dashboard setup

​Discount Types

​Customer Eligibility

​Per-Currency Options

​Checkout Experience

​Stacking Discount Codes

​API Management

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

​Common Use Cases

​Integration Examples

​Create a discount with metadata

​Apply discounts in Checkout Sessions

​Apply discounts during plan changes

​Enable discount entry without pre‑applying

​Best Practices

What Are Discount Codes?

Key Benefits

Creating Discount Codes

Dashboard setup

Discount Types

Customer Eligibility

Per-Currency Options

Checkout Experience

Stacking Discount Codes

API Management

Common Use Cases

Integration Examples

Create a discount with metadata

Apply discounts in Checkout Sessions

Apply discounts during plan changes

Enable discount entry without pre‑applying

Best Practices