Points History — Build Your Own UI

Use these REST endpoints when you want the same data as the Points History widget without embedding the iframe or web component. The ledger payload matches the fields the widget renders.

Interactive API reference (Swagger / Redoc)

Open the live OpenAPI UI and jump to each operation:

Endpoint	Redoc
`GET /api/widget/points-history`	/api/docs#operation/getPointsHistory
`GET /api/widget/claim-rewards/balance`	/api/docs#operation/getPointsBalance
Full Widget tag	/api/docs#tag/Widget
Machine-readable spec	/api/docs/spec

Prerequisites

SSO client (clientId + clientSecret) with your origins registered — see SSO.
Pioneer widgets enabled on the deployment: PIONEER_WIDGETS=1. When the flag is off, these routes return 404.
Your Legion base URL (e.g. https://app.yourshop.com), referred to below as {BASE_URL}.

Authentication

Send an SSO (or hub) bearer token:

Authorization: Bearer {TOKEN}

Mint the token server-to-server via POST /api/auth/sso (never expose clientSecret in the browser), or use window.legionAuth.getToken() when the storefront runs the Legion SSO WordPress plugin. Middleware verifies the JWT and stamps x-user-id for the handlers — clients only need the Authorization header.

CORS is granted for origins registered on your SSO client.

Endpoints you need

1. Current balance (optional header)

GET {BASE_URL}/api/widget/claim-rewards/balance
Authorization: Bearer {TOKEN}

{
  "balance": 1500,
  "currency": "points",
  "asOf": "2026-06-15T22:14:03.000Z"
}

Use this for a balance badge above your history table. Swagger: getPointsBalance.

2. Paginated ledger (required)

GET {BASE_URL}/api/widget/points-history?limit=10&offset=0
Authorization: Bearer {TOKEN}

Query	Default	Notes
`limit`	`10`	Max `100`
`offset`	`0`	Skip N rows for pagination

{
  "data": [
    {
      "id": "b1c2d3e4-…",
      "amount": 150,
      "balance": 1500,
      "transaction_type": "earn",
      "description": "Order #1042",
      "reference_type": "order",
      "created_at": "2026-06-15T22:14:03.000Z"
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "total": 87 }
}

Rows are newest-first and scoped to the authenticated shopper on the current shop. Swagger: getPointsHistory.

Field → UI mapping

Field	Typical UI use
`created_at`	Date / time column
`description` or `transaction_type`	Label (prefer description when present)
`amount`	Signed points delta (`+150` / `-50`)
`balance`	Running balance after the row
`transaction_type`	Badge / filter (`earn`, `claim`, `redeem`, …)
`reference_type`	Optional secondary label (`order`, `point_claim`, …)
`pagination.total`	Page count / “Showing X–Y of Z”

Common transaction_type values: earn, claim, redeem, adjustment, refund, reversal. When the type is claim, reference_type is usually point_claim.

Minimal browser example

async function loadPointsHistory(
  baseUrl,
  token,
  { limit = 10, offset = 0 } = {}
) {
  const url = new URL("/api/widget/points-history", baseUrl);
  url.searchParams.set("limit", String(limit));
  url.searchParams.set("offset", String(offset));

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${token}` },
  });

  if (!res.ok) {
    throw new Error(`points-history failed: ${res.status}`);
  }

  return res.json(); // { data, pagination }
}

// Example: first page
const { data, pagination } = await loadPointsHistory(
  "https://app.yourshop.com",
  token,
  { limit: 10, offset: 0 }
);

Fetch the next page with offset = pagination.offset + pagination.limit while offset < pagination.total.

Reserved / claimable points

On shops that hold earnings as reservations until the shopper claims them:

List pending grants: GET /api/user/points/claimable
Claim: POST /api/user/points/claim
After a claim, refresh history — a single claim row appears in the ledger

Full walkthrough: Point Reservations guide.

If you prefer the packaged UI (table, theming, pagination):

Live preview: /widget/points-history
Customizer (embed code + attributes): /widgets/points-history/customize
Widgets index: /docs/widgets