> ## 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.

# Preview Trial

> Preview the trial eligibility and trial days for a subscription checkout session

Preview the trial period for a subscription checkout session — returns whether the customer is eligible for a trial and the trial day count.

```
POST /v1/actions/checkout/preview-trial
```

**Authentication:** Store Slug (visitor) — also accepts a customer session token

<Note>
  This endpoint also accepts a customer session token — see [Customer Session Endpoints](/api-reference/endpoints/auth/customer-endpoints). When called with a customer token, the customer identity is taken from the token and overrides any `buyerIdentity` field in the request body.
</Note>

## Eligibility Rule

Eligibility is based on whether the customer already has a trial record on this product (or any product in the same product group):

* No prior trial record → `isEligible: true`, `trialDays` reflects the product's configured trial length
* Trial record exists → `isEligible: false`, `trialDays` is `null`

A visitor call with no `buyerIdentity` is treated as a brand-new customer and always returns `isEligible: true`.

## Request Body

| Field               | Type   | Required    | Description                                                                                                                                           |
| ------------------- | ------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `checkoutSessionId` | string | Yes         | Checkout session ID returned by Create Checkout Session (must be a subscription product)                                                              |
| `buyerIdentity`     | string | Conditional | Customer email. Required in customer mode (taken from the token); optional in visitor mode — omitting it returns the full trial without record lookup |

## Example Request

<CodeGroup>
  ```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"
  ```
</CodeGroup>

## Success Response (200) -- Eligible

```json theme={"system"}
{
  "data": {
    "isEligible": true,
    "trialDays": 14
  }
}
```

## Success Response (200) -- Not Eligible

```json theme={"system"}
{
  "data": {
    "isEligible": false,
    "trialDays": null
  }
}
```

### Response Fields

| Field        | Type           | Description                                                                   |
| ------------ | -------------- | ----------------------------------------------------------------------------- |
| `isEligible` | boolean        | Whether the customer is eligible for a trial (no prior trial record = `true`) |
| `trialDays`  | number \| null | Trial day count when eligible; `null` when not eligible                       |

## Errors

> **Retry policy:** Never retry 4xx — fix the request and resubmit. Retry 5xx with exponential backoff (start 5s, max 3 attempts).

| Status | `errors[0].message`                                    | What it means                                  | Recommended handling                                      |
| ------ | ------------------------------------------------------ | ---------------------------------------------- | --------------------------------------------------------- |
| 400    | `Invalid JSON body`                                    | Request body is not valid JSON                 | Fix the body, resubmit                                    |
| 400    | `Missing required field: checkoutSessionId`            | `checkoutSessionId` was not provided           | Fix the body, resubmit                                    |
| 400    | `Session product type mismatch: expected subscription` | The session was created for a one-time product | Create a subscription checkout session and retry          |
| 401    | `Unauthorized`                                         | Invalid Store Slug or session token            | Verify auth headers                                       |
| 404    | `Session not found`                                    | Checkout session does not exist or has expired | Create a new checkout session and retry                   |
| 404    | `Session does not belong to this store`                | The session was created for a different store  | Use a session belonging to the calling store              |
| 500    | `Internal server error`                                | Unexpected server-side failure                 | Retry with exponential backoff (start 5s, max 3 attempts) |