Customer Portal API Overview

Endpoints the customer’s browser calls with a session token minted via Issue Session Token

The Customer Portal API is the customer-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

Header	Value
Authorization	Bearer <session-token> (the JWT returned by Issue Session Token)
X-Environment	test or prod (must match the environment the token was minted for)

The gateway derives the customer identity and visiting store from the token; you do not pass them as separate headers.

Endpoints

Cancel One-time Order

Cancel a pending one-time order before payment completes

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:

Status	errors[0].message	What it means
400	Missing X-Context-Buyer-Identity header	Token did not carry a customer identity (buyerIdentity) claim — re-mint the token
400	Missing X-Context-Visiting-Store-Id header	Token was not scoped to a store — re-mint with visitingStoreId
401	Authentication failed	Session token expired, malformed, or signed for a different merchant