Spend Side

Reversible Hold

Invoice-Settled

Reward Reservations (Spending Points)

This guide covers what happens after a shopper redeems a reward with their points. Redeeming no longer settles instantly: it creates a reservation — the points are deducted from the shopper's balance right away, but the redemption stays open until Legion sees the matching invoice from the commerce platform. If no invoice ever arrives, the reservation lapses and the points are automatically refunded.

This is the spend-side counterpart of claimable points (earn-side reservations, covered in the Earning tab above). A shopper first claims earned points into their spendable balance, then spends them on a reward — which creates the reservation described here.

How it works

Your site                    Legion (user-x)               Commerce / ERP (Sage)
─────────                    ───────────────               ─────────────────────
1. Shopper clicks "Claim" ─► POST /api/widget/claim-rewards/redeem
                             ├─ deducts points (reversible hold)
                             └─ returns sku + reservationCode + expiresAt
2. List open/synced holds ─► GET  /api/webhooks/claim-rewards/reservations
3. Create a Sage invoice with customerPONo = reservationCode
4. Legion invoice sync    ◄─ matches invoice to reservation
                             └─ finalizes: redemption → fulfilled
   …or, if no invoice arrives before expiresAt:
   Legion expiry sweep       └─ reservation → expired, points refunded

Your integration only changes at steps 2–3: pull reservations from Legion and create the Sage invoice yourself, stamping reservationCode as customerPONo. You do not need the shopper to place a commerce order or auto-insert the code into a cart/PO field. Step 4 is handled entirely by Legion's hourly invoice sync.

Reservation lifecycle

Status	Meaning
`pending`	Reserved. Points already deducted from the balance, but the hold is reversible.
`fulfilled`	Finalized. The invoice sync matched a Sage invoice to the reservation; the deduction is final.
`expired`	No invoice arrived before `expiresAt`. The points were refunded automatically.
`cancelled`	Reversed (e.g. order cancelled or refunded). The points were refunded.

Every transition is auditable: the finalizing invoice number, date, and customer are stamped into the redemption record, and the refund on expiry/cancellation appears in the shopper's points history as a refund transaction.

1. Redeeming creates the reservation

POST /api/widget/claim-rewards/redeem works exactly as before — same request, same authentication — but the response now carries two extra fields:

POST {BASE_URL}/api/widget/claim-rewards/redeem
Authorization: Bearer {TOKEN}
Content-Type: application/json

{ "rewardId": "b1f3…" }

{
  "redemptionId": "9c2a…",
  "transactionId": "4d7e…",
  "balance": 2500,
  "currency": "points",
  "sku": "STORE-CREDIT-100",
  "reservationCode": "RSV-Y3BZVH3R6HFZ",
  "expiresAt": "2026-08-21T16:14:03.000Z"
}

reservationCode — a short, unguessable code (RSV- + 12 characters) that uniquely identifies this reservation. It fits within Sage's 30-character customerPONo limit by design.
expiresAt — when the unfinalized reservation lapses and the points are refunded. The window is a per-deployment setting (30 days by default).

The shopper's balance returned here already reflects the deduction — display it as-is.

2. List reservations (server-to-server)

GET /api/webhooks/claim-rewards/reservations returns every pending (created, not yet matched) and fulfilled (already matched to an invoice) reservation in the shop. Expired, cancelled, and redemptions that never received a reservation code (commerce-only checkout or flat invoice deductions) are omitted.

GET {BASE_URL}/api/webhooks/claim-rewards/reservations
Authorization: Bearer {API_TOKEN}

Mint {API_TOKEN} yourself in the admin dashboard under Settings → API Tokens. The token is scoped to one shop and can be revoked there at any time; the same token authenticates the redeem and invoice-sync webhooks.

Query param	Default	Description
`status`	both	`pending` or `fulfilled`. Omit to return both.
`userId`	—	Restrict to one shopper.
`shopId`	token	Optional; must match the token's shop.
`page`	`1`	1-based page.
`limit`	`50`	Page size (max 200).

