メインコンテンツへスキップ
サブスクリプション checkout session のトライアル期間をプレビューします — 買い手がトライアルの対象かどうか、およびトライアル日数を返します。 
POST /v1/actions/checkout/preview-trial
認証： Store Slug（visitor）— customer session token も受け付けます
このエンドポイントは customer session token も受け付けます — Customer Session エンドポイント を参照。Customer トークンで呼び出す場合、買い手の身元はトークンから取得され、リクエストボディの buyerIdentity フィールドは上書きされます。

​
資格判定ルール

資格は、買い手がこの製品（または同じ製品グループ内の製品）に対して既にトライアル記録を持っているかどうかに基づきます：
  • トライアル記録なし → isEligible: true、trialDays は製品設定のトライアル日数
  • トライアル記録あり → isEligible: false、trialDays は null
Visitor 呼び出しで buyerIdentity が空の場合、新規買い手として扱われ、常に isEligible: true を返します。

​
リクエストボディ

フィールド型必須説明
checkoutSessionIdstringYesCheckout Session 作成で返された session ID（サブスクリプション製品である必要があります）
buyerIdentitystring条件付き買い手のメールアドレス。Customer モードではトークンから取得（必須）；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: checkoutSessionIdcheckoutSessionId が提供されていないボディを修正してから再送信
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 回）