Rewards Module — Admin

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

type CustomerSearchItem = {
  customerId: string;
  email: string | null;
  name: string | null;
  /** Spendable balance. May be negative after a reversal exceeded
   *  the redeemed amount. */
  availableBalance: number;
  /** Earned-but-not-yet-promoted points (waiting on delivery /
   *  stuck-pending sweep). */
  pendingBalance: number;
  /** Set once when the customer crosses the first-purchase gate.
   *  null = first-purchase bonus is still unclaimed. */
  firstPurchaseAwardedAt: string | null;
};

type CustomerSummaryResponse = {
  customerId: string;
  email: string | null;
  name: string | null;
  availableBalance: number;
  pendingBalance: number;
  firstPurchaseAwardedAt: string | null;
  /** Most recent reward_ledger.created_at for this customer.
   *  null when the customer has had zero rewards activity. */
  lastActivityAt: string | null;
};

type LedgerListItem = {
  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;
  /** Lot state — only set on `earn` rows; null elsewhere.
   *  Values: pending / available / consumed / expired / reversed / void. */
  state: RewardLotState | null;
  /** Set on `earn` rows; null elsewhere. */
  earnedAt: string | null;
  /** Set on `earn` rows when the lot was created with expiry enabled. */
  expiresAt: string | null;
  /** Origin category. */
  sourceType:
    | "order_vendor"
    | "first_purchase"
    | "customer_registration"
    | "review"
    | "redemption"
    | "reversal"
    | "restoration"
    | "expiry"
    | "manual";
  /** Interpretation depends on sourceType:
   *    order_vendor / first_purchase → orderVendor.id
   *    customer_registration → user.id (the customer themselves)
   *    review → reviewId (or `${productId}:${customerId}` when
   *             one_per_product is on — the dedupe key)
   *    redemption → orderId (or cartId if no order yet)
   *    reversal / restoration → parent_ledger_id is also set
   *    expiry → parent_ledger_id of the expired lot
   *    manual → admin user.id who performed the credit/debit */
  sourceId: string | null;
  /** For reverse/restore/expire rows, points back at the original
   *  earn/redeem ledger row this entry compensates. */
  parentLedgerId: string | null;
  /** Human / system note. Required on manual_credit + manual_debit. */
  reason: string | null;
  createdAt: string;
};

type ManualAdjustResponse = {
  ledgerId: string;
  /** Customer's new balance after the adjustment. */
  availableBalance: number;
  pendingBalance: number;
};

{
  "data": [
    {
      "customerId": "lWpZoPgXt8Oux2kWd1fntGQzKfO6MTx8",
      "email": "alice@test.com",
      "name": "Alice",
      "availableBalance": 19250,
      "pendingBalance": 0,
      "firstPurchaseAwardedAt": null
    }
  ],
  "message": "Success",
  "statusCode": 200,
  "metadata": { "total": 1, "limit": 20, "offset": 0, "hasMore": false }
}

{
  "data": [
    {
      "id": "fb6b014e-b1f3-4f2b-a2dd-c8d6d28d8c8b",
      "entryType": "earn",
      "points": 500,
      "state": "available",
      "earnedAt": "2026-05-14T17:12:50.000Z",
      "expiresAt": null,
      "sourceType": "manual",
      "sourceId": "<admin user id>",
      "parentLedgerId": null,
      "reason": "Verification credit",
      "createdAt": "2026-05-14T17:12:50.000Z"
    },
    {
      "id": "5d2c63ee-...",
      "entryType": "restore",
      "points": 1000,
      "state": null,
      "earnedAt": null,
      "expiresAt": null,
      "sourceType": "restoration",
      "sourceId": "07001304-...",
      "parentLedgerId": "9a48...redemption-row-id",
      "reason": "order.cancelled: Changed my mind",
      "createdAt": "2026-05-14T17:15:21.000Z"
    }
  ],
  "message": "Success",
  "statusCode": 200,
  "metadata": { "total": 2, "limit": 20, "offset": 0, "hasMore": false }
}

{
  "points": 500,
  "reason": "Loyalty appreciation for being a long-time customer",
  "neverExpire": true
}

{
  "data": {
    "ledgerId": "fb6b014e-b1f3-4f2b-a2dd-c8d6d28d8c8b",
    "availableBalance": 19550,
    "pendingBalance": 0
  },
  "message": "Success",
  "statusCode": 201
}

{
  "points": 300,
  "reason": "Correction — customer accidentally got 2× registration bonus"
}

{
  "data": {
    "ledgerId": "699e6c81-f38c-43d1-9119-0a9f294d1979",
    "availableBalance": 19250,
    "pendingBalance": 0
  },
  "message": "Success",
  "statusCode": 201
}

{
  "data": null,
  "message": "Cannot debit 100000 pts; max allowed is 19250.",
  "statusCode": 400,
  "errorCode": "BAD_REQUEST",
  "details": { "maxAllowed": 19250 }
}