Skip to main content
Preview the trial period for a subscription checkout session — returns whether the buyer 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
This endpoint also accepts a customer session token — see Customer Session Endpoints. When called with a customer token, the buyer identity is taken from the token and overrides any buyerIdentity field in the request body.

​
Eligibility Rule

Eligibility is based on whether the buyer 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 buyer and always returns isEligible: true.

​
Request Body

FieldTypeRequiredDescription
checkoutSessionIdstringYesCheckout session ID returned by Create Checkout Session (must be a subscription product)
buyerIdentitystringConditionalBuyer email. Required in customer mode (taken from the token); optional in visitor mode — omitting it returns the full trial without record lookup

​
Example Request

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

// 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: "buyer@example.com",
});

// 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\":\"buyer@example.com\"}");

# 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": "buyer@example.com",
})

// 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":"buyer@example.com"}`)

// 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":"buyer@example.com"}"#
).await?;

// 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\":\"buyer@example.com\"}");

// 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":"buyer@example.com"})");

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": "buyer@example.com"
  }'

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":"buyer@example.com"}' \
  "https://api.waffo.ai/v1/actions/checkout/preview-trial"

​
Success Response (200) — Eligible

{
  "data": {
    "isEligible": true,
    "trialDays": 14
  }
}

​
Success Response (200) — Not Eligible

{
  "data": {
    "isEligible": false,
    "trialDays": null
  }
}

​
Response Fields

FieldTypeDescription
isEligiblebooleanWhether the buyer is eligible for a trial (no prior trial record = true)
trialDaysnumber | nullTrial 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).
Statuserrors[0].messageWhat it meansRecommended handling
400Invalid JSON bodyRequest body is not valid JSONFix the body, resubmit
400Missing required field: checkoutSessionIdcheckoutSessionId was not providedFix the body, resubmit
400Session product type mismatch: expected subscriptionThe session was created for a one-time productCreate a subscription checkout session and retry
401UnauthorizedInvalid Store Slug or session tokenVerify auth headers
404Session not foundCheckout session does not exist or has expiredCreate a new checkout session and retry
404Session does not belong to this storeThe session was created for a different storeUse a session belonging to the calling store
500Internal server errorUnexpected server-side failureRetry with exponential backoff (start 5s, max 3 attempts)