discounts-and-promotions

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. Codes are case-sensitive.

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

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',
});