Storefront

Storefront is the online shop. Shoppers browse, fill a cart, check out and pay by card, PromptPay or bank transfer, then follow their order on its own page. Staff confirm payments, ship orders with a carrier and tracking number, take returns and cancellations, and sell gift cards. Storefront sells what Catalog holds, and checkout holds and deducts stock in Inventory, so a product is set up once and counted once. Sales, codes and free gifts are set up in Discounts, and the shop prices every cart through it. Storefront doesn't own products, stock counts, discounts, or the rest of the public website: those are Catalog's, Inventory's, Discounts' and Website's.

Discounts in the shopCopy Anchor Link

• Sale prices. An automatic percent or amount off with no condition (no minimum spend or quantity, member or time window) shows as the item's price on product cards and product pages, with the regular price struck through and a badge naming the sale ("Spring sale"). A product marked down with a compare-at price shows the same way with a "Sale" badge. An item covered by a quantity offer gets a badge such as "Buy 2, get 1 free" instead of a sale price.
• The cart. Each line shows what it saves, and the order shows each discount by its name. When an automatic discount is held back only by its minimum spend, the cart says how much more to spend ("Spend ฿200 more for free shipping").
• Codes. The shopper types a code at checkout. A code that applies on its own but loses to a better set of discounts it can't combine with doesn't apply, and keeps its use.
• Free gifts. A buy X get Y discount whose reward is one free product puts it in the cart when the cart earns it and takes it out when it no longer does. See Buy X get Y and free gifts.
• Staff orders. Staff building an order can still take an amount off by hand; it comes off after the discounts, capped at what's left.

What it handlesCopy Anchor Link

• Two shoppers after the last items. With three shirts left, two shoppers check out at once; one gets them and the other is refused, and one payment is created. A shopper asking for more than the shop has is told it's sold out and nothing is held. Tested: "storefront checkout journey"

• A checkout or payment request sent twice. A retried checkout holds stock once and returns the same answer. Two payment requests at once create one charge with the provider. When the provider may have taken the money but the answer was lost, the shop doesn't charge again: the customer is told the payment is under review and staff get an urgent item to resolve. Tested: "storefront commands" Tested: "commerce-payments-e2e"

• A payment confirmed by more than one path. If the payment webhook never arrives, the shop asks the provider when the customer comes back from paying, and a paid charge confirms the order. A webhook followed by that check records one payment and one stock deduction. A charge the provider reports as refunded never marks the order paid. Tested: "commerce-payment-confirm-b2"

• Shoppers who never pay, and crashes after payment. An unpaid checkout keeps its stock through a one-minute grace period after its hold ends, then the order expires and the stock is released. If a paid order's stock deduction fails, the next background sweeps deduct it once, even when two sweeps overlap. Tested: "storefront upkeep"

• Money owed back. Cancelling a paid order records what the customer is owed and adds it to the staff queue until it's refunded or waived. Items returned one at a time each owe their share of what was paid after a discount code. A new app's Staff role can't record a refund; its Manager role can. Tested: "storefront refunds owed"

• Gift cards. A gift card can pay part of an order, and the provider charges only the rest. A card that covers the whole order pays it without the provider. The same return submitted twice at once restocks, owes money and credits the card once. Tested: "storefront gift cards" Tested: "storefront returns and cancels take gift cards back once"

• Bank transfer slips. A shopper uploads a slip and staff verify it, or reject it with a reason that's emailed to the shopper so they can send another. Two staff verifying the same slip at once mark the order paid once. Staff without online-order access, or at another location, can't verify. Tested: "merchant reviews a bank transfer slip"

• A shopper's private order link. A guest's order page needs the secret token from checkout. A missing or wrong token gets "not found", and a cancel without the token is refused. A visitor sending more than 30 requests a minute is refused until the minute is up, while other shoppers carry on. Tested: "guest-manage-token"

• A sale price checkout honours. A running sale shows on the product page at the price a cart of that item is charged, and the page goes back to the regular price when the sale ends. A compare-at price that isn't above the price shows no sale. Tested: "storefront compare-at prices"

• Discounts that add up. A 10% code spreads over the lines it discounts, never the gift card, and the lines add up to the order's discount to the cent. A collection sale discounts only the products in the collection, and a register-only discount never applies online. Tested: "storefront promotions" Tested: "storefront gift cards are never discounted"

• Discounts that combine, or don't. A sale and free shipping that allow each other both apply, and a sale that combines with nothing applies alone. An order discount on top of a 50% item discount is capped at what's left. Buy 2 get 1 free gives away the cheapest unit, and a once-per-order offer gives one free unit of six. A gold-tier discount reaches a signed-in gold member and not a silver one. When the last use of one code in a set went to another shopper, checkout claims none of the set and applies the discounts still available. Tested: "Discounts: combining, quantity rewards and members in the shop"

• Free gifts that come and go. Three Spring shirts put the free tote in the cart, and dropping to two takes it out. A tote the shopper added at full price stays theirs, a removed gift isn't added again, and a gift whose offer was switched off is taken out at checkout, never charged. With one tote left, the second cart to check out with it is refused as sold out. Tested: "storefront free gifts" Tested: "storefront free gifts at checkout" Tested: "a free gift's stock is claimed at checkout like any line"

