折扣 - Dodo Payments Documentation

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

Checkout Sessions

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

Validate Discount

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

Get Discount by Code

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

Create Discount (API)

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

List & Update Discounts

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

Plan Change Discounts

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

什么是折扣码？

折扣码是结账时减少订单总额的促销代币。它们非常适合：

季节性活动：黑色星期五、产品发布或周年庆
获取优惠：首次购买奖励或推荐奖励
客户留存：为现有客户提供的赢回或忠诚奖励
B2B 交易：通过私有代码进行的合同或协商定价

主要优点

灵活折扣：按百分比或固定金额设置折扣
可叠加代码：每次结账、Payment 或 Subscription 最多应用 20 个代码 — 组合多个活动（例如 WELCOME10 + BLACKFRIDAY20），无需创建专用代码
定向控制：按产品、Subscription 周期和客户资格进行限制
活动治理：设置计划开始日期、过期日期，以及总使用次数和每位客户的使用次数限制
按货币定价：为每种货币设置固定扣减金额、金额上限和最低小计
无缝结账：通过结账会话提供 UI 字段和 API 支持

创建折扣码

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

Dashboard 设置

Discount Name（必填）：内部名称和 Dashboard 显示名称
Code（必填）：客户在结账时输入的字符串，或使用提供的按钮生成随机代码
Type（必填）：选择 Percentage（按百分比减免）或 Amount（固定金额扣减）
Amount（必填）：百分比数值，或 Amount 折扣的固定金额
Start Date（可选）：安排代码稍后生效；留空则立即生效
Expiration Date（可选）：代码失效的日期
Usage Limit（可选）：所有客户合计的最大兑换次数
Per-Customer Usage Limit（可选）：单个客户的最大兑换次数。当两者同时设置时，该值必须小于或等于总使用次数限制
Customer Eligibility（可选）：限制可以兑换代码的客户 — 所有客户、首次购买客户、现有客户或手动指定的客户列表
Currency Options（可选）：按货币设置的值 — 请参阅 Per-Currency Options
Product Restriction（可选）：将适用范围限制为选定产品
Subscription Cycle Limit（可选）：折扣适用的计费周期数
Preserve on Plan Change（可选）：Subscription 的计划发生变更时仍保留折扣（preserve_on_plan_change）
Metadata（可选）：附加自定义键值对，用于内部跟踪或集成

折扣详情 — 类型、百分比或金额、名称、代码和货币选项：

New Discount Code 表单，显示类型、百分比金额、名称、代码和货币选项

使用次数和过期限制均已完成配置：

表单下方 — 资格、限制和高级选项：

使用周期限制为 Subscription 设置介绍性定价（例如“前 3 个月享受 50% 折扣”）。

通过 API，百分比 amount 以 basis points 表示 — 1500 表示 15%。固定金额 amount 是货币值，其货币由代码的货币选项确定。

折扣类型

类型	API value	行为
Percentage	`percentage`	按百分比降低价格。可以按货币设置上限，以限制最大折扣金额。
Amount	`flat`	扣除固定金额。该扣减金额在整个购物车范围内统一计算，而不是应用于每个行项目。

两种类型可以在同一个 discount_codes 数组中组合，并按照数组顺序应用。

客户资格

设置 customer_eligibility，以控制哪些客户可以兑换代码：

值	可兑换的客户
`any`	任何客户。这是默认值。
`first_time`	之前未向你购买过商品的客户。
`existing`	之前向你购买过商品的客户。
`specific`	仅限添加到代码允许列表中的客户。

客户资格下拉菜单，显示 Any、First-time、Existing 和 Specific customer 选项

specific 代码初始时没有任何符合资格的客户，在将客户添加到代码之前会拒绝所有兑换请求。你可以在 Dashboard 中添加客户，也可以使用 discount customers API 添加。

将资格设置与 Per-Customer Usage Limit 配合使用，可以限制每位客户兑换代码的次数，且不受总使用次数限制影响。

按货币设置的选项

货币选项可以让同一个代码在你销售所使用的各种货币中正确运行。每个条目针对单一货币设置以下内容：

Amount — 对于 Amount 折扣，这是实际扣减金额；对于 Percentage 折扣，这是代码可以减免的金额上限。通过 API 映射到 max_amount_possible。
Minimum subtotal — 只有购物车达到此小计金额时，代码才会生效。0 表示没有最低金额要求。
Default — 可以将一个条目标记为默认值，其他未配置的货币将根据该默认值进行转换。

Amount 折扣至少需要一个具有可解析默认值的货币选项，因为固定扣减金额在没有货币时没有意义。Percentage 折扣的货币选项为可选。

最低小计始终根据购物车的原始价格计算，而不是根据叠加过程中途的当前总额计算。因此，叠加顺序不会改变最低金额是否满足。

结账体验