{
  "reservations": [
    {
      "id": "9c2a…",
      "userId": "…",
      "organizationId": null,
      "status": "pending",
      "reservationCode": "RSV-Y3BZVH3R6HFZ",
      "sku": "STORE-CREDIT-100",
      "rewardId": "b1f3…",
      "rewardName": "Store Credit $100",
      "pointsAmount": 1000,
      "requestedAt": "2026-08-19T18:00:00.000Z",
      "expiresAt": "2026-09-18T18:00:00.000Z",
      "fulfilledAt": null,
      "invoice": null
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 1 }
}

Use this list (or the reservationCode from the redeem response) when you create the Sage invoice. Fulfilled rows include invoice (invoiceNo, invoiceDate, customerNo, itemCode) for audit once the sync has matched.

3. Stamp the reservation code on the Sage invoice

When you send the reward to Sage, set the invoice's customer PO number to the reservationCode. The requirement is simply that the value arrives in Sage as the invoice's customerPONo.

Why it matters. The reservation code is the primary matching key. If it is missing, Legion falls back to matching by shopper + SKU, which works for one open reservation per SKU but cannot disambiguate a shopper with two pending reservations for the same reward. Always stamp the code when you create the invoice.

4. Legion finalizes (or expires) the reservation

You do not call anything for this step. Legion's invoice sync runs hourly:

It pulls new invoices from the ERP (Sage) since the last run.
For each invoice it looks for a pending reservation whose reservationCode equals the invoice's customerPONo (primary match), or — failing that — a pending reservation for the same shopper and an invoiced SKU (fallback match).
Matched reservations become fulfilled; the invoice number, date, and customer are recorded on the redemption for audit.
Reservations past expiresAt become expired and the points are refunded in the same sweep.

Fulfilled and expired reservations are visible to shop staff in the admin console (Points → Redemptions → History), including the reservation code and finalizing invoice number.

Monitoring from your side (optional)

Reservations list (GET /api/webhooks/claim-rewards/reservations) is the source of truth for open holds and already-synced invoices.
Points history (GET /api/widget/points-history) shows the initial deduction at redeem time and, if the reservation later expires or is cancelled, a refund row re-crediting the points.
Balance (GET /api/widget/claim-rewards/balance) always reflects holds: a pending reservation's points are not spendable.
Order webhook — if your platform already reports order events to POST /api/webhooks/claim-rewards/redeem, order.cancelled and order.refunded release the hold immediately instead of waiting for expiry.

Integration checklist

Redeem response's reservationCode and expiresAt captured.
Partner backend lists reservations via GET /api/webhooks/claim-rewards/reservations.
Sage invoice created with customerPONo = reservationCode (≤ 30 chars — the code always fits). Shopper does not need to place a commerce order for the hold to exist.
Balance shown from the redeem response / balance endpoint (already reflects the hold).
No point deduction on your side at invoice time — Legion owns the ledger.
(Optional) Cancellations/refunds reported to the redeem webhook for immediate release of the hold.
Shoppers informed that unfinalized reservations auto-refund after the expiry window.

Earn Side

Explicit Claim

Business-Day Expiry

Point Reservations (Claimable Points)

This guide is for partners integrating with shops that opt into claimable points. Some point grants are not credited to the spendable balance immediately — they are first held as a pending reservation that the shopper must explicitly claim. Unclaimed reservations expire after a per-shop timeout and are forfeited.

Campaign rewards credit instantly. Points earned by completing a campaign (claiming a points-based reward) are added to the spendable balance immediately — no reservation, no second claim step. Reservations apply to other grant paths, such as manual grants issued from the admin console.

Point reservations are part of the opt-in Point System and are distinct from XP (experience points). XP accrues automatically at earn time and drives rank/tier progression only; it is never reserved and is unaffected by claiming or expiry.

How it works

Your site                          Legion (user-x)
─────────                          ───────────────
1. Authenticate shopper   ───────► POST /api/auth/sso
                                   └─ returns SSO bearer token
2. List reservations      ───────► GET  /api/user/points/claimable
                                   └─ pending grants + total unclaimed points
3. Shopper clicks "Claim" ───────► POST /api/user/points/claim
                                   └─ credits spendable balance, returns new balance
4. Show updated ledger    ───────► GET  /api/widget/points-history
                                   └─ claim appears as one "claim" row

The lifecycle of a reservation (point_claims row):

Status	Meaning
`pending`	Reserved. XP already accrued, but the spendable balance is unchanged.
`claimed`	Converted into spendable balance via a `claim` ledger transaction.
`expired`	The reservation lapsed before it was claimed. The points are forfeited.
`revoked`	Withdrawn by the platform (e.g. a correction). The points are forfeited.

Expiry

Each reservation carries an expiry. The window is a per-shop setting configured in the admin console and enforced by the platform — storefronts do not set it. It is business-day aware by default (weekends do not count toward the timeout), so a Friday grant is not lost over the weekend.

Each reservation's expiresAt timestamp is included in the claimable endpoint's response (null means it never expires). Reservations whose expiry has already passed are omitted from the list.

Prerequisites

A registered SSO client (clientId + clientSecret) with your origins registered. See the SSO documentation.
Claimable points enabled for the shop (a per-shop platform setting — Legion handles this). On shops without it, points are credited directly and GET /api/user/points/claimable simply returns an empty list.
Your Legion base URL, e.g. https://app.yourshop.com (referred to below as {BASE_URL}).

1. Authentication

Both endpoints require an SSO bearer token in the Authorization header:

Authorization: Bearer {TOKEN}

Mint the token server-to-server via POST /api/auth/sso (never expose your clientSecret to the browser), or use window.legionAuth.getToken() if your storefront runs the legion-sso WordPress plugin. See /docs/sso and /docs/wordpress-plugin for the full flows.

CORS is granted for origins registered on your SSO client, so these endpoints can be called directly from the browser on an approved origin. Failed calls carry the same CORS headers as successful ones, so you can read the status and error body of a 401 (expired token) or 403 (origin not registered) instead of seeing an opaque network error.

2. Endpoint reference

GET `/api/user/points/claimable`

Lists the authenticated shopper's pending (unclaimed) point reservations, oldest first.

GET {BASE_URL}/api/user/points/claimable
Authorization: Bearer {TOKEN}

{
  "claims": [
    {
      "id": "7f3a9c2e-…",
      "amount": 150,
      "description": "Order #1042",
      "referenceType": "order",
      "referenceId": "1042",
      "createdAt": "2026-07-17T09:30:00.000Z",
      "expiresAt": "2026-07-21T09:30:00.000Z"
    }
  ],
  "totalPoints": 150
}

totalPoints is the sum of all pending amounts — use it for a "You have N points to claim" prompt. An empty claims array means there is nothing to claim.

POST `/api/user/points/claim`

Converts pending reservations into spendable balance. Omit the body to claim everything pending; pass claimIds to claim specific reservations only.

POST {BASE_URL}/api/user/points/claim
Authorization: Bearer {TOKEN}
Content-Type: application/json

{ "claimIds": ["7f3a9c2e-…"] }

{
  "claimedCount": 1,
  "pointsClaimed": 150,
  "transactionId": "4d7e1b6a-…",
  "balance": 1650
}

claimIds, when present, must be a non-empty array of reservation IDs from the claimable endpoint; an empty array is rejected with 400.
Reservations that expired before the call are lapsed, not claimed — they are never credited. claimedCount: 0 with pointsClaimed: 0 means nothing was pending (already claimed, or expired).
balance is the shopper's spendable balance after the claim (null if it could not be read; the claim itself still succeeded).

Claiming is idempotent per reservation: a grant can only be claimed once, and concurrent claims of the same grant are serialized server-side.

3. Ledger effects

A successful claim appears in the shopper's points history (GET /api/widget/points-history) as a single ledger row covering the whole batch:

{
  "amount": 150,
  "balance": 1650,
  "transaction_type": "claim",
  "reference_type": "point_claim",
  "created_at": "2026-07-17T10:05:00.000Z"
}

Expired reservations never appear in the ledger — they simply lapse.

4. Webhook (optional)

When a shopper claims points, Legion can notify your backend via the points-claim webhook (configured per shop in the admin console under Settings → Webhook URLs). The payload includes transaction_id, points_claimed, claimed_count, and the claimed claim_ids. See the Webhooks section of the developer docs for authentication and the full schema.

Integration checklist

Shopper authenticated via SSO bearer token (/docs/sso).
Pending reservations surfaced from GET /api/user/points/claimable (e.g. a "You have N points to claim" banner).
Claim action calls POST /api/user/points/claim and refreshes the balance and points history on success.
Shoppers are prompted to claim promptly — unclaimed reservations expire and are forfeited.
(Optional) points-claim webhook consumed for server-side reconciliation.