Edit or remove cart items
Customer App can present quantity, edit, remove, and clear controls for eligible cart rows. A changed quantity, closed editor, missing row, empty-looking cart, toast, or navigation is not proof that the requested cart mutation settled.
:::warning Important boundary
Do not repeat an edit, quantity change, removal, or clear action to make the screen match an expected result. A request can partially affect cart, reservation, payment, or related state before an error or lost response.
:::
Visible controls are conditional
| Control or state | What it can mean | What it does not prove |
|---|---|---|
| Quantity decrease/increase | The current row is eligible for a quantity request | Inventory, reservation, totals, or server acceptance |
| Edit affordance | The current item can open an edit surface | That every prior option remains available |
| Remove action | A destructive row-removal request can be started | That related effects were reversed |
| Clear cart | A destructive whole-cart request can be started | That every dependent record was cleared atomically |
| Pending cart | Edit controls can be unavailable | Financial or order settlement |
| Invalid item | The current item/menu/quantity failed one validation layer | Which replacement is safe |
| Loading indicator | One client request is considered in flight | That the server has not already committed |
Visibility can change with cart status, item/menu state, business, order type, configuration, account, project, and caller.
Quantity is optimistic and can become stuck
The compact cart control can display the requested quantity and a loading state before the returned cart confirms it. Some failure results are returned as a false outcome instead of a thrown error. In that case, the optimistic row can remain changed or busy until another cart result replaces it.
A callback can also run after the quantity request returns without proving that the requested update succeeded. Treat the displayed row, shared cart, server cart, recalculated summary, and follow-up callback as separate states.
Editing an item can rebuild more than quantity
The full edit surface can submit current item options, ingredients, quantity, and other subtype context. The server can revalidate the current catalog row, availability, options, inventory, cart, and business before returning a new cart.
For a service item, an update can release or replace a calendar reservation. Compact quantity changes do not necessarily carry the previously selected professional and service date, so the update can re-reserve a different professional or date, or fail after the earlier reservation state changed. Never assume a service edit preserves the visible appointment details.
Remove and clear are different destructive boundaries
Removing one row can delete its service calendar reservation, refresh the cart, run related effects, and update shared state. When the removed row is the final line, the server can enter the broader clear-cart path rather than return an ordinary one-row removal result.
Clear can reset or detach product rows, calendar events, payment and address context, order and group relations, reservation data, cart metadata, offers, timing, tips, comments, and other checkout fields. Those operations, plugin work, socket updates, and the final response are not established as one atomic receipt.
Related effects can settle separately
| Effect layer | Possible consequence of update, remove, or clear |
|---|---|
| Product/cart row | Quantity, options, validity, totals, or row existence changes |
| Service calendar | Prior reservation is extended, released, replaced, or re-created |
| Address/fulfillment | Current address, delivery, timing, or order-type context becomes invalid or clears |
| Offer/metafield | Eligibility, discount, attached metadata, or summary bases change |
| Payment/wallet | Selected method, provisional payment event, wallet association, or financial revision becomes stale or clears |
| Group/order | Membership, group summary, pending order relation, or placement context changes |
| Socket/plugin/cache | Other listeners or integrations receive an update at a different time |
No single visible layer proves that all other layers used the same cart revision or completed successfully.
Unknown and partial outcomes
| Observed state | Safe interpretation |
|---|---|
| Quantity changed but spinner remains | Optimistic state is stuck; settlement is unknown |
| Quantity reverted | The current client row rejected or replaced the optimistic value; server effects may still need reconciliation |
| Editor closes with unchanged row | Callback/navigation and update settlement may disagree |
| Row disappears after an error | Removal or a dependent effect may have committed before failure |
| Final row removal shows an empty cart | A broader clear path may have run; dependent cleanup is not proved |
| Service professional or date changed | Re-reservation used different current availability or lost prior context |
| Cart summary changes partially | Product, offer, wallet, address, group, or payment revisions differ |
| Response is lost | Mutation and every dependent effect remain unknown |
| Account, project, cart, or group changes | Reject old callbacks and do not apply them to the new context |
While the result is unknown, do not repeat the action, edit another field to force refresh, clear the cart as a repair, or proceed to payment or placement as a diagnostic.
Reconcile without repeating
- Treat the currently authorized cart read as cart presentation only, not a complete effect ledger.
- Compare only value-free state classes: row present or absent, quantity unresolved, service reservation unresolved, or cart cleanup partial.
- Keep service appointment, address, offer, wallet/payment, group, and order outcomes unresolved until their current authorized surfaces agree.
- If the cart remains inconsistent, use an approved support channel. Do not initiate replacement reservations, payment, refunds, compensation, or another cart mutation.
- Do not use Back, foregrounding, reopening Cart, another account, another project, or another group as a retry test.
Support reports should use only a value-free state class such as “cart item update unresolved.” Do not include product or service details, professional or appointment data, customer/business data, cart/order identifiers, payment information, links, or private screenshots.
Privacy and accessibility
- Cart items, options, service details, professional/date context, addresses, offers, payment state, and group/order relationships can be private. Keep them out of documentation and support evidence.
- Quantity controls need accessible names, current values, limits, disabled and busy state, and a clear relationship to the affected row.
- Edit, remove, and clear controls need distinct names and consequences. Destructive confirmations must retain modal isolation, Cancel/accept order, and predictable focus return.
- Loading, optimistic, error, partial, unavailable, removed, empty, and unknown states need announcements that do not imply success.
- Large text, keyboard, screen reader, switch, safe-area, Back, and reduced- motion behavior require current-platform verification; this guide does not certify them.
Recertification triggers
Revalidate this reference after changes to quantity controls, optimistic state, item edit callbacks, update/remove/clear controllers, final-line behavior, service calendar reservations, professional/date selection, inventory or option validation, cart refresh, address/fulfillment/timing, offers/metafields, wallet/payment events, group/order relations, sockets/plugins/caches, accessibility primitives, or error presentation.
Also recertify after changes to API deployment authority, cart ownership and versioning, transaction or idempotency behavior, operation receipts, partial- failure recovery, or stale-response cleanup.