Quick Add to Cart

Free — GPL coresize Mplanned, not built

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

One-click add-to-cart from product listings cuts checkout friction 30% and increases conversion. This core feature allows customers to add simple products directly without opening the product detail page.

The problem

Customers must click into each product, scroll through details, and click ‘Add to Cart’ — three actions for one item. With quick add from the listing, customers can fill a cart in seconds.

What it does

• Quick add button on product listings (grid and list views) for simple products only
• For variable products (size, color), quick add opens a mini-modal variant selector, then adds the chosen variant
• Button label, position, and styling configurable per theme (theme owns the UI, module provides the API)
• Quantity input: allow customer to specify qty before adding (default 1, cap at product’s per-order max)
• Sku/variant detection: client sends product_id + variant_id if applicable; server validates stock before adding
• Cart persistence: item immediately appears in cart (no page reload required)
• Error handling: ‘Out of stock’, ‘Variant required’, ‘Qty exceeds limit’ — return structured errors with code

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.

• Bulk product add — adding multiple different products from a list in one action. That’s a separate ‘add to cart’ workflow.
• Wishlist functionality — saving products for later without adding to cart. Distinct from quick add.
• Customization options (text uploads, file uploads) — quick add is for pre-configured options only. Fully custom products need the detail page.

Data model

None. The existing Cart (which is in-client session storage) and Order/checkout flow handle this. No schema change needed.

API

• POST /api/cart/add — body: { product_id, variant_id (optional), qty } → { success, cart_total, item_added }

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 feature is configured in the theme — where the quick-add button appears, its styling, and the modal for variant selection.

The seam — why this is core

Core owns the POST /api/orders endpoint (checkout itself) and product validation (variant existence, stock). This feature is pure storefront UX; AstroBaaS ships the route and the server-side validation. Theme owns the HTML, JS event handling, and cart UI update.

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

Dependencies

• shopping-cart — quick add only makes sense if a cart exists to add to
• product management (core) — product_id and variant_id must exist and be public

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.

• Simple product (no variants): quick-add button visible, qty field, click adds to cart in one action
• Variable product (color, size): quick-add button opens mini-modal, merchant selects color + size, confirms, item added
• Qty field: merchant enters 3, click add; cart shows item with qty 3
• Qty exceeds limit (product max 2 per order): qty input caps at 2; submit adds qty 2
• Out of stock: quick add button disabled or shows ‘Out of stock’ label
• Variant missing (e.g., size required but not selected in modal): error returned with code ‘variant_required’
• Adding same product twice: first add creates line, second add increments qty on existing line
• Cart persists after add: no page reload, cart UI updates immediately to show new item

Risks

Stock race: between validation on the add request and checkout, another customer buys the last unit. This is unavoidable; checkout must re-validate stock. Variant logic: if a product’s variants change between quick-add request and checkout (e.g., a variant is deleted), the order fails at checkout with ‘variant_no_longer_available’. Client must handle the error gracefully. Client-side cart: if the storefront stores cart in localStorage and does not sync with server until checkout, a ‘quick add’ on device A is not visible on device B — this is a storefront architecture issue, not the module’s.

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.