---
name: discounts-and-promotions
description: Dodo Payments discount codes and promotional pricing, covering discount CRUD, percentage and flat amounts, eligibility rules, usage limits, stacking via discount_codes, subscription-cycle limits, and preservation on plan changes. Use when creating coupons or promo codes, applying or validating a code at checkout, or debugging a discount that won't apply.
---

# Discounts and Promotions

This skill covers discount codes, coupons, and promotional pricing in Dodo Payments. Use it when building discount management, applying codes at checkout, validating codes before showing prices, or handling discounts during subscription plan changes.

## When to use this skill

- Create, update, list, or delete discount codes
- Apply discount codes at checkout or during plan changes
- Validate a code before displaying adjusted pricing to the user
- Configure eligibility rules, usage limits, or subscription-cycle restrictions
- Handle the subtle semantics of discount preservation during plan upgrades/downgrades
- Debug why a discount isn't applying or stacking as expected

## Core concepts

**Discount types:** Dodo supports both percentage and flat-amount discounts. Percentage amounts are expressed as integers where 1500 means 15% (100 = 1%). Flat amounts are in the smallest currency unit (cents for USD).

**Discount code:** A human-readable string (e.g., `SUMMER2025`) that customers enter at checkout. The API uppercases codes on create (`summer2025` is stored as `SUMMER2025`); codes must be at least 3 characters, and omitting `code` generates a random 16-character uppercase code.

**Eligibility:** Discounts can be restricted to specific products, customers, or date ranges. A discount without restrictions applies to any product and any customer.

**Stacking:** Multiple discount codes can be applied to a single checkout or subscription. They are applied in the order specified in the `discount_codes` array, up to a maximum of 20 codes.

**Subscription-cycle limits:** A discount can be configured to apply only for a specific number of billing cycles (e.g., first 3 months only).

**Preservation on plan change:** When a customer upgrades or downgrades their subscription, the `preserve_on_plan_change` setting and the `discount_codes` parameter control whether existing discounts carry forward.

## Discount CRUD

### Create a discount

```typescript
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
});

// Percentage discount: 15% off
const percentageDiscount = await client.discounts.create({
  type: 'percentage',
  amount: 1500, // 15%
  code: 'SUMMER2025',
  metadata: {
    campaign: 'summer_promo',
    source: 'email_blast'
  }
});

// Flat discount: $10 off (1000 cents in currency_options)
const flatDiscount = await client.discounts.create({
  type: 'flat',
  amount: 1000,
  currency_options: [{
    currency: 'USD',
    max_amount_possible: 1000,
    is_default: true,
  }],
  code: 'WELCOME10',
});
```

### List discounts

```typescript
const discounts = await client.discounts.list({
  page_size: 50,
  page_number: 0,
});

// Paginated responses expose `items`.
for (const discount of discounts.items) {
  console.log(`${discount.code}: ${discount.type} ${discount.amount}`);
}

// Or let the SDK walk every page for you:
for await (const discount of client.discounts.list()) {
  console.log(discount.code);
}
```

### Retrieve a discount by ID

```typescript
const discount = await client.discounts.retrieve('discount_id');
console.log(discount.code, discount.type, discount.amount);
```

### Retrieve a discount by code

```typescript
try {
  const discount = await client.discounts.retrieveByCode('SUMMER2025');
  console.log('Discount found:', discount.amount);
} catch (error) {
  console.log('Code not found or expired');
}
```

### Update a discount

```typescript
await client.discounts.update('discount_id', {
  metadata: { updated_at: new Date().toISOString() }
});
```

### Delete a discount

```typescript
await client.discounts.delete('discount_id');
```

## Discount types and configuration

Two types are supported: `percentage` and `flat` (shown as **Amount** in the dashboard). A `flat` discount requires `currency_options` with at least one resolvable default currency; for a `percentage` discount, `currency_options` is optional and caps the discount per currency. A flat deduction is pooled across the whole cart rather than applied per line item.

### Percentage discounts

Expressed as an integer where 100 = 1%. A 15% discount is `1500`.

```typescript
const discount = await client.discounts.create({
  type: 'percentage',
  amount: 1500, // 15%
  code: 'PERCENT15',
});
```

### Flat discounts

For flat discounts, set the deduction per currency through `currency_options`. A $10 USD deduction is `max_amount_possible: 1000` (cents).

