Skip to main content
The Customer Portal API is the buyer-side surface of Waffo. The merchant’s backend mints a short-lived session token via Issue Session Token, and the customer’s browser (or your in-product UI) calls the endpoints below with that token in the Authorization header. The merchant API Key never leaves the server.
Session tokens are scoped by buyerIdentity + visitingStoreId and only authorize operations on records that belong to that customer within that store. They cannot read merchant-wide state.

​
Required headers on every call

HeaderValue
AuthorizationBearer <session-token> (the JWT returned by Issue Session Token)
X-Environmenttest or prod (must match the environment the token was minted for)
The gateway derives the buyer identity and visiting store from the token; you do not pass them as separate headers.

​
Endpoints

Preview Trial

Check whether the customer is eligible for a trial period

Create One-time Order

Create a one-time order for the authenticated customer

Cancel One-time Order

Cancel a pending one-time order before payment completes

Create Subscription Order

Subscribe the authenticated customer to a recurring plan

Cancel Subscription

Cancel an active or pending subscription on behalf of the customer

Reactivate Subscription

Reverse a pending cancellation while still in canceling

Change Product

Switch the active subscription to a different product

GraphQL

Query the customer’s own orders, payments, and refunds

​
Token-path errors

These errors are surfaced only on the session-token call path:
Statuserrors[0].messageWhat it means
400Missing X-Context-Buyer-Identity headerToken did not carry a buyer identity claim — re-mint the token
400Missing X-Context-Visiting-Store-Id headerToken was not scoped to a store — re-mint with visitingStoreId
401Authentication failedSession token expired, malformed, or signed for a different merchant