E-Commerce — Order Management¶
OWNER: aimee (scoping) ALSO_USED_BY: anna (spec), urszula, maxim (backend), faye (PM Alfa), sytske (PM Bravo) LAST_VERIFIED: 2026-03-26
Overview¶
Order management covers the full lifecycle from payment confirmation to delivery and beyond (returns, exchanges, disputes). The admin panel is the primary interface for order management — most clients handle orders themselves, so the UX must be self-explanatory for non-technical shop owners.
Feature Decomposition¶
Order Lifecycle¶
placed → confirmed → processing → shipped → delivered
→ partially_delivered
→ on_hold (manual, fraud check)
cancelled ←───────┘
returned ← return_requested
exchanged ← exchange_requested
disputed ← chargeback received
refunded ←──────────────────────────┘
SCOPE_ITEM: Order creation INCLUDES: Order created on checkout completion (status: placed), auto-transition to confirmed on payment success, order number generation (prefix + sequential: GE-10001, GE-10002) OPTIONAL: Custom order number format per client ESTIMATE_COMPLEXITY: simple
SCOPE_ITEM: Order status management INCLUDES: Status transitions with validation (cannot go from shipped back to processing), status change timestamp log, admin status update with optional note OPTIONAL: Automated status transitions (e.g., auto-confirm on payment, auto-ship on label creation) ESTIMATE_COMPLEXITY: normal
SCOPE_ITEM: Order detail view (admin) INCLUDES: Customer info, shipping address, billing address, line items with images, payment status and method, shipping status and tracking, order timeline (all status changes with timestamps and actor), action buttons (confirm, ship, cancel, refund) ESTIMATE_COMPLEXITY: normal
SCOPE_ITEM: Order detail view (customer) INCLUDES: Order status with progress indicator, line items, tracking link (when shipped), invoice download, return/withdrawal request button (within 14-day window) ESTIMATE_COMPLEXITY: simple
Status Notifications¶
SCOPE_ITEM: Transactional emails INCLUDES: Order confirmed, order shipped (with tracking link), order delivered (estimated), refund processed OPTIONAL: Order processing (for custom/handmade products with longer lead times), delivery reminder, review request (7 days post-delivery) COMPLIANCE: Confirmed email must include withdrawal rights and return instructions ESTIMATE_COMPLEXITY: normal
CHECK: Notification channels IF: MVP → email only (Brevo (FR) or Mailjet (FR) preferred. Resend/Postmark secondary — US-based, EU data sovereignty risk) IF: full → email + optional SMS (for shipping updates) IF: client requests → push notifications (requires mobile app or PWA)
SCOPE_ITEM: Admin notifications INCLUDES: New order alert (email and/or admin dashboard), low stock alert, failed payment alert OPTIONAL: Daily order summary email, webhook to external system (Slack, Teams) ESTIMATE_COMPLEXITY: simple
Returns & Exchanges¶
SCOPE_ITEM: Return request (customer-initiated) INCLUDES: Return request form (reason, which items, photos optional), auto-approve within 14-day withdrawal period, return shipping label generation (if integrated with carrier), return status tracking COMPLIANCE: EU 14-day withdrawal right — consumer can return for ANY reason within 14 days of delivery. Must refund within 14 days of receiving returned goods. Consumer pays return shipping unless seller advertises free returns. ESTIMATE_COMPLEXITY: normal
SCOPE_ITEM: Return processing (admin) INCLUDES: View return requests, approve/reject (with reason), mark items as received, inspect condition (re-stock or write off), trigger refund (full or partial based on condition) OPTIONAL: Restocking fee (only for opened/used items outside withdrawal period, NOT during 14-day withdrawal) COMPLIANCE: During 14-day withdrawal — no restocking fee, no questions asked. After 14 days — seller's return policy applies. ESTIMATE_COMPLEXITY: normal
SCOPE_ITEM: Exchange INCLUDES: Customer requests different size/color/variant, creates linked return + new order, price difference handling (charge more or refund difference) OPTIONAL: Instant exchange (ship new before receiving return) ESTIMATE_COMPLEXITY: normal
CHECK: Return logistics IF: NL domestic → PostNL return label, service point drop-off IF: EU cross-border → DHL return label or buyer-arranged return IF: digital products → no physical return, access revocation
Cancellations¶
SCOPE_ITEM: Order cancellation (customer) INCLUDES: Cancel button available before shipping, automatic stock release, automatic refund initiation COMPLIANCE: EU — customer can cancel any time before delivery (part of 14-day withdrawal). After delivery, the 14-day return window applies instead. ESTIMATE_COMPLEXITY: simple
SCOPE_ITEM: Order cancellation (admin) INCLUDES: Cancel with reason (out of stock, fraud, duplicate, customer request), automatic refund, customer notification email ESTIMATE_COMPLEXITY: simple
Dispute Handling¶
SCOPE_ITEM: Chargeback management INCLUDES: Webhook notification from Mollie/Stripe on chargeback, order flagged as disputed, evidence collection tools (order details, delivery proof, communication) OPTIONAL: Automated evidence submission (Stripe), fraud scoring COMPLIANCE: Respond within provider's deadline (Mollie: varies by bank, typically 7-14 days) ESTIMATE_COMPLEXITY: normal
Admin Order Management¶
SCOPE_ITEM: Order list and filtering INCLUDES: Sortable/filterable order list, filter by status, date range, customer, payment method, search by order number or customer email OPTIONAL: Bulk actions (bulk ship, bulk print labels), export to CSV ESTIMATE_COMPLEXITY: normal
SCOPE_ITEM: Order notes INCLUDES: Internal notes (visible to admin only), customer-facing notes (included in emails), note history with author and timestamp ESTIMATE_COMPLEXITY: simple
SCOPE_ITEM: Order editing INCLUDES: Edit shipping address (before shipping only), add/remove items (recalculates total), manual price adjustment with reason OPTIONAL: Split order (ship partial, hold rest) COMPLIANCE: Price changes must be communicated to and accepted by customer before charging ESTIMATE_COMPLEXITY: normal
Database Schema Pattern¶
orders (id, order_number, user_id, email, status, shipping_address_json, billing_address_json,
subtotal_cents, shipping_cents, tax_cents, discount_cents, total_cents, currency,
shipping_method, tracking_number, tracking_url, notes, created_at, updated_at)
order_items (id, order_id, product_variant_id, product_name, variant_name, sku, quantity,
unit_price_cents, total_cents, created_at)
order_status_history (id, order_id, from_status, to_status, actor, note, created_at)
returns (id, order_id, status, reason, items_json, tracking_number, refund_id, created_at, updated_at)
order_notes (id, order_id, author, content, is_internal, created_at)
Implementation Patterns¶
Idempotent Order Creation¶
On payment webhook (paid):
1. Find order by payment ID
2. IF order.status already confirmed or later → return 200 (idempotent)
3. BEGIN TRANSACTION
4. Update order status to confirmed
5. Decrease stock for each line item
6. Insert status history record
7. COMMIT
8. Send confirmation email (outside transaction — email failure must not roll back order)
The June 2026 "Cancel My Contract" Button¶
From 19 June 2026, EU Directive 2023/2673 requires: - A visible "withdraw from the contract here" button on the customer's order page - After clicking, a confirmation step: "confirm withdrawal here" - Must be available during the entire 14-day withdrawal period - Two-click maximum to complete withdrawal
CHECK: Is the launch date after June 2026? IF: yes → the withdrawal button is mandatory from day one IF: no → implement anyway, it becomes mandatory shortly
Anti-Patterns¶
ANTI_PATTERN: Deleting cancelled orders from the database FIX: Soft delete or status change only. Cancelled orders are needed for reporting, tax, and dispute resolution.
ANTI_PATTERN: Sending confirmation email inside the database transaction FIX: Email sending outside transaction. If email fails, the order must still be confirmed.
ANTI_PATTERN: No order status history FIX: Every status change must be logged with timestamp, actor, and optional note. Essential for disputes.
ANTI_PATTERN: Allowing admin to edit orders after shipping FIX: Lock most fields after shipping. Only notes and tracking info should be editable.
Cross-References¶
READ_ALSO: wiki/docs/archetypes/e-commerce/payments.md READ_ALSO: wiki/docs/archetypes/e-commerce/cart-checkout.md READ_ALSO: wiki/docs/archetypes/e-commerce/integrations.md READ_ALSO: wiki/docs/archetypes/e-commerce/compliance.md READ_ALSO: wiki/docs/archetypes/e-commerce/checklist.md