Add to Cart Notification

Free — GPL coresize Splanned, not built

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

Customers are unsure if add-to-cart succeeded, so they click again and order duplicates. This core feature adds brief visual feedback when an item is added: a toast, a check-mark animation, or a cart update.

The problem

After clicking ‘Add to Cart’, customers don’t see confirmation. They click again, accidentally adding two copies. Without feedback, checkout abandonment increases and duplicate-order support tickets waste staff time.

What it does

• Toast notification: display for 2–3 seconds when item is added (‘Added to cart: Blue Shirt x1’)
• Cart counter: update the cart icon badge to show total items (e.g., cart icon shows ‘3’)
• Item detail page: after add, show a brief check-mark icon or status message
• Accessibility: notification must be screen-reader-friendly; use aria-live regions
• Configurable timing: merchant can adjust toast duration via theme settings
• Error state: if add fails (out of stock, variant invalid), show an error toast instead

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.

• Slide-out cart drawer or cart preview — that’s a UX choice for the theme, not the notification module. Notification is feedback-only.
• Email or SMS confirmation — that’s email marketing, not cart UX.

Data model

None. Notification is purely client-side UI feedback on the response from POST /api/cart/add.

API

• POST /api/cart/add response — already includes item details; no changes needed. Client uses the response to build the notification.

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. Notification text and styling are theme-controlled (CSS variables, custom messages).

The seam — why this is core

Core owns the POST /api/cart/add response schema (product name, qty, price, error codes). Theme owns the UI rendering and notification display.

Core owns the interface + honest feedback UI; checkout UX is infrastructure, not a support commitment or credential.

Dependencies

• quick-add-to-cart — notification is feedback for adding items
• shopping-cart — cart counter relies on cart existing

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.

• After quick add, a toast appears saying ‘Added to cart: Blue Shirt x1’ and disappears after 3 seconds
• Cart icon badge updates from ‘2’ to ‘3’ immediately
• If add fails (out of stock), error toast appears: ‘Out of stock: Blue Shirt (size L)’ with red styling
• Screen reader announces ‘Added to cart, Blue Shirt, quantity 1’ via aria-live region
• Notification can be dismissed early by clicking a close button (X)
• Merchant can configure toast duration via theme settings; change to 5 seconds takes effect

Risks

Notification spam: if a customer clicks add-to-cart five times quickly, five toasts appear. The theme must debounce or queue notifications. Toast timing: if notification disappears too fast (< 1 second), users on slow networks don’t see it. Too slow (> 5 seconds) clutters the screen. Accessibility: aria-live=‘polite’ means notification appears after the user finishes their current action; aria-live=‘assertive’ interrupts (use sparingly). Error messages must not leak sensitive info (e.g., ‘This variant is out of stock in our warehouse location X’ — just say ‘Out of stock’).

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.