跳转到主要内容
Discount codes overview cover
折扣代码让您可以运行有针对性的促销和激励。创建基于百分比的折扣，设置限制和到期时间，限制产品，并在结账时无缝应用。

Checkout Sessions

在托管结账时，通过 discount_codes 和 UI 控件应用一个或多个叠加代码。

Validate Discount

通过 ID 检查折扣是否有效。

Get Discount by Code

使用代码名称（例如 “SAVE20”）查找并验证折扣。

Create Discount (API)

以编程方式创建新的折扣码。

List & Update Discounts

浏览和管理现有折扣；根据需要更新或删除。

Plan Change Discounts

在升级或降级订阅计划时应用折扣码。

​
什么是折扣码？

折扣码是结账时减少订单总额的促销代币。它们非常适合：
  • 季节性活动：黑色星期五、产品发布或周年庆
  • 获取优惠：首次购买奖励或推荐奖励
  • 客户留存：为现有客户提供的赢回或忠诚奖励
  • B2B 交易：通过私有代码进行的合同或协商定价

​
主要优点

  • 灵活折扣：基于百分比的折扣
  • 可叠加代码：每次结账、付款或订阅最多可应用 20 个代码 — 结合活动（例如 WELCOME10 + BLACKFRIDAY20）而无需创建定制代码
  • 有针对性的控制：按产品和订阅周期限制
  • 活动管理：到期日期和使用限制
  • 无缝结账：通过结账会话的 UI 字段和 API 支持

​
创建折扣码

在您的 Dodo Payments 仪表板中创建折扣码，然后在托管结账或通过 API 应用它们。

​
仪表板设置

  • 折扣名称（必填）：内部和仪表板显示名称
  • 代码（必填）：客户在结账时输入的字符串
  • 类型和金额（必填）：设置百分比值（目前仅支持基于百分比的折扣），或使用提供的按钮生成随机代码
  • 到期日期（可选）：代码失效的日期
  • 使用限制（可选）：所有客户的最大兑换次数
  • 产品限制（可选）：限制适用于选定产品
  • 订阅周期限制（可选）：折扣适用的计费周期数
  • 元数据（可选）：附加用于内部跟踪或集成的自定义键值对
使用循环限制用于订阅的入门定价（例如，“3个月内50%折扣”）。

​
结账体验

  1. 顾客在结账字段中输入代码。
  2. 合格的折扣被应用，并立即更新总额。
在结账会话中，传递 discount_codes（一个数组）以预先应用一个或多个代码，并设置 feature_flags.allow_discount_code 显示输入字段。代码按数组顺序应用，最多可应用 20 个。

​
叠加折扣代码

结账会话、付款和订阅通过 discount_codes 数组（最多 20 项）接受最多 20 个叠加代码。代码按 数组顺序 应用，第一个符合条件的代码优先减少基础价格，接下来的代码减少已折扣的价格，以此类推。完整的应用折扣集在响应中通过 discount_ids （在付款/订阅上）和 discounts（每个折扣的更丰富细节，包括位置和剩余订阅周期）返回。 
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'
});
单一的 discount_code 字段已 弃用，但仍完全支持以确保向后兼容 — 现有集成继续工作无需更改。不能在同一请求中与 discount_codes 结合使用。我们建议在方便时迁移到 discount_codes（数组形式），即使对于单个代码，以利用叠加和更丰富的响应形态。

​
API 管理

以编程方式创建具有类型和金额的折扣代码。

API Reference

查看创建折扣 API。
列出所有折扣或检索详细信息以进行管理和审计。

API Reference

浏览列表和检索 API。
使用可读代码（例如，“SAVE20”）代替内部 ID 查找折扣。

API Reference

通过代码名检索折扣。
修改折扣配置，如金额、到期或限制。

API Reference

了解如何更新折扣详细信息。
在应用之前检查折扣是否有效和适用。

API Reference

验证折扣使用。
停用或移除不再需要的折扣。

API Reference

删除折扣。

​
常见用例

  • 介绍优惠：新产品的限时发布促销
  • 批量或 B2B：特定产品组的合同折扣
  • 保留方式：防止流失工作流中的重获代码
  • 季节性活动：假日或事件为基础的促销

​
集成示例

​
创建带有元数据的折扣

附加自定义键值对以进行内部跟踪。 
const discount = await client.discounts.create({
  type: 'percentage',
  amount: 1500, // 15%
  code: 'SUMMER2025',
  metadata: {
    campaign: 'summer_promo',
    source: 'email_blast'
  }
});
使用元数据根据活动、来源或内部引用 ID 标记折扣，以便稍后核对使用情况并衡量投资回报率。

​
在结账会话中应用折扣

预先应用一个或多个叠加折扣，并显示代码输入 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'
});

​
在计划变更期间应用折扣

当客户升级或降级其订阅时提供促销定价。 
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: ['UPGRADE20']
});
discount_codes 值计划变更时的行为
undefined / null （未提供）如果适用于新产品，现有折扣与 preserve_on_plan_change=true 保留。
[] （空数组）全部 现有折扣从订阅中移除。
['CODE_A', 'CODE_B', ...]用这个叠加集替换所有现有折扣，按数组顺序应用。
通过订阅响应中的新 discounts 数组读取所有应用的折扣。每个条目包括 discount_id、position、cycles_remaining（针对订阅）和原始代码。

​
启用折扣输入而不预先应用

允许客户在结账时输入代码而无需提前传递。 
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'
});

​
最佳实践

  • 清晰命名：使用与活动名称匹配的可识别代码
  • 时限：添加截止日期以产生紧迫感并防止滥用
  • 明智的范围：限制到特定产品以避免利润损失
  • 提前验证：在确认结账前检查代码适用性
  • 监控影响：按活动跟踪使用情况和转化率
折扣代码是获取和保留的强大杠杆。从简单、命名良好的优惠开始，彻底验证，并根据表现反复改进。
Last modified on June 9, 2026