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

# 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](/api-reference/endpoints/auth/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.

<Note>
  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.
</Note>

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

<CardGroup cols={2}>
  <Card title="Preview Trial" icon="circle-info" href="/api-reference/endpoints/orders/preview-trial">
    Check whether the customer is eligible for a trial period
  </Card>

  <Card title="Cancel One-time Order" icon="ban" href="/api-reference/endpoints/orders/cancel-onetime-order">
    Cancel a pending one-time order before payment completes
  </Card>

  <Card title="Cancel Subscription" icon="circle-stop" href="/api-reference/endpoints/subscriptions/cancel-subscription-customer">
    Cancel an active or pending subscription on behalf of the customer
  </Card>

  <Card title="Reactivate Subscription" icon="rotate" href="/api-reference/endpoints/subscriptions/reactivate-order">
    Reverse a pending cancellation while still in `canceling`
  </Card>

  <Card title="Change Product" icon="right-left" href="/api-reference/endpoints/subscriptions/change-product">
    Switch the active subscription to a different product
  </Card>

  <Card title="GraphQL" icon="diagram-project" href="/api-reference/endpoints/graphql/overview">
    Query the customer's own orders, payments, and refunds
  </Card>
</CardGroup>

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