```typescript
const discount = await client.discounts.create({
  type: 'flat',
  amount: 1000, // $10.00
  currency_options: [{
    currency: 'USD',
    max_amount_possible: 1000,
    is_default: true,
  }],
  code: 'FLAT10',
});
```

## Eligibility and restrictions

### Product restrictions

Limit a discount to specific products:

```typescript
const discount = await client.discounts.create({
  type: 'percentage',
  amount: 1500,
  code: 'PREMIUM_ONLY',
  restricted_to: ['pdt_premium', 'pdt_enterprise'],
});
```

### Customer eligibility

Restrict a discount to specific customers by creating it with `customer_eligibility: 'specific'`, then attaching customers through the discount-customer endpoint. `customer_ids` is not a `discounts.create` parameter.

```typescript
const discount = await client.discounts.create({
  type: 'percentage',
  amount: 1500,
  code: 'VIP_ONLY',
  customer_eligibility: 'specific',
});

// The SDK has no named method for this endpoint yet. `client.post` reuses the
// client's auth and base URL (test.dodopayments.com for `test_mode`,
// live.dodopayments.com for `live_mode`), so nothing is hardcoded.
await client.post(`/discounts/${discount.discount_id}/customers`, {
  body: { customer_ids: ['cus_vip_001', 'cus_vip_002'] },
});
```

### Date range

Set activation and expiration dates:

```typescript
const discount = await client.discounts.create({
  type: 'percentage',
  amount: 1500,
  code: 'SUMMER2025',
  starts_at: '2025-06-01T00:00:00Z',
  expires_at: '2025-08-31T23:59:59Z',
});
```

### Usage limits

Limit the total number of times a code can be used:

```typescript
const discount = await client.discounts.create({
  type: 'percentage',
  amount: 1500,
  code: 'LIMITED_100',
  usage_limit: 100,
});
```

### Subscription-cycle limits

Apply a discount only for the first N billing cycles:

```typescript
const discount = await client.discounts.create({
  type: 'percentage',
  amount: 1500,
  code: 'FIRST_3_MONTHS',
  subscription_cycles: 3, // applies to first 3 billing cycles only
});
```

## Applying codes at checkout

### Single code

Never call the SDK from the browser: it uses your secret API key. Create the session in a server route and return only the URL.

```typescript
// Server route
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  discount_codes: ['SUMMER2025'],
  customer: { email: 'user@example.com' },
  return_url: 'https://yoursite.com/return'
});

return Response.json({ checkout_url: session.checkout_url });
```

```typescript
// Browser
const res = await fetch('/api/checkout', { method: 'POST' });
const { checkout_url } = await res.json();
window.location.href = checkout_url;
```

### Multiple codes (stacking)

Codes are applied in the order specified. Maximum 20 codes per checkout:

```typescript
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  discount_codes: ['WELCOME10', 'BLACKFRIDAY20', 'LOYALTY5'],
  customer: { email: 'user@example.com' },
  return_url: 'https://yoursite.com/return'
});
```

## Validating codes before checkout

Validate a code and check its eligibility before showing adjusted pricing:

```typescript
async function validateDiscount(code, productId) {
  try {
    const discount = await client.discounts.retrieveByCode(code);
    
    // Check expiration
    if (discount.expires_at && new Date(discount.expires_at) < new Date()) {
      return { valid: false, reason: 'Code expired' };
    }
    
    // Check usage limit
    if (discount.usage_limit && discount.times_used >= discount.usage_limit) {
      return { valid: false, reason: 'Code exhausted' };
    }
    
    // Check product eligibility
    if (discount.restricted_to.length > 0) {
      if (!discount.restricted_to.includes(productId)) {
        return { valid: false, reason: 'Code not valid for this product' };
      }
    }
    
    return { valid: true, discount };
  } catch (error) {
    return { valid: false, reason: 'Code not found or unavailable' };
  }
}

// Usage
const result = await validateDiscount('SUMMER2025', 'pdt_abc');
if (result.valid) {
  console.log('Discount applies:', result.discount.amount);
} else {
  console.log('Cannot apply:', result.reason);
}
```

## Discounts on plan changes

