Skip to main content
skill CX Codex

discounts-and-promotions — Claude Code skill for discounts

discounts-and-promotions is a Claude Code skill for configuring Dodo Payments promo codes, checking eligibility rules, and troubleshooting codes rejected at checkout.

MIT 199 installs ★ 14 updated 2026-10-20

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add dodopayments/skills --skill discounts-and-promotions -a claude-code
Open on GitHub

What discounts-and-promotions does

This skill covers discount management in Dodo Payments with the dodopayments SDK. It guides you through creating, listing, retrieving, updating, and deleting codes, with percentage or flat amounts and restrictions for products or customers.

It also covers date windows, total-use limits, subscription billing-cycle limits, and how stacked codes are applied in the order supplied through discount_codes. Existing discounts during subscription plan changes are part of the workflow too. A flat discount needs currency_options with a default currency, so that setting must be in place before you create one.

What it helps with

  • create a percentage or flat promo code
  • restrict a discount to selected products or customers
  • set an expiry date and a usage cap
  • debug a code that fails at checkout
  • control discounts across subscription plan changes

Example prompts for the agent

  • Create a percentage promo code restricted to pdt_premium and set its active dates.
  • Find out why WELCOME10 is rejected during checkout.
  • Set a discount to cover the first subscription billing cycles.

How to install discounts-and-promotions

1Skills CLI (Vercel)

npx skills add dodopayments/skills --skill discounts-and-promotions -a claude-code

2Manually: put the files in place

~/.claude/skills/discounts-and-promotions/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/discounts-and-promotions/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about discounts-and-promotions

How do I install discounts-and-promotions in Claude Code?

Run npx skills add dodopayments/skills --skill discounts-and-promotions -a claude-code. The skill file is at ~/.claude/skills/discounts-and-promotions/SKILL.md.

What does discounts-and-promotions do?

It helps manage Dodo Payments discounts, configure code eligibility, and investigate why a promo code does not work at checkout.

What does a flat discount need?

Its currency_options must include at least one default currency. The deduction is set in the smallest unit of that currency.

Source text

SKILL.md · MIT
---
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: '[email protected]' },
  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: '[email protected]' },
  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)

© dodopayments · MIT · dodopayments/skills

Similar skills

All skills for Backend and APIs →

From the same set17

The whole set →
testing-and-go-live testing-and-go-live runs a Dodo Payments integration through test mode: cards, declines, renewals, webhooks. Then takes it to production with a launch checklist. CX Codex +1 219installs framework-adapters framework-adapters mounts official Dodo Payments adapters across Next.js, Express, Hono, Nuxt, and more. Sets up checkout, customer portal, and webhook handlers. CX Codex +1 209installs refunds-and-disputes refunds-and-disputes teaches coding agents how to issue refunds and handle dispute lifecycles with Dodo Payments. Helps wire webhooks, issue partial line-item refunds, and manage access. CX Codex +1 208installs product-catalog-management product-catalog-management manages Dodo Payments products, subscription pricing models, add-ons, and image uploads. Designed for TypeScript SDK integrations. CX Codex +1 208installs customer-management customer-management is a Claude Code skill for managing Dodo Payments customers: create records, set up portals and payment methods, manage wallets, and link app users to billing IDs. CX Codex +1 202installs localized-pricing localized-pricing guides multi-currency setups in Dodo Payments across fixed regional prices, live Adaptive Currency conversion, and purchasing power parity (PPP) tiers. CX Codex +1 198installs mobile-checkout mobile-checkout guides integration of Dodo Payments hosted checkout into React Native, Flutter, iOS, and Android using system browsers. CX Codex +1 192installs better-auth-integration The better-auth-integration skill connects Better Auth with Dodo Payments for customer sync, checkout, portal access, usage events, and signed webhooks. CX Codex +1 192installs

Project sponsors

Companies that keep this analytics open