先配置并激活折扣 Reward，明确领取渠道与规则。Customer 持有的 grant 与 Reward 定义、promotion code 是不同身份。
Coupon 与 Reward
配置优惠、定向或人群发放，读取持券并在购买中使用。
SDK 示例对应当前 API。核对匹配版本与 HTTP 接入方式
API v1更新于
开始前准备
Coupon and Reward
A Coupon is a percentage- or fixed-discount Reward. Terms, promotion codes, Customer possession and verified redemption are separate facts. Coupons are independent of Offering, Paywall and Funnel.
- 在 Offers & rewards 配置折扣、适用 Product、期限与 claim rules；生效条款锁定。每个 Customer 的限领次数包含所有未撤销记录，即使已过期；总名额与代码容量只计预留、已核销和未过期的 issued。
- 可使用 code、后端定向发放或保存的人群发放。人群批次冻结名单，每次最多处理 50 人；后续加入人群的 Customer 不会自动进入原批次。
发放、读取与购买使用
grantOffer 和 redeemCoupon 需要稳定 requestId；响应丢失复用原输入。quote 只预留持券，失败或过期释放，服务端验证的购买成功才核销。展示、刷新、点击按钮或完成 Funnel 都不表示核销。
// Trusted backend: current authenticated Customer; offers:grant.await indiana.grantOffer({ customerId: verifiedCustomer.id, couponId, requestId });// Identified browser: offers:resolve.const { offers } = await grow.listOffers();const redeemed = await grow.redeemCoupon({ code: "WELCOME", requestId: codeRequestId });if (!redeemed.offer) throw new Error(redeemed.reason ?? "Coupon unavailable");// Use the held grant's ID, not couponId, in a purchase:const { quote } = await grow.previewAttach({ requestId: purchaseRequestId, plans: [{ productVersionId: selectedProductId }], provider: "stripe", currency: "USD", offerId: redeemed.offer.id,});对应 HTTP 接口
可以在已完成的 HTTP 接入上调用这些操作。每页参考列出完整请求、响应和凭据要求；有匹配 SDK 时，也可使用本页 SDK 示例。
| 操作 | HTTP | 权限 |
|---|---|---|
| listOffers | GET /api/v1/offers | offers:resolve |
| redeemReward | POST /api/v1/rewards/redeem | offers:resolve |
| grantOffer | POST /api/v1/offers/grant | offers:grant |
操作与权限
listOffers
- HTTP
- GET /api/v1/offers
- 权限
- offers:resolve
redeemReward
- HTTP
- POST /api/v1/rewards/redeem
- 权限
- offers:resolve
grantOffer
- HTTP
- POST /api/v1/offers/grant
- 权限
- offers:grant
完成后检查
预期结果
读取资格与持券；购买时引用真实 grant，取消或过期释放，付款验证后核销。预览优惠不表示已经领券。