perq-wallet

Get Summary

Overview of the signed-in user's wallet: total still available to redeem this cycle, amount already redeemed, number of open credits, gift-card balance on hand, points-portfolio value, and anything expiring soon (plus a household roll-up when the wallet has household members).

List Credits

List recurring card credits for the signed-in user. filter: 'open' (not yet redeemed this period, the default), 'due-soon' (open and ending within 14 days), 'redeemed', or 'all'. Optional person to scope to a household member by name (e.g. 'Mom', 'Dad'); default is the account owner.

List Expiring

List gift cards, certificates, free-night/companion awards, and card certificate-benefits that have a deadline, with how many days are left, soonest first.

List Points

List loyalty-points balances aggregated across the household by program, each with the cents-per-point valuation in effect and its dollar value, plus the total portfolio value.

Mark Redeemed

Mark a recurring credit as redeemed (used) for the current period. Match by keyword against the benefit or card name (e.g. 'uber', 'resy', 'saks'). Applies to the account owner's own cards.

Add Gift Card

Add a gift-card / store-credit balance to track. Provide the merchant name and balance; optionally an expiry date (YYYY-MM-DD) and occasion.

Wallet Overview

Structured overview of the signed-in user's OWN cards (not household members): which cards are owned (id, name, annual fee), how many recurring credits are open vs. already used this cycle and their dollar totals, and benefit-year totals for the owned cards: total annual fees, total annual potential credit value, and this cycle's open/unredeemed value (what's currently left on the table).

Expiring Soon

Recurring card credits, certificate benefits, gift cards, and awards on the signed-in user's own wallet that reset or expire within a window, with amounts (when the benefit has one) and period keys (when it's a rolling-period credit), soonest first.

Mark Benefit Used

Set the used-state of one recurring credit on one of the signed-in user's OWN cards, for a specific benefit period. state: 'used' (redeemed), 'partial' (partially redeemed; the app has no partial UI yet, so this shows as used there, but Perq's own tools report it distinctly), or 'unused' (clears it). periodKey is optional, omit it to target the CURRENT period (the same one the app is showing right now); pass one from expiring_soon/list_credits to target a different period. Returns the resulting

Add Card

Add a card to the signed-in user's own wallet (owned[]). cardId must match an id from card_reference / the live card database. Returns the resulting owned-card list.

Remove Card

Remove a card from the signed-in user's own wallet (owned[]). Any recorded used-state for that card's credits is left in place, harmless, since it can never match a different card, exactly like the app's own remove-card action. Returns the resulting owned-card list.

Set Status Progress

Update progress toward an elite-status goal (Delta MQDs, Hyatt/Marriott/Hilton nights, AA Loyalty Points, United PQP, or a custom program) for the signed-in user. Matches an existing entry by program name (case-insensitive) and updates its current value; creates a new custom entry if none exists yet (target starts at 0, set a real target once in the app's Status tab). Returns the resulting progress.

Card Reference

Static benefit data from the live card database: issuer, annual fee, and each benefit's amount/cadence/reset basis. No wallet-specific or account data; works the same for every user. Omit cardId to list every card in the database; provide it for one card's full benefit detail.

Recent Activity

The redemption ledger: who moved each number and from what evidence. Returns the newest events on this wallet — actor (a thumb in the app, Genie, an issuer email, the Monarch sync), what was marked or unmarked, the source transaction where one exists, and when. Use it to answer 'what got checked off, and why?'

Pending Confirmations

Card activity the Monarch matcher found but was NOT confident enough to mark on its own: each one names the transaction (date, amount, merchant), the credit it probably belongs to, and why it stopped short. These are QUESTIONS, not facts, and nothing is marked until someone says yes. Use it to ask the user about a specific one, then mark_benefit_used (or mark_redeemed) once they confirm; say plainly that you are asking because the automatic match was uncertain.