Understand wallet and loyalty states
Customer App can conditionally present cash-wallet or loyalty-points controls inside single Checkout and multi-business Checkout. Those integrated controls are reachable when current account, business, project, cart, configuration, and loyalty rules allow them.
A separate Wallets page exists in source and Checkout can attempt to navigate
to it, but the current signed-in navigator does not register that destination.
Cash-wallet and loyalty-points account pages are different registered surfaces.
This article is therefore a blocked state reference, not a standalone Wallets
journey or a wallet-use procedure.
Visible wallet states
| Visible state | Safe interpretation |
|---|---|
| Wallet section absent | No eligible integrated wallet control is presented; account, feature, balance, or provider existence is not disclosed |
| Loading placeholders | Wallet, loyalty-plan, business, cart, configuration, or payment-event state is unresolved |
| Empty or filtered list | No wallet row passed the current UI gates; this is not proof that no wallet record exists |
| Cash-wallet row | A returned cash-type wallet passed current global/business/cart display rules |
| Loyalty-points row | A returned points-type wallet has a provisional redemption rule for the current business or group |
| Disabled row | Current visible balance/cart state prevents selection; available balance and reservation state remain unknown |
| Selected-looking row | Local cart payment-event state currently references the wallet; it is not proof of reserved or debited funds |
| Error or unchanged row | Read/add/remove/refresh outcome can be unknown; local selection can disagree with cart/server state |
Do not infer wallet ownership, available balance, redemption eligibility, or financial settlement from visibility, row order, icon, checkbox, or formatted value.
Opening Checkout is not read-only
Wallet discovery is effectful. The current wallet read can create missing wallet records and run plugin work before returning data. Checkout can also read loyalty plans, cart state, business rules, configuration, and payment events.
In multi-business Checkout, loading wallet/payment choices can automatically remove incompatible per-cart wallet associations and refresh shared order options. A screen mount or refresh is therefore not proof of zero wallet, cart, payment-event, socket, job, or plugin effects.
Selection, cart association, and provisional payment state
| Stage | What it can change | What it does not prove |
|---|---|---|
| Row press | Local checked state and an add/remove request can start | Server acceptance, reservation, debit, or refund |
| Add wallet to cart | Cart-wallet association and refreshed cart/payment-event presentation | Funds reserved, available balance locked, payment final, or order placed |
| Remove wallet from cart | Association and provisional cart/payment state can change | Reversal, refund, balance restoration, or cleanup across group members |
| Cart/payment-event refresh | Returned cart state can replace shared local state and update selected styling | Same revision as displayed balance, loyalty rate, total, or provider state |
| Multi-business wallet cleanup | Multiple per-cart associations can be removed asynchronously | All removals succeeded, group summary refreshed, or rollback occurred |
The visible checkbox can update optimistically while the request is pending, and some errors are not presented beside the affected row. Do not repeat selection or removal to force the checkbox and cart to agree.
Balance, rate, type, and precision
Cash wallet and loyalty points are different types. Cash display uses monetary formatting; points can use a business or general redemption rate to show a provisional monetary equivalent. Type recognition, supported business set, rate, rounding, currency, and cart amount must all belong to the same current revision.
A displayed wallet balance is not an available-balance guarantee. Pending carts, orders, refunds, compensations, jobs, other sessions, or concurrent activity can change actual availability. A points conversion is an estimate, not a promise of redemption amount or financial precision.
Debit occurs at Place, not selection
Selecting a wallet associates it with a cart and can create provisional payment state. The financial debit belongs to the later Place/confirm operation. There is no documented reservation or lock that guarantees the displayed balance will remain available between selection and Place.
Place can settle wallet debit, provider payment, cart/group state, order creation, compensation/refund, jobs, messages, sockets, and plugins in separate stages. A selected row, zero remaining cart balance, Place navigation, order card, or provider result does not prove all stages completed or occurred exactly once.
This guide does not provide Place, wallet selection, removal, redemption, transfer, debit, refund, or compensation procedures.
Single, multi, guest, gift, and free distinctions
| Context | Important boundary |
|---|---|
| Single Checkout | One cart-wallet association can still differ from current balance and later Place debit |
| Multi-business Checkout | Eligibility must hold across the exact member set; automatic cleanup and partial group outcomes can diverge |
| Guest | Wallet ownership requires an authorized signed-in identity; guest conversion does not imply wallet transfer |
| Gift order | Gift and wallet/payment policy is separate; visibility does not prove compatibility |
| Free or zero-balance cart | No external payment requirement does not make wallet association valid or Place atomic |
| Mixed wallet and provider payment | Wallet and provider portions require one authoritative amount snapshot and recoverable settlement |
Do not carry a wallet selection between account, project, session, cart, group, business, order type, or payment-method generations.
Unknown and partial outcomes
| Situation | Safe interpretation |
|---|---|
| Checkbox changes but cart total does not | Local checked state and cart/payment-event settlement disagree |
| Cart total changes but wallet row does not | Balance/rate/list and cart revisions may differ |
| Add/remove reports an error | Association and provisional payment state are unknown; do not repeat automatically |
| Multi-business cleanup affects only some carts | Exact per-cart association and group summary remain partial |
| Place fails or response is lost | Debit, provider, order, compensation, and refund outcomes are unknown |
| Order appears but balance seems unchanged | Ordering order state and wallet read/financial job timing are separate |
| Account/project/session changes | Reject old wallet/cart/provider results and do not apply them to the new generation |
| Standalone Wallets navigation fails | Route registration is absent; do not substitute another financial surface |
Troubleshoot safely
- Treat wallet rows and balances as returned display, not authoritative available funds.
- Do not select/remove repeatedly, refresh Checkout, or switch methods to test wallet state.
- Do not use another cart, guest conversion, gift order, free order, or multi-business group as a diagnostic.
- If Place or a response is unknown, check Orders once and use approved support; do not initiate debit, refund, or compensation.
- If wallet and cart states disagree, preserve the disagreement without entering replacement amounts or calculating a conversion.
- Do not attempt the unregistered Wallets destination through a private route or link.
Privacy and accessibility
Wallet type, balance, points, redemption rate, account, cart/group, payment events, orders, and provider relationships are private financial data. Do not include real values, identifiers, screenshots, links, activity, or raw errors in documentation, diagnostics, accessibility labels, logs, or support notes.
Wallet type, eligibility, loading, balance class, conversion estimate, selected/pending/error/unknown, disabled, add/remove, and Place-time consequence need explicit semantic text. Rows and checkboxes need names, roles, checked/ disabled/busy state, focus order, and predictable announcements without relying on icons, color, or formatting. Large text, keyboard, screen-reader, safe-area, and Back behavior must not cause duplicate selection. These are verification requirements, not current accessibility or financial certification.
Product disposition and recertification
Retain this article as blocked until the standalone route has an explicit owner or is removed, wallet reads are pure, add/remove/refresh errors are observable, type/rate/precision rules are authoritative, and Place provides a recoverable wallet/payment/order receipt. Do not promote a standalone Wallets procedure from the current source.
Revalidate after changes to wallet-route registration, Checkout wallet gates, wallet reads/provisioning/plugins, loyalty plans/rates, add/remove associations, payment-event refresh, multi-business cleanup, balance/precision/currency, guest/gift/free policy, Place debit, refund/compensation/jobs/sockets, account/ project/session cleanup, privacy, or accessibility.
Related guides: Review your cart before checkout · Understand payment-method availability · Understand multi-business checkout · Understand checkout recovery states · Understand grouped order states · Understand privacy and consent