Rewards Module — Storefront

{
  "data": <payload>,
  "message": "Success",
  "statusCode": 200,
  "metadata": { /* on paginated lists */ }
}

type BalanceResponse = {
  /** Spendable balance. May be negative immediately after a refund
   *  reversal exceeded the redeemed amount; the storefront should
   *  surface that explicitly to avoid confusion. */
  available: number;
  /** Earned-but-not-yet-promoted points (e.g. credited at vendor
   *  fulfillment, waiting for delivery to become spendable). */
  pending: number;
  /** Points across `available` lots whose `expires_at` falls within
   *  the next 30 days. 0 when no lot is expiring soon. */
  expiringSoonPoints: number;
  /** Earliest expiry across available lots inside the soon-window.
   *  null when no lot is expiring soon. */
  expiringSoonAt: string | null; // ISO
};

type HistoryItem = {
  id: string;
  /** 'earn' / 'redeem' / 'reverse' / 'expire' / 'restore' /
   *  'manual_credit' / 'manual_debit'. */
  entryType: RewardLedgerEntryType;
  /** Signed: positive for earn / restore / manual_credit;
   *  negative for redeem / reverse / expire / manual_debit. */
  points: number;
  /** Origin category — drives the row's icon + label on the
   *  storefront history list. */
  sourceType:
    | "order_vendor"
    | "first_purchase"
    | "customer_registration"
    | "review"
    | "redemption"
    | "reversal"
    | "restoration"
    | "expiry"
    | "manual";
  /** Free-text note (set on manual admin actions + reversal events). */
  reason: string | null;
  /** Set on `earn` rows. null on every other entry type, and on
   *  earn rows created when `expiry_enabled` was off. */
  expiresAt: string | null;
  createdAt: string;
};

type CartAppliedRedemption = {
  /** Customer's most recent requested amount (cart.redemption_points). */
  requestedPoints: number;
  /** What the port accepted after clamping against balance, the
   *  per-order absolute cap, and the % of cart cap. May be less
   *  than `requestedPoints` (the cart UI should re-display so the
   *  customer can see the clamp), never more. */
  acceptedPoints: number;
  /** acceptedPoints × point_value_subunits, in integer subunits. */
  discountAmount: number;
  /** Pro-rata split across vendor sub-bags; sum equals discountAmount. */
  allocations: Array<{ vendorId: string; amount: number }>;
};

MODULE_DISABLED       — rewards.enabled or redemption_enabled is off
USER_REQUIRED         — anonymous cart, customer hasn't signed in
INSUFFICIENT_BALANCE  — available balance is 0
BALANCE_NEGATIVE      — available balance is below 0 (post-reversal debt)
BELOW_MIN_CART        — cart subtotal after coupons < min_cart_total_subunits
EXCEEDS_PER_ORDER_CAP — request > max_redeem_points_per_order
EXCEEDS_PCT_CAP       — requested discount > max_redeem_pct_of_subtotal × subtotal
RATE_NOT_CONFIGURED   — point_value_subunits is 0 (mis-configuration)

{
  "data": {
    "available": 1240,
    "pending": 100,
    "expiringSoonPoints": 50,
    "expiringSoonAt": "2026-06-12T17:10:07.651Z"
  },
  "message": "Success",
  "statusCode": 200
}

{
  "data": [
    {
      "id": "79721f68-ce09-461a-ba97-3f6fe501d834",
      "entryType": "earn",
      "points": 50,
      "sourceType": "customer_registration",
      "reason": null,
      "expiresAt": "2027-05-14T17:10:07.651Z",
      "createdAt": "2026-05-14T17:10:07.649Z"
    },
    {
      "id": "5d2c63ee-1b1e-4f57-9c44-...",
      "entryType": "redeem",
      "points": -1000,
      "sourceType": "redemption",
      "reason": "order:07001304-6fa4-4c26-bfac-0cc6905e7c1e",
      "expiresAt": null,
      "createdAt": "2026-05-14T17:13:55.121Z"
    }
  ],
  "message": "Success",
  "statusCode": 200,
  "metadata": { "total": 2, "limit": 20, "offset": 0, "hasMore": false }
}

{ "points": 500 }

{
  "data": {
    "cartId": "cafe5664-...",
    "bags": [ /* ... */ ],
    "cartTotals": {
      "subtotal": 125800,
      "discountTotal": 5000,
      "shippingTotal": 0,
      "total": 120800
    },
    "appliedCoupons": [],
    "appliedRedemption": {
      "requestedPoints": 500,
      "acceptedPoints": 500,
      "discountAmount": 5000,
      "allocations": [
        { "vendorId": "XzkY5vtg...", "amount": 5000 }
      ]
    }
  },
  "message": "Success",
  "statusCode": 200
}