When a customer changes their subscription plan, discounts can be preserved, replaced, or cleared depending on the `discount_codes` parameter and each discount's `preserve_on_plan_change` setting. Set `preserve_on_plan_change` through `discounts.create` or `discounts.update`; it is not a `subscriptions.changePlan` parameter.

### Behavior matrix

| Scenario | `discount_codes` | Discount's `preserve_on_plan_change` | Result |
|---|---|---|---|
| Upgrade with no change | `undefined` | `true` | Existing discounts carry forward |
| Upgrade with no change | `undefined` | `false` | Existing discounts are removed |
| Upgrade with no change | `[]` (empty array) | any | Existing discounts are removed |
| Upgrade with replacement | `['NEW_CODE']` | any | Only `NEW_CODE` applies; old discounts removed |

### Example: preserve existing discounts

```typescript
await client.discounts.update('dsc_existing', {
  preserve_on_plan_change: true,
});

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  // Omit discount_codes. Existing discounts configured with
  // preserve_on_plan_change: true carry forward.
});
```

### Example: replace discounts on upgrade

```typescript
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: ['UPGRADE20'], // replaces old discounts
});
```

### Example: remove all discounts on downgrade

```typescript
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_basic',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: [], // empty array removes all discounts
});
```

## Common mistakes

### Validating discounts client-side only

Never trust client-side validation. Always validate on the server before applying a discount at checkout. A user can modify the discount code in the browser.

```typescript
// WRONG: client-side only
if (code.length > 0) {
  applyDiscount(code);
}

// CORRECT: server-side validation
try {
  const discount = await client.discounts.retrieveByCode(code);
  if (isEligible(discount)) {
    // proceed with checkout
  }
} catch (error) {
  // Unknown or unavailable code; reject the checkout request.
}
```

### Assuming codes stack unconditionally

Discounts stack in order, but eligibility rules still apply. If a code is restricted to a product not in the cart, it won't apply even if other codes do.

```typescript
// Both codes may not apply if they have conflicting restrictions
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_basic', quantity: 1 }],
  discount_codes: ['PREMIUM_ONLY', 'BASIC_ONLY'], // one or both may fail
  return_url: 'https://yoursite.com/return'
});
```

### Losing a discount on upgrade by passing an empty array

Passing `discount_codes: []` explicitly removes all discounts, even if `preserve_on_plan_change` is true. Omit the parameter entirely if you want to preserve existing discounts.

```typescript
// WRONG: removes all discounts
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: [], // this clears discounts
});

// CORRECT: preserves discounts whose preserve_on_plan_change property is true
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  // omit discount_codes
});
```

### Not handling expired or exhausted codes

A code can expire by date or by reaching its redemption limit. Always check both before showing a discount to the user.

```typescript
// WRONG: assumes code is always valid
const discount = await client.discounts.retrieveByCode(code);
applyDiscount(discount);

// CORRECT: catch unknown codes, then check expiration and usage
try {
  const discount = await client.discounts.retrieveByCode(code);
  if (discount.expires_at && new Date(discount.expires_at) < new Date()) {
    showError('Code expired');
  } else if (discount.usage_limit && discount.times_used >= discount.usage_limit) {
    showError('Code exhausted');
  } else {
    applyDiscount(discount);
  }
} catch (error) {
  showError('Code not found');
}
```

### Confusing subscription-cycle limits with expiration dates

`subscription_cycles` applies only to subscriptions and controls how many billing cycles the discount applies. `expires_at` is a hard cutoff for all uses of the code.

```typescript
// Applies to first 3 billing cycles of any subscription
const discount = await client.discounts.create({
  type: 'percentage',
  amount: 1500,
  code: 'FIRST_3_MONTHS',
  subscription_cycles: 3,
});

// Expires on a specific date, regardless of billing cycles
const discount2 = await client.discounts.create({
  type: 'percentage',
  amount: 1500,
  code: 'SUMMER_ONLY',
  expires_at: '2025-08-31T23:59:59Z',
});
```

## Resources

- [Discounts feature guide](https://docs.dodopayments.com/features/discount-codes)
- [Create discount API](https://docs.dodopayments.com/api-reference/discounts/create-discount)
- [Checkout Sessions API](https://docs.dodopayments.com/developer-resources/checkout-session)
- [Subscription plan changes](https://docs.dodopayments.com/api-reference/subscriptions/change-plan)