The Complete Shop Order Flow: Buy, Ship, Confirm
When you buy items from a player-owned shop in Erleuchtung, the order goes through a carefully designed flow that protects both the buyer and the seller. Here’s how it works — step by step.
The Flow
1 Buyer places order and pays
BUYER The buyer adds items to their cart, checks out, and sends the payment on-chain to the server’s operator wallet. The coins are held in escrow — the seller does not receive them yet.
2 Seller gets notified
SELLER The server sends an SSE notification (a toast popup in the game) and an email to the shop owner: “New order from [buyer]!” The seller opens their shop dashboard and sees the order with buyer name, items, and amount.
3 Seller ships the goods
SELLER The seller clicks “Mark as Shipped” and can add a note for the buyer (e.g. tracking info or delivery instructions). The order is timestamped with shipped_at.
4 Buyer gets shipping notification
BUYER The buyer receives a green toast notification: ”📦 Your order has been shipped!” — plus an email with the seller’s note. The buyer can now check their orders and see the shipping status.
5 Buyer confirms receipt
BUYER Once the goods are received, the buyer clicks “Confirm Receipt”. This releases the escrow: 98% of the payment is sent on-chain to the seller’s wallet. The server keeps a 2% commission.
6 Payout complete
SELLER The seller sees the payout in their wallet. The order’s payout status changes from escrow to paid. Done!
What if something goes wrong?
Dispute
If the buyer doesn’t receive the goods, or they’re not as described, the buyer can click “Dispute” instead of confirming. This freezes the escrow — the seller gets no payout. An admin reviews the case and either:
- Releases the payout to the seller (if the dispute is unfounded), or
- Refunds — the payout is cancelled and the coins stay with the server (the buyer can be compensated manually)
Auto-release after 7 days
If the buyer doesn’t confirm or dispute within 7 days, the payout is released automatically to the seller. A background worker checks every hour for expired escrows. This prevents buyers from holding seller payouts hostage indefinitely.
Order Status Reference
| Status | Meaning |
|---|---|
pending | Order created, payment not yet confirmed on-chain |
paid | Payment confirmed on-chain, goods being delivered |
escrow | Payment held by server, waiting for buyer confirmation |
shipped | Seller has marked the order as shipped |
disputed | Buyer disputed, admin review pending |
paid (payout) | 98% sent to seller on-chain |
refunded | Admin cancelled payout |
Notifications
| Event | Who gets notified | How |
|---|---|---|
| New order received | Seller | SSE toast + email |
| Order shipped | Buyer | SSE toast + email |
| Receipt confirmed | Seller | Payout arrives on-chain |
| Dispute filed | Seller (via admin) | Payout frozen |
| Auto-release | Seller | Payout arrives on-chain |
Revenue Share
| Recipient | Share |
|---|---|
| Shop owner | 98% |
| Server commission | 2% |
The 2% commission covers infrastructure costs: blockchain gas, server hosting, and the escrow service.
Why This Matters
Without this flow, there’s no trust between buyers and sellers. A buyer could pay and never receive goods. A seller could deliver and never get paid. The escrow system ensures both sides fulfill their obligations — and the notification system ensures nobody is left in the dark wondering what to do next.
Every step is transparent: both buyer and seller can see the order status, payment status, shipping status, and payout status at any time in their respective dashboards.