# Storefront (/docs/app/storefront)

> Study: a study of the work. Defines nothing. No package exists.

> App study: everything after the cart for a Business that sells goods or digital products, from checkout to returns and disputes.



A storefront is the App a Business that sells goods or digital products runs after the cart. It holds the hosted checkout, the shopper's view of each Order, and the merchant's order desk.

The desk pays, fulfils, ships, cancels, edits, returns, refunds, disputes and reviews fraud. Browsing, product pages and the cart live on the Site; checkout is the seam between the Site and the App.

Any Business that sells things ships one: a bakery, a bookshop, a direct-to-consumer brand, a distributor's reorder portal, a software vendor selling licences. Its defining complexity is that the Order is a header over several independent machines.

Every simple model flattens them into one status. The study describes the work; how an App is defined is open, see [What every App needs](https://next.mdxui.dev/docs/app/every-app).

## Actors

| Side | Actors | Relation to the Order |
| --- | --- | --- |
| Demand | Guest shopper; account shopper; payer who is not the shopper; gift recipient; subscriber | Requester; payer; a recipient sees tracking, never the price |
| Demand, B2B | Company buyer per location; approver over a threshold; accounts payable with net terms and a tax-exempt certificate | Requester; reviewer before placement; invoice payer |
| Merchant | Owner; order and fulfilment staff; support; finance; risk reviewer; merchandiser; marketer; purchasing; POS associate | Owner of the store and its one-way money Verbs; performers; reviewers |
| Third parties | Upstream supplier or dropshipper; 3PL; carrier; payment processor; issuing bank; an outside merchant of record; a sales venue that collects Orders elsewhere | Performer on its own fulfilment orders; operator of the payment rail; decider on a chargeback |

Agents fill the merchant's Roles. A support agent answers "where is my order" and refunds under its Mandate; one guide sets $50. A billing agent captures, reconciles and assembles dispute evidence.

A risk agent screens Orders, and an operations agent routes fulfilment and chases suppliers. A buyer's agent shops under its principal's Mandate and sees the same price list people see.

## Interfaces

| Reader | Screens | Renderings |
| --- | --- | --- |
| Shopper | Checkout (contact, delivery or pickup or digital-only, delivery method with an estimate, discounts with the reason a code failed, tax and duties lines, payment, review and pay with the withdrawal notice); an order status page from a signed URL with no login; account with orders, per-line state, shipments, documents, downloads, licence keys, returns, subscriptions, addresses, store credit, privacy; B2B company tools | Email for confirmation, payment action needed, shipping, delivery, delays with a cancel option, digital delivery, returns and refunds; SMS updates under consent; branded tracking; PDF invoices and credit notes; buy buttons and payment links; MCP and REST for a buyer's agent |
| Merchant staff | Orders with saved views (unfulfilled, authorised not captured, on hold, high risk, disputed, by venue or agent buyer); order detail with timeline, payment, risk, one panel per fulfilment order, returns, edit and cancel, a refund dialog showing the Limit; fulfilment queue per location; supplier request board; returns inspection; disputes by deadline; fraud review; draft orders and quotes; catalog; inventory; discounts; customers; settings; merchant analytics (order value, conversion, return rate by product); POS | New-order alerts; a daily "needs you" digest; inbox Approvals; pick and pack worklists; webhooks; accounting sync |
| Supplier, 3PL | A light portal or API to accept or reject requests, ship with tracking and handle cancel requests | Inventory feed |

## Records and actions

| Machine or record | States |
| --- | --- |
| Order header | draft (quote), open, closed or canceled; an on-hold overlay; archived. Paid, fulfilled and refunded are badges, not states |
| Payment, one per tender | pending, authorised, captured (partial per shipment), partially refunded, refunded; voided; expired and reauthorised; failed; a dispute overlay ending won or lost |
| Fulfilment order, per location or supplier | open, scheduled or on hold, requested, accepted, in progress, closed; rejected and re-routed; cancellation requested, then canceled or rejected |
| Shipment | label created, in transit, out for delivery, delivered; exception, returned to sender, lost |
| Return | requested, open or declined, in transit, received, inspected, processed; canceled |
| Refund | requested, approved or declined, pending, succeeded or failed, then store credit or manual |
| Reserved act at checkout | pending on an appointed, licensed seller (insurance sold at someone else's checkout), with its named act and party; cleared only by that seller's act |
| Line ledger | quantities ordered, fulfilled, returned, refunded, canceled; refunded never exceeds captured |
| Inventory unit | available, reserved with a time limit, committed, fulfilled; returns go to restocked, damaged or back to vendor |
| Entitlement, licence key | granted, revoked on refund or a lost dispute, expired |

Verbs that exist on startupbuilder.dev's Order: place, screen, pay, fulfill, deliver, confirm, cancel, refund, dispute. The type also needs:

- **Checkout and Order:** start and complete checkout; capture, edit, hold and release an Order.
- **Payment:** authorise, void and reauthorise.
- **Fulfilment:** route, request, accept and reject; create and track a shipment.
- **Returns:** request, approve, receive, inspect and process; issue a refund to a destination.
- **Stock and balances:** reserve, commit and release inventory; issue and redeem store credit; issue and revoke a licence key.

### Terms

| Term | In startupbuilder.dev | Definition, quoted from [startupbuilder.dev](https://startupbuilder.dev) or the gap |
| --- | --- | --- |
| Order | [Order](https://startupbuilder.dev/business/nouns/order) | "An Order is a Customer's commitment to buy one or more Offers once, moving from placed to paid, fulfilled, and closed." Single-axis; closed means sign-off, a Service idea, where goods close when the return window ends. |
| Offer | [Offer](https://startupbuilder.dev/business/nouns/offer) | "An Offer is a Product, under a Brand, at a price, on terms, made by a Startup." Read for any Business. |
| A size or color option | collides | startupbuilder.dev's Variant is an Experiment arm. |
| Goods supplier | collides | startupbuilder.dev's Supplier is human supply; the dropship upstream is business-as-code's Vendor. |
| Product review | collides | In the Portal, Review means accept, refund or repeat. |
| Cart, checkout, order line, payment record, fulfilment, shipment, return, exchange, credit note, store credit, duties, address, licence key, location | lack | |
| Inventory | narrowed | Exists at the Business layer; startupbuilder.dev's dropship Product Template avoids it because the upstream holds stock. |
| Credential | [Credential](https://startupbuilder.dev/business/nouns/credential) | "A Credential is a standing authority a regulator grants a person or entity to perform certain acts in a jurisdiction." A buyer-side credential that gates a purchase, such as a licensed dealer's, is a gap. |

## Workflows

1. **Merchant onboarding.** Pass entity and processor identity checks, and set up payouts. Register for tax where the merchant has nexus and code every product, or use an outside merchant of record. Set shipping profiles or the supplier's lead times. Write policies for returns, refunds, risk and agent buyers. Create or migrate the catalog, place a test order, then go live.
2. **Checkout to closed Order.** Re-price the cart on the server. Identify the shopper, validate the address, and reserve inventory with a time limit. Apply discounts with atomic caps, compute tax and duties, and screen: allow, authenticate, review or block. Then authorise, with goods captured on shipment, or capture now for digital lines. Place the Order idempotently with the Offer Version and price frozen. Route into fulfilment orders, fulfil, track and deliver. The return window opens, and its end closes the Order.
3. **Unhappy paths.** Paid with no Order: reconcile from processor events. Out of stock after payment: cancel and refund the line, or offer backorder. An authorisation expires before shipment: reauthorise or ask for a new method. A supplier rejects: re-route or refund. A late shipment needs a delay notice with a cancel option. "Not received" after delivery: proof of delivery, then reship or refund, and expect a chargeback.
4. **Cancel and edit.** Before fulfilment, void or refund and release the reservation. An edit with a higher total needs a new authorisation. After a supplier accepted, cancellation is a request the supplier may reject. After shipment, cancel becomes a return.
5. **Returns and exchanges.** Request with reason and photos, and decide by policy. Give a label, a drop-off, an in-store return or keep-it. Receive and inspect, then refund to the original method, issue store credit or exchange.

Money:

- posted prices per market, tax-inclusive or exclusive by region, and split tender;
- processor, platform and merchant-of-record fees;
- payouts with reserves and negative balances;
- refunds per line, with tax and discount pro-rated;
- disputes, with funds and fee debited at once and a hard answer deadline.

Store credit and gift balances edge toward stored value, which law regulates.

## Boundaries

- A guest's order status URL is a capability token: it expires, is never logged and never indexed.
- The shopper never sees risk scores, fraud rules, internal notes, cost, margin, or a blind dropshipper's identity.
- A supplier sees only its own fulfilment orders, lines and ship-to. It never sees payment, other suppliers' lines or retail prices; carriers get address and phone only.
- Nobody, person or agent, sees a full payment number.
- One shopper across many merchants sees the union of their orders; each merchant sees only its own slice. Sibling Startups in a Studio do not pool customers by default.
- The platform operating the rails reads shopper data only through recorded break-glass access the merchant sees.
- Erasure anonymises the profile while invoices and tax records stay for the statutory period.
- Merchant analytics reads the shared measurement plane. Customers appear in aggregate; a named Customer appears only in an owner-private rendering.
- An Offer sold only to licensed buyers checks the buyer's credential at checkout and on every reorder.

## Agents

| Step | Agent | Human |
| --- | --- | --- |
| Product copy, images, translations | yes | regulated claims |
| Pricing | proposes | every change of price |
| Screening Orders | yes | review outcomes above a value |
| Routing, supplier chasing, delay notices, where-is-my-order | yes | a new supplier |
| Returns inside the policy | yes | exceptions; suspected return fraud |
| Refunds | within the Mandate Limit | above it, or after a dispute opened |
| Dispute evidence | assembles | accept or fight above a value |
| Tax thresholds | detects | filing and signing |
| Identity checks, payout destination | no | always, the owner |
| Held agent Orders | no | the merchant approves or declines |

The Autonomous storefront template runs with no humans, so every human cell goes somewhere. It goes to an upstream (a supplier or merchant of record), a declared Policy such as an auto-refund rule, or the Studio's human floor.

## Hard parts

1. **The Order is a header over sub-machines.** Partial capture, partial fulfilment, split shipments, partial returns, exchanges and disputes need per-line quantities and separate records.
2. **Refund is not return is not restock.** A goodwill refund on a delivered Order restocks nothing; an exchange refunds nothing; restock happens after inspection.
3. **Reservation.** A check-then-write oversells under concurrency, and supplier feeds lag. Reserve, commit and release are atomic with a time limit.
4. **Who is the merchant of record.** It decides who owes tax, who answers under consumer law, and who bears chargebacks. A Startup on Connect cannot use Stripe's merchant-of-record service, so it is its own merchant of record unless a third party sits upstream.
5. **Tax and duties.** US economic nexus by state, EU and UK VAT schemes, product tax codes and exemption certificates. HS codes and duty terms, where surprise charges cause refused parcels and chargebacks.
6. **Dropship.** The supplier's promise becomes the merchant's, its stockouts arrive after the sale, and its return policy may be stricter than the published one. The merchant is still the seller for consumer law and product safety.
7. **Fraud as an operations queue.** Chargeback ratios above network thresholds end processing; testing stolen payment numbers attacks the checkout endpoint; friendly fraud dominates digital goods.
8. **The agent buyer's authority.** No API records the principal's authority at purchase. A storefront that keeps the caller, principal, Mandate and request trace on the Order is ahead of the protocols.
9. **Reserved acts inside a checkout.** Insurance offered at another merchant's checkout is a reserved act by an appointed seller. The checkout carries a typed pending state with a clock, never a silent add-on.

## Day one

For an idea-stage founder, day one holds:

- reserve first, with a waitlist or a refundable pre-order;
- one hosted checkout per Offer, with tax on, one shipping rate or "ships from supplier", and promo codes;
- a confirmation email, and a no-login status page with tracking passed through;
- a merchant order list and detail with supplier requests, tracking, and full or partial refunds under an always-ask Policy;
- digital lines delivered at once;
- disputes in the founder's [Worklist](https://next.mdxui.dev/docs/app/worklist) with their deadline;
- an agent channel with the same Offers and a cap;
- a test order before go-live.

A bakery adds inventory at one location, local pickup and delivery days.

| Stage | Turns on |
| --- | --- |
| Repeatable | Passwordless accounts, a returns portal, split shipments and supplier re-routing, recovery and review emails, a discount engine, a fraud queue, tax registrations and VAT invoices, subscriptions that create Orders |
| Scale | Multi-location inventory and 3PLs, markets and duties, B2B companies with net terms, POS and omnichannel returns, venue Orders, migration tooling |

The Startup layer narrows Startups to digital by design: dropship only, so no inventory or shipping screens. For most Startups, checkout is a step on the Site that leads into a [party portal](https://next.mdxui.dev/docs/app/service-portal) or [developer portal](https://next.mdxui.dev/docs/app/developer-portal). A full storefront appears only when goods or digital products are sold.

## Related studies

## Prototypes this study needs