Cart Persistence

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/cart-persistence/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Customers’ carts disappear on page refresh, forcing them to re-add items or abandon. This core feature saves the cart to localStorage (or database) so items persist across sessions.

The problem

A customer adds 5 items to their cart, accidentally refreshes the page, and the cart is empty. They re-add some items but give up, losing the sale.

What it does

• Persist cart to localStorage on every change (add, remove, update qty)
• Restore cart from localStorage on page load
• Clear cart after successful checkout
• Handle edge cases: browser’s private mode (localStorage unavailable), iOS Safari cache limits, quota exceeded
• Sync: if user has an account, optionally sync cart to server during login (optional; theme decides)
• Expiry: old carts can optionally expire after N days (configurable; default 30 days)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Server-side cart storage — that’s a paid feature for user accounts. This core feature is client-side only.
• Cross-device sync — requires accounts and server storage, beyond scope.
• Cart abandonment tracking — that’s marketing analytics, not persistence.

Data model

None on server. Client-side: localStorage[‘astrobaas_cart’] = JSON.stringify(cart_state). Cart state: { version: 1, items: [...], updated_at, shop_currency }. Version allows schema upgrades.

API

• No API changes. Persistence is client-side only.

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

No admin interface.

The seam — why this is core

Core provides no persistence layer. Theme implements localStorage persistence using standard JS APIs. AstroBaaS provides guidance in documentation (e.g., ‘use JSON.stringify on add/remove/update events’).

Core owns the interface + honest session storer; cart resilience is infrastructure, not a per-country obligation or credential.

Dependencies

• shopping-cart — persistence only makes sense if cart exists

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Cart has 3 items; page is refreshed; cart is restored with same 3 items
• Browser’s private mode: localStorage unavailable; warning shown or cart is session-only (dismissed on close)
• Cart persists for 30 days; after 30 days, cart is cleared automatically
• Successful checkout: POST /api/orders succeeds; cart is cleared (localStorage[‘astrobaas_cart’] deleted)
• User logs in: cart persists (client-side cart remains; if server-side sync is desired, storefront handles that)

Risks

localStorage quota exceeded (typically 5–10 MB): if cart is huge (1000 items with full product objects), serialization may fail. Theme must catch the error and fall back to session-only cart. Stale cart after product updates: if a product’s price changes, the old price in the cached cart is still there until checkout re-validates. This is acceptable (old price is a surprise, good or bad, until checkout). Private browsing: some browsers throw on localStorage access in private mode; code must wrap in try/catch. Cookie consent: if cart relies on localStorage, it’s not a ‘cookie’ but browser storage — GDPR implications are unclear (guidance: ask a lawyer, not an engineer).

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.