优惠券

创建顾客在结账时可使用的折扣码。支持百分比折扣或固定金额折扣，可设置时间限制或使用上限，适用于一次性或周期性场景。

优惠券可在 Builder 的 Commerce 面板 > Products > Coupons 子标签页中管理，也可通过 SDK 的 proyecta.commerce.coupons 进行操作。

优惠券字段说明

字段	备注
code	顾客在结账时输入的促销码（例如 LAUNCH20）
percent_off 或 amount_off	二选一，不可同时使用。百分比范围为 1–100；金额以最小货币单位（分）表示。
currency	amount_off 折扣必填（三位字母 ISO 货币代码）。创建时接受并转发至 Stripe，但不会被 API 存储或返回。
duration	once（仅首次付款）、repeating（持续 duration_in_months 个月）或 forever
duration_in_months	当 duration 为 repeating 时必填
max_redemptions	所有顾客的总使用上限
redeem_by	优惠券的失效日期，超过该日期后将无法使用
name	展示给顾客的显示名称
active	启用/禁用开关，无需删除即可控制是否生效

创建优惠券

在 Coupons 子标签页中点击 Add coupon 并填写相关字段，或通过 SDK 创建：

// 永久八折优惠
await proyecta.commerce.coupons.create({
    code: 'LAUNCH20',
    name: 'Launch discount',
    percent_off: 20,
    duration: 'forever',
});

// 减免 $10，单次使用，30 天后到期
await proyecta.commerce.coupons.create({
    code: 'WELCOME10',
    amount_off: 1000,
    currency: 'USD',
    duration: 'once',
    max_redemptions: 1,
    redeem_by: new Date(Date.now() + 30 * 86400 * 1000).toISOString(),
});

// 订阅前 3 个月享受五折优惠
await proyecta.commerce.coupons.create({
    code: 'EARLY3',
    percent_off: 50,
    duration: 'repeating',
    duration_in_months: 3,
});

在结账时应用优惠券

顾客可以在 Stripe 托管的结账页面上自行输入优惠码——促销码输入框会自动显示。

await proyecta.commerce.checkout({
    customer_id,
    line_items: [{ variant_id: 'var_pro_monthly' }],
    success_url: 'https://myapp.com/welcome',
});

目前暂不支持在结账调用中以编程方式传入优惠码。

列出、更新、停用

// 查看所有优惠券（仅列出通过 SDK 创建的优惠券）
const { data } = await proyecta.commerce.coupons.list();
for (const coupon of data.data) {
    console.log(coupon.code, coupon.times_redeemed, '/', coupon.max_redemptions);
}
// 如需分页，可使用 data.has_more 和 starting_after 查询参数。

// 禁用优惠券（不删除）
await proyecta.commerce.coupons.update({ couponId: 'coupon_123', active: false });

注意： coupons.list() 仅返回通过 SDK 创建的优惠券。在 Builder Dashboard 中创建的优惠券无法通过 coupons.list() 查看。

注意事项与限制

• 优惠码和折扣金额不可修改。 你可以更新显示 name 并切换 active 状态，但无法修改 percent_off、amount_off 或 code 本身。如需更改条款，请创建新的优惠券。
• times_redeemed 会自动递增，为只读字段——可用于追踪推广活动的效果。
• 优惠券按顾客生效，而非按订单——如果一张优惠券设置为 forever，且顾客已订阅，则每次续费都将享受该折扣。