购物者在结账字段中输入代码。
系统应用符合条件的折扣，并立即更新总额。

在 Checkout Sessions 中，传入 discount_codes（数组）以预先应用一个或多个代码，并设置 feature_flags.allow_discount_code 以显示输入字段。代码按照数组顺序应用，最多 20 个。

叠加折扣代码

Checkout sessions、payments 和 subscriptions 通过 discount_codes 数组接受最多 20 个叠加代码（最多 20 个条目）。代码会按照数组顺序应用：第一个符合条件的代码先降低基础价格，后续代码再降低已经折扣后的价格，以此类推。所有已应用的折扣都会在响应中返回：payments/subscriptions 使用 discount_ids，discounts 则提供更丰富的每个折扣详情，包括位置和剩余 Subscription 周期。

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 管理

Create discounts

通过编程方式创建带有类型和金额的折扣代码。

API Reference

查看创建折扣 API。

List and retrieve

列出所有折扣，或获取用于管理和审计的详情。

API Reference

浏览列出和获取 API。

Get discount by code

使用人类可读的代码（例如 “SAVE20”）而不是内部 ID 查找折扣。

API Reference

按代码名称获取折扣。

Update discounts

修改折扣配置，例如金额、过期时间或限制。

API Reference

了解如何更新折扣详情。

Validate discounts

在应用折扣前，检查折扣是否有效且适用。

API Reference

验证折扣使用情况。

Delete discounts

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

API Reference

删除折扣。

Manage the customer allow list

对于 customer_eligibility 设置为 specific 的折扣，管理可以兑换该折扣的客户：

GET /discounts/{discount_id}/customers — 列出已添加的客户（分页显示，每页最多 100 个）。
POST /discounts/{discount_id}/customers — 按 ID 添加客户。该调用具有幂等性，最多接受 1000 个 ID，并且这些 ID 必须已存在于你的业务中。响应仅返回本次请求中提交的 ID，因此请使用 list endpoint 读取完整的允许列表。
DELETE /discounts/{discount_id}/customers/{customer_id} — 移除单个客户。

常见使用场景

新客优惠：针对新产品的限时发布促销
批量或 B2B：面向特定产品组合的合同折扣
客户留存：在防止客户流失的工作流中使用召回代码
季节性活动：基于节日或活动的促销

集成示例

创建带有 Metadata 的折扣

附加自定义键值对，用于内部跟踪。

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

使用 Metadata 按活动、来源或内部参考 ID 标记折扣，以便之后核对使用情况并衡量 ROI。

在 Checkout Sessions 中应用折扣

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

在计划变更期间应用折扣

在客户升级或降级 Subscription 时提供促销价格。

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` 的现有折扣。
`[]`（空数组）	所有现有折扣都会从 Subscription 中移除。
`['CODE_A', 'CODE_B', ...]`	使用此叠加集合替换所有现有折扣，并按照数组顺序应用。

通过 Subscription 响应中新的 discounts 数组，读取 Subscription 上所有已应用的折扣。每个条目包括 discount_id、position、cycles_remaining（用于 Subscription），以及原始代码。

启用折扣输入但不预先应用

允许客户在结账时输入代码，而无需预先传入代码。

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

最佳实践

清晰命名：使用易于识别且与活动名称匹配的代码
设置时间范围：添加过期时间以营造紧迫感并防止滥用
合理限定范围：限制为特定产品，避免利润流失
尽早验证：确认结账前检查代码是否适用
监控影响：按活动跟踪使用情况和转化率

折扣代码是获取客户和提升留存的有力工具。请从简单、命名清晰的优惠开始，进行全面验证，并根据效果持续迭代。

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

什么是折扣码？

主要优点

创建折扣码

Dashboard 设置

折扣类型

客户资格

按货币设置的选项

结账体验

叠加折扣代码

API 管理

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

常见使用场景

集成示例

创建带有 Metadata 的折扣

在 Checkout Sessions 中应用折扣

在计划变更期间应用折扣

启用折扣输入但不预先应用

最佳实践

Checkout Sessions

Validate Discount

Get Discount by Code

Create Discount (API)

List & Update Discounts

Plan Change Discounts

​什么是折扣码？

​主要优点

​创建折扣码

​Dashboard 设置

​折扣类型

​客户资格

​按货币设置的选项

​结账体验

​叠加折扣代码

​API 管理

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

​常见使用场景

​集成示例

​创建带有 Metadata 的折扣

​在 Checkout Sessions 中应用折扣

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

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

​最佳实践

什么是折扣码？

主要优点

创建折扣码

Dashboard 设置

折扣类型

客户资格

按货币设置的选项

结账体验

叠加折扣代码

API 管理

常见使用场景

集成示例

创建带有 Metadata 的折扣

在 Checkout Sessions 中应用折扣

在计划变更期间应用折扣

启用折扣输入但不预先应用

最佳实践