税金プレビュー

チェックアウトセッションに適用される税ルールを照会し、請求情報が十分に揃った時点で計算済みの税額を取得します。このエンドポイントは段階的な収集を前提に設計されています：必須なのは billingDetail.country のみです。その国で追加的に必要となるフィールドは rules.requiredFields でレスポンスが示すため、チェックアウトフォームは最初から全てを要求せず、一つずつ順に尋ねられます。

POST /v1/actions/checkout/preview-tax

認証： Store Slug（visitor ロール）

このエンドポイントは、customer が請求情報を入力していく過程でホスティングされたチェックアウトページから呼び出されます。独自のチェックアウト UI を構築する場合は、customer の国または法人ステータスが変わるたびに呼び出してください。

リクエストボディ

フィールド	型	必須	説明
`checkoutSessionId`	string	Yes	チェックアウトセッションの作成が返すセッション ID
`billingDetail`	object	Yes	これまでに収集した請求情報（以下参照）

billingDetail

フィールド	型	必須	説明
`country`	string	Yes	ISO 3166-1 alpha-2 国コード（例：`US`、`DE`、`JP`）
`isBusiness`	boolean	No	法人購入かどうか
`state`	string	No	州・県コード
`postcode`	string	No	郵便番号
`businessName`	string	No	法人の正式名称
`taxId`	string	No	法人の税務登録番号（EU の VAT 番号など）

必須なのは country のみです。残りのどのフィールドを収集する必要があるかはレスポンスが決定します —— 国ごとの固定ルールではありません。rules.requiredFields を参照してください。

レスポンス

フィールド	型	説明
`currency`	string	チェックアウトセッションの通貨
`rules`	object	指定された国の税ルール
`calculation`	object \| null	計算済みの金額。フィールドがまだ足りない場合は `null`

rules

フィールド	型	説明
`country`	string	ルールが適用される国コード
`taxName`	string	税の名称（例：`JCT`、`VAT`）
`standardRate`	number	標準税率（小数表記、`0.1` = 10%）
`isTaxFree`	boolean	この国が非課税かどうか
`isEuReverseChargeEligible`	boolean	EU のリバースチャージが適用できるかどうか
`hasReducedRates`	boolean	一部の商品カテゴリに軽減税率が存在するかどうか
`requiredFields`	array	税額を計算する前にまだ必要なフィールド（以下参照）

requiredFields

各エントリは、チェックアウトフォームが次に収集すべきフィールドを 1 つ表します。

フィールド	型	説明
`field`	string	`isBusiness`、`state`、`postcode`、`businessName`、`taxId` のいずれか
`label`	string	入力欄に使用する可読ラベル
`reason`	string	その国でこれが必要な理由 —— customer に表示して問題ありません
`inputType`	string	推奨される入力コントロール

requiredFields が空の場合、calculation に値が入ります。

calculation

フィールド	型	説明
`subtotal`	string	税抜き金額（表示フォーマット、例：`"8.39"`）
`taxAmount`	string	税額（表示フォーマット）
`total`	string	customer に実際に請求される金額
`taxRate`	number	この注文に適用される税率

金額は API の他の部分と同様に表示フォーマットの文字列です。taxRate は小数（0.19 = 19%）です。

例

curl -X POST https://api.waffo.ai/v1/actions/checkout/preview-tax \
  -H "X-Store-Slug: my-store-abc123" \
  -H "X-Environment: prod" \
  -H "Content-Type: application/json" \
  -d '{
    "checkoutSessionId": "cs_xxx",
    "billingDetail": { "country": "US" }
  }'

curl -X POST https://api.waffo.ai/v1/actions/checkout/preview-tax \
  -H "X-Store-Slug: my-store-abc123" \
  -H "X-Environment: prod" \
  -H "Content-Type: application/json" \
  -d '{
    "checkoutSessionId": "cs_xxx",
    "billingDetail": { "country": "DE", "isBusiness": false }
  }'

情報が不足している場合 —— フォームは次に state を尋ねる必要があります。

{
  "data": {
    "currency": "USD",
    "rules": {
      "country": "US",
      "taxName": "Sales Tax",
      "standardRate": 0,
      "isTaxFree": false,
      "isEuReverseChargeEligible": false,
      "hasReducedRates": false,
      "requiredFields": [
        {
          "field": "state",
          "label": "State",
          "reason": "Sales tax in the United States is determined at state level",
          "inputType": "select"
        }
      ]
    },
    "calculation": null
  }
}

計算できる場合：

{
  "data": {
    "currency": "EUR",
    "rules": {
      "country": "DE",
      "taxName": "VAT",
      "standardRate": 0.19,
      "isTaxFree": false,
      "isEuReverseChargeEligible": true,
      "hasReducedRates": true,
      "requiredFields": []
    },
    "calculation": {
      "subtotal": "8.39",
      "taxAmount": "1.60",
      "total": "9.99",
      "taxRate": 0.19
    }
  }
}

エラー

ステータス	メッセージ	原因
400	`Missing required field: checkoutSessionId`	`checkoutSessionId` が指定されていない
400	`Missing required field: billingDetail.country`	`billingDetail` が欠落、または `country` を含まない
400	`Missing or invalid header: x-context-environment`	`X-Environment` ヘッダーが欠落、または `test` / `prod` 以外
404	`Checkout session not found or expired`	セッションが存在しない、期限切れ、別のストアに属する、または別の environment で作成された
500	`Internal server error`	サーバ側の予期しない障害

現在の税務カバレッジ

税の判定は customer の請求地に基づき、Waffo Pancake が記録商（Merchant of Record）として納税義務を負います。現在設定されているカバレッジでは、すべての国で taxAmount と taxRate は 0 が返ります —— このエンドポイントは、ある注文に実際に請求される金額の正式な情報源です。税率を仮定せず calculation.total を読み取ってください。 rules.requiredFields も同様に稼働中の設定によって決まります。「米国とカナダは state が必要」「EU の法人は税番号が必要」といった内容をチェックアウト UI にハードコードせず、レスポンスが要求する項目をそのままレンダリングしてください。

概要

認証

マーチャント API（API Key）

Customer Portal API（Session Token）

GraphQL

リクエストボディ

billingDetail

レスポンス

rules

requiredFields

calculation

例

エラー

現在の税務カバレッジ

​リクエストボディ

​billingDetail

​レスポンス

​rules

​requiredFields

​calculation

​例

​エラー

​現在の税務カバレッジ

リクエストボディ

billingDetail

レスポンス

rules

requiredFields

calculation

例

エラー

現在の税務カバレッジ