跳转到主要内容
预览订阅 checkout session 的试用期 — 返回买家是否有试用资格以及试用天数。 
POST /v1/actions/checkout/preview-trial
认证方式： Store Slug（visitor）— 也接受 customer session token
此端点也接受 customer session token — 见 Customer Session 端点。使用 customer token 调用时，买家身份从 token 中取得，请求体中的 buyerIdentity 字段会被覆盖。

​
资格判定规则

资格判定基于买家在该产品（或同产品组内任一产品）是否已有试用记录：
  • 无试用记录 → isEligible: true，trialDays 返回产品配置的试用天数
  • 已有试用记录 → isEligible: false，trialDays 为 null
Visitor 模式下 buyerIdentity 为空时，视为全新买家，恒返回 isEligible: true。

​
请求体

字段类型必需说明
checkoutSessionIdstring是由「创建 Checkout Session」返回的会话 ID（必须是订阅产品）
buyerIdentitystring条件买家邮箱。Customer 模式下从 token 取得（必填）；visitor 模式可选 — 不传则视为有完整试用资格，不查记录

​
请求示例

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

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

const result = await client.checkout.previewTrial({
  storeSlug: "my-store-abc123",
  checkoutSessionId: "cs_550e8400-e29b-41d4-a716-446655440000",
  buyerIdentity: "buyer@example.com",
});

console.log(result.isEligible); // true
console.log(result.trialDays);  // 14

​
成功响应 (200) — 有试用资格

{
  "data": {
    "isEligible": true,
    "trialDays": 14
  }
}

​
成功响应 (200) — 无试用资格

{
  "data": {
    "isEligible": false,
    "trialDays": null
  }
}

​
响应字段

字段类型说明
isEligibleboolean是否有试用资格（无试用记录为 true）
trialDaysnumber | null有资格时返回试用天数；无资格时为 null

​
错误响应

重试策略：4xx 一律不要重试 — 修正请求后重发。5xx 指数退避重试（起步 5s，最多 3 次）。
状态码errors[0].message含义推荐处理
400Invalid JSON body请求体不是合法 JSON修正请求体后重新提交
400Missing required field: checkoutSessionId未提供 checkoutSessionId修正请求体后重新提交
400Session product type mismatch: expected subscriptionSession 是一次性产品创建的创建订阅类型的 checkout session 再重试
401UnauthorizedStore Slug 或 session token 无效检查认证请求头
404Session not foundCheckout session 不存在或已过期重新创建 checkout session 再重试
404Session does not belong to this storeSession 属于其他门店使用调用方门店的 session
500Internal server error服务端意外失败指数退避重试（起步 5s，最多 3 次）