> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# トライアルのプレビュー
> サブスクリプション checkout session のトライアル資格とトライアル日数をプレビューする
サブスクリプション checkout session のトライアル期間をプレビューします — customer がトライアルの対象かどうか、およびトライアル日数を返します。
```
POST /v1/actions/checkout/preview-trial
```
**認証：** Store Slug（visitor）— customer session token も受け付けます
このエンドポイントは customer session token も受け付けます — [Customer Session エンドポイント](/ja/api-reference/endpoints/auth/customer-endpoints) を参照。Customer トークンで呼び出す場合、customer の身元はトークンから取得され、リクエストボディの `buyerIdentity` フィールドは上書きされます。
## 資格判定ルール
資格は、customer がこの製品（または同じ製品グループ内の製品）に対して既にトライアル記録を持っているかどうかに基づきます：
* トライアル記録なし → `isEligible: true`、`trialDays` は製品設定のトライアル日数
* トライアル記録あり → `isEligible: false`、`trialDays` は `null`
Visitor 呼び出しで `buyerIdentity` が空の場合、新規 customer として扱われ、常に `isEligible: true` を返します。
## リクエストボディ
| フィールド | 型 | 必須 | 説明 |
| ------------------- | ------ | ---- | ------------------------------------------------------------------------------------------ |
| `checkoutSessionId` | string | Yes | Checkout Session 作成で返された session ID（サブスクリプション製品である必要があります） |
| `buyerIdentity` | string | 条件付き | customer のメールアドレス。Customer モードではトークンから取得（必須）；visitor モードでは任意 — 省略するとレコード照会なしで完全なトライアルを返します |
## リクエスト例
```typescript TypeScript (SDK) theme={"system"}
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: "customer@example.com",
});
console.log(result.isEligible); // true
console.log(result.trialDays); // 14
```
```typescript TypeScript (Manual) theme={"system"}
// Assumes callApi() is defined as shown in the Authentication guide
const result = await callApi("POST", "/v1/actions/checkout/preview-trial", {
checkoutSessionId: "cs_550e8400-e29b-41d4-a716-446655440000",
buyerIdentity: "customer@example.com",
});
```
```java Java theme={"system"}
// Assumes callApi() is defined as shown in the Authentication guide
String result = callApi("POST", "/v1/actions/checkout/preview-trial",
"{\"checkoutSessionId\":\"cs_550e8400-e29b-41d4-a716-446655440000\","
+ "\"buyerIdentity\":\"customer@example.com\"}");
```
```python Python theme={"system"}
# Assumes call_api() is defined as shown in the Authentication guide
result = call_api("POST", "/v1/actions/checkout/preview-trial", {
"checkoutSessionId": "cs_550e8400-e29b-41d4-a716-446655440000",
"buyerIdentity": "customer@example.com",
})
```
```go Go theme={"system"}
// Assumes callAPI() is defined as shown in the Authentication guide
result, err := callAPI("POST", "/v1/actions/checkout/preview-trial",
`{"checkoutSessionId":"cs_550e8400-e29b-41d4-a716-446655440000","buyerIdentity":"customer@example.com"}`)
```
```rust Rust theme={"system"}
// Assumes call_api() is defined as shown in the Authentication guide
let result = call_api("POST", "/v1/actions/checkout/preview-trial",
r#"{"checkoutSessionId":"cs_550e8400-e29b-41d4-a716-446655440000","buyerIdentity":"customer@example.com"}"#
).await?;
```
```c C theme={"system"}
// Assumes call_api() is defined as shown in the Authentication guide
call_api("/v1/actions/checkout/preview-trial",
"{\"checkoutSessionId\":\"cs_550e8400-e29b-41d4-a716-446655440000\","
"\"buyerIdentity\":\"customer@example.com\"}");
```
```cpp C++ theme={"system"}
// Assumes call_api() is defined as shown in the Authentication guide
auto result = call_api("/v1/actions/checkout/preview-trial",
R"({"checkoutSessionId":"cs_550e8400-e29b-41d4-a716-446655440000","buyerIdentity":"customer@example.com"})");
```
```bash cURL theme={"system"}
curl -X POST "https://api.waffo.ai/v1/actions/checkout/preview-trial" \
-H "Content-Type: application/json" \
-H "X-Store-Slug: my-store-abc123" \
-H "X-Environment: test" \
-d '{
"checkoutSessionId": "cs_550e8400-e29b-41d4-a716-446655440000",
"buyerIdentity": "customer@example.com"
}'
```
```bash wget theme={"system"}
wget -qO- \
--header="Content-Type: application/json" \
--header="X-Store-Slug: my-store-abc123" \
--header="X-Environment: test" \
--post-data='{"checkoutSessionId":"cs_550e8400-e29b-41d4-a716-446655440000","buyerIdentity":"customer@example.com"}' \
"https://api.waffo.ai/v1/actions/checkout/preview-trial"
```
## 成功レスポンス (200) -- 対象
```json theme={"system"}
{
"data": {
"isEligible": true,
"trialDays": 14
}
}
```
## 成功レスポンス (200) -- 対象外
```json theme={"system"}
{
"data": {
"isEligible": false,
"trialDays": null
}
}
```
### レスポンスフィールド
| フィールド | 型 | 説明 |
| ------------ | -------------- | ----------------------------------------- |
| `isEligible` | boolean | customer がトライアル対象かどうか（トライアル記録なし = `true`） |
| `trialDays` | number \| null | 対象の場合はトライアル日数；対象外の場合は `null` |
## エラー
> **リトライポリシー**：4xx は一切リトライしない — リクエストを修正してから再送信。5xx は指数バックオフでリトライ（5s 開始、最大 3 回）。
| ステータス | `errors[0].message` | 意味 | 推奨処理 |
| ----- | ------------------------------------------------------ | -------------------------------- | ------------------------------------ |
| 400 | `Invalid JSON body` | リクエストボディが有効な JSON ではない | ボディを修正してから再送信 |
| 400 | `Missing required field: checkoutSessionId` | `checkoutSessionId` が提供されていない | ボディを修正してから再送信 |
| 400 | `Session product type mismatch: expected subscription` | Session がワンタイム製品で作成されている | サブスクリプション checkout session を作成してリトライ |
| 401 | `Unauthorized` | Store Slug または session token が無効 | 認証ヘッダーを確認 |
| 404 | `Session not found` | Checkout session が存在しないか期限切れ | 新しい checkout session を作成してリトライ |
| 404 | `Session does not belong to this store` | Session が別のストアのもの | 呼び出し元のストアに属する session を使用 |
| 500 | `Internal server error` | サーバ側の予期しない障害 | 指数バックオフでリトライ（5s 開始、最大 3 回） |