跳转到主要内容
创建优惠券及它自己的 code —— 买家可在收银台输入 —— 并可同时创建最多 20 个促销码。全部内容在一次请求中创建:优惠券、它的码与全部促销码一起生效,或者都不创建。优惠券只按到期时间(redeemBy)与总兑换次数(maxRedemptions)限制兑换;买家限制(限定买家邮箱、每位买家次数、最低消费)设置在促销码上。优惠券也可在结账会话上通过 couponId 使用;之后可用创建促销码补充促销码。
认证方式: API Key(店铺 owner 或 admin)

请求体

优惠对象

促销码对象

promotionCodes 的每一项与创建促销码的字段相同(不含 couponId):

请求示例

成功响应 (200)

响应字段

响应包裹在 data.coupon 中。
创建在本次请求内要么成功、要么失败。200 响应中的优惠券始终为 active。支付服务商拒绝或未确认创建时返回 502,优惠券记为 failed,本次请求的全部码已释放 —— 可以重新创建,也可以继续使用同样的码。请求在完成前中途中断时,优惠券可能停留在 pending 并占用它的码;这样的优惠券创建超过 10 分钟后,会由同一店铺同一环境的下一次创建优惠券、创建促销码或批量生成促销码请求就地清理 —— 记为 failed,码被释放。

带 warnings 的响应

优惠券变为 active 后它的码即可使用,请求不会再失败。若此时 Pancake 无法把金额换算为显示格式,仍返回 200 和 active 的优惠券:amountOff 与每个 promotionCodes[].restrictions.minimumAmount 为 null —— 响应结构不变 —— 并在响应顶层附带 warnings 数组,说明金额未换算。其余字段照常返回。
优惠券已按请求创建 —— 不要再次创建。用 GraphQL coupon(id) 查询该优惠券以获取金额。

错误响应

重试策略:4xx 一律不要重试 — 修正请求后重发。5xx 指数退避重试(起步 5s,最多 3 次)。重试时始终使用同一个 X-Idempotency-Key。