Storefront

Sides

The shopper and the merchant's staff

Unit of work

The Order and its payment, fulfilment and return machines

Examples

• None named

The five tests

1. who signs in
2. which record dominates
3. who acts next
4. how money moves
5. who may settle what

Carried only by it, from What every App needs

Order sub-machines with a per-line ledger; inventory reservation; tax and merchant of record; reverse logistics

Screens its Interfaces name, by reader

Shopper

Checkout · 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

Merchant staff

Orders with saved views · 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 · POS

Supplier, 3PL

A light portal or API to accept or reject requests, ship with tracking and handle cancel requests

Build today: the Site pages around it

• product-list
• pricing
• plan-table

4actors5workflows10records

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.

Demand2 actors

• Guest shopper; account shopper; payer who is not the shopper; gift recipient; subscriberWorkRequester; payer; a recipient sees tracking, never the price
• Company buyer per location; approver over a threshold; accounts payable with net terms and a tax-exempt certificateB2BWorkRequester; reviewer before placement; invoice payer

Merchant1 actor

• Owner; order and fulfilment staff; support; finance; risk reviewer; merchandiser; marketer; purchasing; POS associateWorkOwner of the store and its one-way money Verbs; performers; reviewers

Third parties1 actor

• Upstream supplier or dropshipper; 3PL; carrier; payment processor; issuing bank; an outside merchant of record; a sales venue that collects Orders elsewhereWorkPerformer on its own fulfilment orders; operator of the payment rail; decider on a chargeback

1. 01
   Workflow 1: Merchant onboarding

   1. 1.1Pass entity and processor identity checks, and set up payouts.
   2. 1.2Register for tax where the merchant has nexus and code every product, or use an outside merchant of record.
   3. 1.3Set shipping profiles or the supplier's lead times.
   4. 1.4Write policies for returns, refunds, risk and agent buyers.
   5. 1.5Create or migrate the catalog, place a test order, then go live.
2. 02
   Workflow 2: Checkout to closed Order

   1. 2.1Re-price the cart on the server.
   2. 2.2Identify the shopper, validate the address, and reserve inventory with a time limit.
   3. 2.3Apply discounts with atomic caps, compute tax and duties, and screen: allow, authenticate, review or block.
   4. 2.4Then authorise, with goods captured on shipment, or capture now for digital lines.
   5. 2.5Place the Order idempotently with the Offer Version and price frozen.
   6. 2.6Route into fulfilment orders, fulfil, track and deliver.
   7. 2.7The return window opens, and its end closes the Order.
3. 03
   Workflow 3: Unhappy paths

   1. 3.1Paid with no Order: reconcile from processor events.
   2. 3.2Out of stock after payment: cancel and refund the line, or offer backorder.
   3. 3.3An authorisation expires before shipment: reauthorise or ask for a new method.
   4. 3.4A supplier rejects: re-route or refund.
   5. 3.5A late shipment needs a delay notice with a cancel option.
   6. 3.6"Not received" after delivery: proof of delivery, then reship or refund, and expect a chargeback.
4. 04
   Workflow 4: Cancel and edit

   1. 4.1Before fulfilment, void or refund and release the reservation.
   2. 4.2An edit with a higher total needs a new authorisation.
   3. 4.3After a supplier accepted, cancellation is a request the supplier may reject.
   4. 4.4After shipment, cancel becomes a return.
5. 05
   Workflow 5: Returns and exchanges

   1. 5.1Request with reason and photos, and decide by policy.
   2. 5.2Give a label, a drop-off, an in-store return or keep-it.
   3. 5.3Receive and inspect, then refund to the original method, issue store credit or exchange.

Order header7 states

1. draft (quote)
2. open
3. closed or canceled
4. an on-hold overlay
5. archived. Paid
6. fulfilled and refunded are badges
7. not states

Payment, one per tender9 states

1. pending
2. authorised
3. captured (partial per shipment)
4. partially refunded
5. refunded
6. voided
7. expired and reauthorised
8. failed
9. a dispute overlay ending won or lost

Fulfilment order, per location or supplier9 states

1. open
2. scheduled or on hold
3. requested
4. accepted
5. in progress
6. closed
7. rejected and re-routed
8. cancellation requested
9. canceled or rejected

Shipment7 states

1. label created
2. in transit
3. out for delivery
4. delivered
5. exception
6. returned to sender
7. lost

Return7 states

1. requested
2. open or declined
3. in transit
4. received
5. inspected
6. processed
7. canceled

Refund5 states

1. requested
2. approved or declined
3. pending
4. succeeded or failed
5. store credit or manual

Reserved act at checkout4 states

1. pending on an appointed
2. licensed seller (insurance sold at someone else's checkout)
3. with its named act and party
4. cleared only by that seller's act

Line ledger6 states

1. quantities ordered
2. fulfilled
3. returned
4. refunded
5. canceled
6. refunded never exceeds captured

Inventory unit6 states

1. available
2. reserved with a time limit
3. committed
4. fulfilled
5. returns go to restocked
6. damaged or back to vendor

Entitlement, licence key3 states

1. granted
2. revoked on refund or a lost dispute
3. expired

ActorsCopy Anchor Link

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.

InterfacesCopy Anchor Link

Records and actionsCopy Anchor Link

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.

TermsCopy Anchor Link

Terms3 quoted from startupbuilder.dev · 1 it lacks · 3 colliding

Term	In startupbuilder.dev	Definition, quoted from startupbuilder.dev or the gap
Order	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	"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	"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.

WorkflowsCopy Anchor Link

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.

BoundariesCopy Anchor Link

• 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.

AgentsCopy Anchor Link

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 partsCopy Anchor Link

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 oneCopy Anchor Link

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 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.

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 or developer portal. A full storefront appears only when goods or digital products are sold.

Related studiesCopy Anchor Link

Prototypes this study needsCopy Anchor Link

1. 01

   Can one lifecycle notation hold concurrent machines, the ball and derived state?

   Encode a storefront Order, a booking with its payment, a delivery work item, a Task over its Action and a facility with its applications.

   names: storefrontnames: Order
2. 02

   Do Order states plus a work record carry collect, earn and reverse?

   Postings for a service, a goods Order with partial refund, a refund after payout, a zero-take route and a flat fee.

   names: Order