メインコンテンツへスキップ
商品バージョン、価格、通貨を固定するチェックアウトセッションを作成します。これは単発商品とサブスクリプション商品の両方のチェックアウトフローの最初のステップです。 一般的なフローは次のとおりです：
  1. マーチャントがチェックアウトセッションを作成（サーバーサイド）
  2. checkoutUrl をフロントエンドに返す
  3. 消費者がリンクをクリックしてホスティングチェックアウトページにアクセス
  4. 消費者が請求情報を入力し、税金をプレビューし、注文を完了
POST /v1/actions/checkout/create-session
認証： API Key or Store Slug

​
リクエストボディ (API Key)

フィールド型必須説明
storeIdstringはいストア ID（Short ID 形式 STO_xxx）
productIdstringはい商品 ID（Short ID 形式 PROD_xxx）
productTypestringはいonetime または subscription
currencystringはいISO 4217 通貨コード（例：USD、EUR、JPY）
priceSnapshotobjectいいえセッション作成時の価格オーバーライド（API Key のみ）
withTrialbooleanいいえトライアル期間を有効にする（サブスクリプション商品のみ）
buyerEmailstringいいえチェックアウトページで消費者のメールを事前入力
billingDetailobjectいいえ請求詳細を事前入力（下記参照）
successUrlstringいいえ支払い成功後のリダイレクト URL のオーバーライド
expiresInSecondsnumberいいえセッション TTL（秒）（デフォルト：2700 = 45分、API Key のみ）
darkModebooleanいいえチェックアウトページのダークモードを有効にする
metadataobjectいいえセッションに添付するカスタムキーバリューペア

​
リクエストボディ (Store Slug)

フィールド型必須説明
productIdstringはい商品 ID（Short ID 形式 PROD_xxx）
productTypestringはいonetime または subscription
currencystringはいISO 4217 通貨コード
withTrialbooleanいいえトライアル期間を有効にする（サブスクリプション商品のみ）
buyerEmailstringいいえ消費者のメールを事前入力
billingDetailobjectいいえ請求詳細を事前入力（下記参照）
successUrlstringいいえ支払い成功後のリダイレクト URL のオーバーライド
darkModebooleanいいえチェックアウトページのダークモードを有効にする
metadataobjectいいえセッションに添付するカスタムキーバリューペア
Store Slug 認証では、クライアント側からの価格改ざんとセッション操作を防止するため、priceSnapshot と expiresInSeconds はサポートされていません。

​
請求詳細オブジェクト

フィールド型必須説明
countrystringはいISO 3166-1 alpha-2 国コード（例：US、JP、DE）
isBusinessbooleanはいビジネス購入かどうか
postcodestringいいえ郵便番号
statestring条件付きUS と CA の場合に必須（例：CA、NY、ON）
businessNamestring条件付きisBusiness が true の場合に必須
taxIdstring条件付きisBusiness が true の場合に EU 諸国で必須（VAT 番号）

​
セッションロック

チェックアウトセッションが作成されると、以下の値が固定され、セッションの有効期間中は変更できません： productVersionId, productName, priceInfo, storeName, billingPeriod, withTrial, theme, buyerEmail, billingDetail

​
リクエスト例

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

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

const session = await client.checkout.createSession({
  storeId: "STO_2D5F8G3H1K4M6N9P",
  productId: "PROD_7J3K5L8M2N4P6Q9R",
  productType: CheckoutSessionProductType.Onetime,
  currency: "USD",
  buyerEmail: "customer@example.com",
  successUrl: "https://example.com/thank-you",
});

console.log(session.sessionId);   // "cs_550e8400-e29b-41d4-a716-446655440000"
console.log(session.checkoutUrl); // "https://checkout.waffo.ai/..."
console.log(session.expiresAt);   // "2026-01-22T10:30:00.000Z"

​
成功レスポンス

{
  "data": {
    "sessionId": "cs_550e8400-e29b-41d4-a716-446655440000",
    "checkoutUrl": "https://checkout.waffo.ai/my-store-abc123/checkout/cs_550e8400-e29b-41d4-a716-446655440000",
    "expiresAt": "2026-01-22T10:30:00.000Z"
  }
}

​
レスポンスフィールド

フィールド型説明
sessionIdstringチェックアウトセッション ID（cs_ + UUID 形式、Short ID ではありません）
checkoutUrlstring消費者をホスティングチェックアウトページにリダイレクトするための完全な URL
expiresAtstringセッションの有効期限（ISO 8601 タイムスタンプ）

​
エラー

ステータスメッセージ説明
400必須フィールドが欠落していますproductId、productType、または currency が欠落しています
400Invalid productTypeonetime または subscription でなければなりません
400Invalid billingDetail請求詳細のバリデーション失敗（例：US の場合に state が欠落）
401Unauthorized無効な API Key 署名または Store Slug
403Store not activeストアが active ステータスではありません
403Store not production enabledストアがライブ支払いを処理できません
403Product not in store商品が指定されたストアに属していません
404ストアが見つかりません指定された storeId またはスラッグに一致するストアがありません
404商品が見つかりません指定された productId に一致する商品がありません
デフォルトのセッション TTL は45分（2700秒）です。API Key 認証を使用する場合、expiresInSeconds でカスタマイズできます。セッションは作成時に商品バージョンと価格を固定するため、価格変更は既存のセッションに影響しません。