The Storefront module is the e-commerce surface of AppEngine. Every endpoint lives under /storefront/*. Browsing endpoints are public; everything that touches an order or a customer record uses the standard JWT + orgid headers.
Scope
A single module covers the full purchase lifecycle plus the operational tooling around it:
- Catalog — products, variants, categories, brands, attributes, collections.
- Pricing — base prices, customer-group tiers, automatic discounts, coupons.
- Cart — anonymous and authenticated carts with line items and a single update endpoint.
- Checkout — Stripe (intents, subscriptions, checkout sessions) and PayPal.
- Orders — full lifecycle from
newthroughprocessing,shipped,delivered,completed, plus refund, cancel, and hold transitions. - Inventory — SKU stock per location, transfers, low-stock alerts, reservations.
- Shipping & tax — rate quotes, address verification, real-time carrier rates, tax-by-jurisdiction.
- Discounts & gift cards — coupon validation, automatic promotions, gift-card balance and redemption.
- Returns — RMA flow and refund posting.
- Subscriptions & rentals — recurring billing and time-bound bookings.
- Invoices — B2B invoicing tied to orders.
Concepts
| Concept | Owns | Where it lives |
|---|---|---|
| Product | SKU, name, description, images, base price, attributes | storefront/products, storefront/product/:id |
| Variant | A purchasable child of a product (size, color, etc.) | Embedded in the product variations array |
| Category / Brand | Grouping for browse and filtering | storefront/categories, storefront/brands/:brand? |
| Cart | Set of line items keyed by cartid, scoped to a customer or guest | storefront/cart/get/:authorid/:cartid |
| LineItem | sku, quantity, unitPrice, options | Inside the cart payload |
| Order | Cart converted at checkout; carries lifecycle state and tracking | storefront/order/get/:author/:orderNumber |
| Discount | Coupon, automatic rule, or promotion | storefront/discounts/* |
| GiftCard | Serial-tracked stored value | storefront/giftcards/* |
| Inventory | Stock-on-hand per SKU per location | storefront/inventory/* |
| Subscription | Recurring order tied to a Stripe subscription | storefront/subscriptions/get/:author |
| Rental | Time-bound product reservation | Mixed with cart via itemType: "rental" |
| Return | RMA against a fulfilled order | storefront/returns/* |
| Invoice | Document representing payment due | storefront/invoice/* |
What goes where
- Building a product page or category grid? → Products and variants.
- Wiring a cart UI? → Cart.
- Taking payment? → Checkout.
- Operations side (process, ship, deliver)? → Orders and fulfillment.
The base-app reference site uses every endpoint in this module. The canonical client-side wrapper is src/lib/storefront-api.ts — copy from it rather than writing your own from scratch.
Multi-channel
The Storefront module is the system of record. The Sales Channel module syncs the same catalog out to Amazon, eBay, Shopify, WooCommerce and aggregates orders back. You can ignore Sales Channel entirely until you need a second channel.
Public vs authenticated
Browse, cart-read, and gift-card-balance are public — @PublicRoute() on the controller. Everything that mutates an order, processes a payment, or touches a customer record is JWT-gated. Cart updates work for both anonymous (authorid = a generated guest id) and authenticated customers; the cart merges on sign-in.