跳转到主要内容
基于预先创建的 checkout session 创建订阅订单。返回 PSP 收银台 URL，引导买家跳转完成支付后即进入订阅。 
POST /v1/actions/subscription-order/create-order
认证方式： Session Token — 见 Customer Endpoints（customer 或 shopper 角色）

​
行为说明

  • 价格快照：下单时冻结订阅价格（price_snapshot），支持二阶段定价（regularPhase + 可选 specialPhase，后者用于试用期）。
  • 计费周期映射：weekly -> week/1，monthly -> month/1，quarterly -> month/3，yearly -> year/1。
  • PSP 容错：PSP 调用失败时本地订单自动取消，错误透传。
  • Session 预填回退：请求体中的 billingDetail 和 buyerEmail 会覆盖 session 上的预填值；两处都缺失时返回 400。
  • 邮箱规范化：buyerEmail 使用前先做 trim().toLowerCase() 规范化。
以下字段从 session 中获取，请求体中不要传：storeId、productId、billingPeriod、currency。即便传递也会被忽略。

​
请求体

字段类型必需说明
checkoutSessionIdstring是由 create-checkout-session 返回的 checkout session ID
billingDetailobject条件必填买家账单信息；若 session 未预填则必填
billingDetail.countrystringbillingDetail 存在时必填国家代码（ISO 3166-1 alpha-2）
billingDetail.isBusinessbooleanbillingDetail 存在时必填是否企业买家
billingDetail.postcodestring否邮编
billingDetail.statestringUS/CA 必填州 / 省代码
billingDetail.businessNamestringisBusiness=true 时必填企业法定名称
billingDetail.taxIdstringEU 企业买家必填税号（如 DE123456789）
buyerEmailstring条件必填买家邮箱；若 session 未预填则必填
buyerIpstring否买家 IP 地址（用于税务计算）
successUrlstring否收银台后跳转 URL；覆盖 session 级别的配置

​
请求示例

import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  sessionToken: window.WAFFO_SESSION_TOKEN, // 由商户门户注入
  environment: "prod",
});

const result = await client.orders.createSubscriptionOrder({
  checkoutSessionId: "cs_550e8400-e29b-41d4-a716-446655440000",
  billingDetail: {
    country: "DE",
    isBusiness: true,
    businessName: "Acme GmbH",
    taxId: "DE123456789",
  },
  buyerEmail: "customer@example.com",
  successUrl: "https://myapp.com/subscription/success",
});

console.log(result.checkoutUrl);

​
成功响应 (200)

{
  "data": {
    "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_xxx"
  }
}

​
响应字段

字段类型说明
checkoutUrlstringPSP 收银台页面 URL，引导买家跳转完成支付

​
错误响应

重试策略：4xx 一律不要重试 — 修正请求后重发。5xx 指数退避重试（起步 5s，最多 3 次）。
状态码errors[0].message含义推荐处理
400Invalid JSON body请求体不是合法 JSON修正请求体后重新提交
400Missing required field: checkoutSessionId请求体未提供 checkoutSessionId修正请求体后重新提交
400Session product type mismatch: expected subscriptionSession 是非订阅产品创建的改用订阅产品创建的 session
400Environment mismatch between request and session请求 X-Environment 与 session 环境不一致对齐请求环境与 session 环境
400Session missing subscription information (productVersionId or billingPeriod)Session 缺少必需的订阅字段重新创建 checkout session
400Missing billingDetail: provide in request body or pre-fill in checkout session请求体与 session 都没有 billingDetail在请求体中提供 billingDetail 后重新提交
400State is required for US/CAUS / CA 买家必须填写 billingDetail.state补充 billingDetail.state 后重新提交
401Authentication failedSession token 无效、过期或格式错误通过 Issue Session Token 重新签发
403Session does not belong to this storeSession 属于其他门店检查 session 的门店归属
409Checkout session invalid, please re-enter checkoutSession 不存在或已过期重新创建 checkout session
500Internal server error服务端意外失败指数退避重试（起步 5s，最多 3 次）