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

​
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)