• A sale's own page. An automatic discount with a page lists exactly the products it applies to, at the price checkout charges. When the discount is switched off, has ended, hasn't started, needs a code, sells only at the register or loses its page, the page answers not found. Tested: "Storefront: a sale's page on the website"

What you build on topCopy Anchor Link

• Modules that work with the shop. Catalog and Inventory are required. Website makes the shop part of the site: the shop page gets the owner's own headline, pictures and testimonials through the storefront.shop-page slot, the site's menu gets Shop with the collections under it, and the homepage gets a featured products section. Without Website the shop shows its own header. POS sells from the same stock at the register. Customers records shoppers and sends checkout reminders, and Membership adds loyalty points and member discounts. See Extend a Module.
• Payments. Card and PromptPay checkout go through the app's Beam payment connection, for orders in Beam's currency (THB). Card checkout through Stripe is offered when the app has a Stripe Connect account. Bank transfer is a shop setting of its own and needs no provider.
• Your words. Rename what shoppers and staff see with an override.
• In code. Your coding agent imports Storefront only through its public API: index.ts and server/index.ts in apps/web/src/modules/storefront/. See Build on a Module.

LimitsCopy Anchor Link

• Refunds are records. Staff return the money through the payment provider or by transfer, then record it; Storefront doesn't send a refund to the provider.
• Shipping is one flat fee per order (a free-shipping discount can waive it). There are no live carrier rates or shipping labels; staff enter the carrier and tracking number.

FactsCopy Anchor Link

• Kind: feature Module, can be switched on and off
• Needs: Audit log, Branches, Catalog, Discounts, Formatting, i18n, Identity, Infra, Inventory, Outbox, Standard UI
• Needed by: Nothing
• Adds to these when they're on: Account, Customers, Website, POS, Membership
• Added to by: Finance, Supply chain
• Off by default for these business types: Restaurant, Tour operator, Gym, Online classes, Car hire

Pages

Where	Path
Admin	/admin/storefront/orders
Admin	/admin/storefront/operations
Admin	/admin/storefront/customers
Admin	/admin/storefront/gift-cards

Permissions

Admin holds every key. The other roles listed hold it when the app first gets the Module; after that, roles are yours to change under Settings → Roles & Permissions.

Permission	What it allows	Organization roles that start with it
admin-panel:write	Full compatibility access to all module administration, including POS, catalog, storefront, and CRM staff tools.	Admin
storefront:write	Manage storefront orders and fulfilment operations.	Admin, Manager
storefront-orders:write	Work online orders: see them, take one for a customer, confirm payment, ship and deliver.	Admin, Manager, Staff

Data

• Tables: shop_customer, shop_order, order_line, shop_payment, shipment, storefront_tax_config, shop_order_event, counter, payment_evidence, shop_payment_refund, shop_refund_due, order_return, order_request, operational_exception, operational_exception_event, customer_change_event, gift_card, gift_card_ledger

Slots

Places other Modules and your app code can add to. See Extend a Module.

• storefront.shop-page

Tested workflows

• Discounts: combining, quantity rewards and members in the shop
• Shop checkout follows Beam's live readiness
• commerce janitor: runs only when something is due
• Storefront on the admin home and in search
• Storefront: orders list at the shell's location
• commerce-payment-confirm-b2
• guest-manage-token
• commerce-payments-e2e
• customer-portal
• merchant order operations
• find your order
• cancel an unpaid order
• ask the shop to cancel or return
• storefront-public-api
• storefront commands
• storefront order emails
• storefront catalog handoff
• storefront checkout journey
• storefront free gifts
• storefront free gifts against a better sale
• storefront free gifts at checkout
• storefront keep selling when out of stock
• storefront first run on an empty workspace
• storefront upkeep
• storefront ERP stock sync
• Storefront: the company an online order is sold as
• storefront refunds owed
• storefront staff orders
• storefront order list
• storefront packing
• storefront promotions
• storefront browse filters
• storefront pay an expired order
• storefront gift cards
• storefront gift cards are never discounted
• storefront returns and cancels take gift cards back once
• storefront product story
• storefront product swatches
• Reset with sample data for an online snack store
• storefront without loyalty: no points work
• merchant reviews a bank transfer slip
• Beam card and PromptPay on the shop's own pages
• Storefront: a sale's page on the website
• Storefront + customers: activity projection (with Customers on)
• Storefront + customers: source panel (with Customers on)
• Storefront + customers: checkout recovery emails (with Customers on)
• Storefront + customers: one set of contact details (with Customers on)
• Pos: produced shop products (with POS on)
• Storefront + POS: the register and the shop on one shelf (with POS on)
• commerce-rewards-accrual (with Membership on)
• commerce-rewards-janitor (with Membership on)
• commerce-rewards-portal (with Membership on)
• storefront Loyalty points through cold background routes (with Membership on)
• storefront loyalty switched off and back on (with Membership on)