折扣

​

什么是折扣码？

​

主要优点

• 灵活的折扣：基于百分比或固定金额的折扣
• 可叠加的 codes：每次结账、payment 或 subscription 最多应用 20 个 codes
• 定向控制：按产品、subscription 周期和客户资格进行限制
• 活动管理：计划开始日期、有效期、总使用次数和每位客户的使用次数限制
• 按货币定价：为每种货币设置固定扣减金额、金额上限和最低小计

​

创建折扣码

​

Dashboard 设置

• Discount Name（必填）：在 dashboard 中使用的内部标签。
• Code（必填）：客户在结账时输入的字符串。您可以生成随机 code，也可以输入自定义 code（至少 3 个字符，并会自动转换为大写）。
• Type（必填）：Percentage（按百分比减免）或 Amount（固定金额扣减）。
• Amount（必填）：对于 percentage，在 dashboard 中填写折扣百分比（例如，15 表示 15%）。通过 API 使用时，相同的值以 basis points 表示（1500）。对于 amount，填写 code 默认货币中的固定扣减金额。
• Start Date（可选）：安排 code 在未来日期启用。留空则立即启用。
• Expiration Date（可选）：超过此日期后，code 将无法再兑换。
• Usage Limit（可选，位于 Advanced 下）：所有客户累计可兑换的最大次数。
• Per-Customer Usage Limit（可选，位于 Advanced 下）：单个客户最多可兑换的次数。当两者都设置时，该值必须小于或等于总使用次数限制。
• Customer Eligibility（可选）：限制可兑换的客户范围——所有客户、首次购买客户、现有客户或手动选择的客户列表。
• Currency Options（可选）：您所销售的每种货币对应的折扣金额。请参阅 Per-Currency Options。
• Product Restriction（可选）：将 code 限制为特定产品。
• Subscription Cycle Limit（可选，位于 Advanced 下）：折扣适用的计费周期数。留空表示无限期适用。
• Preserve on Plan Change（可选）：当 subscription 更改计划时保持折扣有效（preserve_on_plan_change）。
• Metadata（可选）：附加自定义键值对，用于内部跟踪。
• Require a minimum order value（可选，位于 Advanced 下）：code 生效所需的最低购物车小计（按货币计算）。

​

折扣类型

​

客户资格

​

按货币设置选项

• Amount — 对于 Amount 折扣，表示该货币中的固定扣减金额；对于 Percentage 折扣，表示最大折扣上限。在 API 中映射到 max_amount_possible。
• Default — 将一种货币标记为默认货币。未配置的货币会根据此默认货币进行换算。

• Minimum subtotal — 仅当购物车在该货币中的小计达到此金额时，code 才会生效。0 表示无最低金额要求。

​

结账体验

​

叠加折扣代码

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  discount_codes: ['WELCOME10', 'BLACKFRIDAY20'], // applied in this order
  customer: { email: 'user@example.com' },
  return_url: 'https://yoursite.com/return'
});

​

API 管理

​

常见使用场景

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

​

集成示例

​

创建带 Metadata 的 Discount

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

​

在 Checkout Sessions 中应用 Discounts

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_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'
});

​

在计划变更期间应用 Discounts

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: ['UPGRADE20']
});

​

隐藏 Discount Code 字段

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  feature_flags: {
    allow_discount_code: false
  },
  return_url: 'https://yoursite.com/return'
});

​

最佳实践

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