# Manage shopping cart

**Flow key:** `cart-management`

## Outcome

The shopper can add, update, remove, and persist intended line items while totals, promotions, inventory, and identity remain coherent.

## Actors

- Shopper
- Cart service
- Catalog/pricing/inventory services

## Preconditions and entry points

- Synthetic products include available, limited-stock, discounted, and incompatible items.
- Guest and signed-in cart policies are known.

## Required test data

Use synthetic, isolated, resettable data. Never use real credentials, payment instruments, private customer records, or production notifications.

| Data | Canonical valid seed | Critical variations |
|---|---|---|
| Items | `CARBON-SKU-001` qty 1 and `CARBON-SKU-002` qty 2 | same SKU different variants, out of stock, max quantity |
| Cart identity | fresh guest cart | signed-in cart, saved cart, two tabs, cart merge after login |
| Pricing | known unit prices and tax/shipping not yet final | promotion, member price, price change |
| Persistence | cookie/storage plus server cart if supported | blocked cookies, expired cart, other device |

## Canonical steps

Treat this as the ordinary successful path inferred from common product behavior. Adapt it to observed labels, business rules, APIs, and implementation evidence; do not invent a requirement.

| Step | User or system action | Expected evidence |
|---:|---|---|
| 1 | Add a configured product. | One line item appears with correct product, variant, quantity, and provisional price. |
| 2 | Add another item and add the first item again. | Merge-versus-separate policy is consistent and counts/totals update. |
| 3 | Change quantity and configuration. | Inventory, price, promotions, and subtotal recalculate without stale lines. |
| 4 | Remove one item and undo if offered. | Exactly the intended line changes; totals and downstream availability agree. |
| 5 | Refresh, navigate, sign in, or reopen on another device. | Cart persists/merges according to policy without leaking another shopper’s cart. |
| 6 | Proceed to checkout. | The same authoritative cart and totals seed checkout. |

## Alternate paths

- Mini-cart
- Saved-for-later
- Guest-to-account merge
- Multi-seller cart
- Subscription plus one-time items

## Failure and recovery paths

- Inventory or price changes
- Two tabs edit concurrently
- Retry duplicates line item
- Cart expires
- Promotion removal leaves stale total

## Completion oracle

- The stated outcome is true in visible UI and authoritative persisted state.
- Exactly one intended business result and no unintended side effect occurred.
- Identity, tenant, authorization, money/data, lifecycle, notifications, integrations, analytics, and audit agree where applicable.
- Refresh, retry, back/forward, and a second authorized read do not reveal a contradictory result.
- Any partial, delayed, canceled, failed, or unknown outcome is labeled truthfully and has a safe recovery path.

## Evidence to capture

- Entry context, actor, tenant, role, feature flags, locale, time zone, and initial identifiers/state.
- Step-level screenshots or DOM state plus request/response, correlation, job, event, and stable business IDs where available.
- Before/after authoritative records, versions, totals, permissions, lifecycle states, and downstream side effects.
- Notifications, audit events, integration deliveries, retries, deduplication, latency, and recovery evidence.
- Untested branches, unsafe-to-run cases, product decisions, and evidence tier.

## Product decisions to resolve

- Exact eligibility, required data, authorization, and validation rules.
- Which steps are synchronous, asynchronous, optional, skippable, reversible, or irreversible.
- Idempotency, concurrency, timeout, retry, cancellation, and compensation semantics.
- Retention, privacy, notification, audit, performance, accessibility, and localization commitments.

## Related CARBON items

- [product service plan price](../../items/records/product-service-plan-price.md)
- [count and quantity](../../items/data/count-and-quantity.md)
- [currency price totals](../../items/data/currency-price-totals.md)
- [delete](../../items/actions/delete.md)

[Back to Commerce and billing flows](index.md)
