> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 折扣
> 创建促销代码来推动转换，开展活动，并通过一次性和订阅购买的百分比折扣奖励客户。
折扣代码让您可以运行有针对性的促销和激励。创建基于百分比的折扣，设置限制和到期时间，限制产品，并在结账时无缝应用。
在托管结账时，通过 `discount_codes` 和 UI 控件应用一个或多个叠加代码。
通过 ID 检查折扣是否有效。
使用代码名称（例如 "SAVE20"）查找并验证折扣。
以编程方式创建新的折扣码。
浏览和管理现有折扣；根据需要更新或删除。
在升级或降级订阅计划时应用折扣码。
## 什么是折扣码？
折扣码是结账时减少订单总额的促销代币。它们非常适合：
* **季节性活动**：黑色星期五、产品发布或周年庆
* **获取优惠**：首次购买奖励或推荐奖励
* **客户留存**：为现有客户提供的赢回或忠诚奖励
* **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`（每个折扣的更丰富细节，包括位置和剩余订阅周期）返回。
```typescript theme={null}
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。
列出所有折扣或检索详细信息以进行管理和审计。
浏览列表和检索 API。
使用可读代码（例如，“SAVE20”）代替内部 ID 查找折扣。
通过代码名检索折扣。
修改折扣配置，如金额、到期或限制。
了解如何更新折扣详细信息。
在应用之前检查折扣是否有效和适用。
验证折扣使用。
停用或移除不再需要的折扣。
删除折扣。
## 常见用例
* **介绍优惠**：新产品的限时发布促销
* **批量或 B2B**：特定产品组的合同折扣
* **保留方式**：防止流失工作流中的重获代码
* **季节性活动**：假日或事件为基础的促销
## 集成示例
### 创建带有元数据的折扣
附加自定义键值对以进行内部跟踪。
```typescript theme={null}
const discount = await client.discounts.create({
type: 'percentage',
amount: 1500, // 15%
code: 'SUMMER2025',
metadata: {
campaign: 'summer_promo',
source: 'email_blast'
}
});
```
使用元数据根据活动、来源或内部引用 ID 标记折扣，以便稍后核对使用情况并衡量投资回报率。
### 在结账会话中应用折扣
预先应用一个或多个叠加折扣，并显示代码输入 UI。
```typescript theme={null}
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'
});
```
### 在计划变更期间应用折扣
当客户升级或降级其订阅时提供促销定价。
```typescript theme={null}
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`（针对订阅）和原始代码。
### 启用折扣输入而不预先应用
允许客户在结账时输入代码而无需提前传递。
```typescript theme={null}
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'
});
```
## 最佳实践
* **清晰命名**：使用与活动名称匹配的可识别代码
* **时限**：添加截止日期以产生紧迫感并防止滥用
* **明智的范围**：限制到特定产品以避免利润损失
* **提前验证**：在确认结账前检查代码适用性
* **监控影响**：按活动跟踪使用情况和转化率
折扣代码是获取和保留的强大杠杆。从简单、命名良好的优惠开始，彻底验证，并根据表现反复改进。