Order Management¶
BadgerCommerce provides a comprehensive order management system that handles the complete lifecycle of customer orders from creation to fulfillment.
Key Features¶
Order Creation & Processing¶
- Stateful Order Flow: Orders move through clearly defined states from creation to completion
- Multi-item Support: Handle orders with multiple products and variants
- Order Splitting: Capability to split orders for partial fulfillment
- Order Merging: Merge carts from guest sessions with customer accounts
- Order History: Comprehensive history tracking of all order state changes
Checkout Experience¶
- One-page Checkout: Streamlined checkout process
- Express Checkout: Save customer details for faster future checkouts
- Guest Checkout: Allow customers to check out without creating an account
- Address Validation: Real-time validation of shipping and billing addresses
- Order Review: Final review step before payment submission
Payment Processing¶
- Stripe Integration: Secure payment processing via Stripe
- Multiple Payment Methods: Support for credit cards, digital wallets, and more
- Partial Payments: Support for split payments across multiple methods
- Saved Payment Methods: Securely store payment details for future use
- Refund Management: Process full or partial refunds, from the admin order page, the admin API (
POST /v1/admin/orders/{orderId}/refund,/refund/partial) or MCP. A refund goes back to the cards first. On an order paid partly or wholly in cash at the till, the rest is recorded as cash given back, and the page, the API answer (cashToHandBackMinor) and the MCP answer (cashToHandBack) say how much to hand the customer. A table's bill is refunded from the table instead, so the bill's own record of refunds stays right; these routes refuse it and say so.
Order Fulfillment¶
- Line-level fulfilment state: Each line item tracks its own fulfilment state, so a single order can mix items that need packing with items that need nothing doing to them
- Automatic digital fulfilment: Donations, virtual gift cards and other non-shippable items are fulfilled at submit — no manual pack and dispatch for a physical process that never happens
- Fulfillment Pipelines: Configurable processing steps for different order types
- Order Status Updates: Real-time status updates visible to customers
- Dispatch Notifications: Automated emails when orders are dispatched
- Order Cancellation: Cancel an order before dispatch, refunding or releasing the payment and restoring stock (see Dispatch, Cancellations & Returns)
- Returns Processing: Record returns against dispatched orders, receive and restock them, and refund or reject them (see Dispatch, Cancellations & Returns)
- Dispatch Tracking: Carrier, tracking number and tracking link recorded at dispatch and shown in the dispatch email (see Dispatch, Cancellations & Returns)
Line fulfilment states¶
| State | Meaning |
|---|---|
PENDING |
No fulfilment decision made yet (the default for a basket line, and for any line placed before line-level fulfilment existed) |
AWAITING_FULFILMENT |
Needs physical fulfilment, waiting to be picked up |
PACKING |
Being packed |
FULFILLED |
Dispatched, delivered digitally, or nothing was required |
CANCELLED |
Will not be fulfilled; set on the open lines when the order is cancelled |
The order-level state remains the field everything queries and reports on, but it is now derived from the line states rather than set directly:
- any line
PACKING→ order isPACKING - every line terminal (
FULFILLEDorCANCELLED) → order isDISPATCHED
The roll-up only ever moves an order forwards through SUBMITTED → PACKING → DISPATCHED. On an order split between fulfillers, one of them dispatching their lines leaves the rest merely awaiting fulfilment, which on its own derives as SUBMITTED — without that rule a half-shipped order would drop back and reappear as untouched work.
- otherwise the order stays SUBMITTED
Only fulfilment states are derived this way. Pre-placed and payment states (INITIAL, ITEMS_ADDED, PAYMENT_FAILED, MERGED) stay authoritative on the order itself and are never overwritten from its lines.
Digital and donation orders¶
A product with Shipping required unticked produces a line that needs no fulfilment. At submit, the autoFulfilDigitalLinesProcessor marks every such line FULFILLED and every shippable line AWAITING_FULFILMENT.
An order whose lines are all non-shippable — a donation, say — therefore rolls straight up to DISPATCHED inside the submit pipeline, with no operator action and no dispatch email. A mixed order stays SUBMITTED, and the Pack and Dispatch buttons appear only while physical lines are still outstanding.
Sites that would rather review every order by hand can turn this off with the Auto-fulfil Digital Lines site configuration setting (pipeline-submitOrder-autoFulfilDigital-enabled).
Orders placed before this existed read back as PENDING and behave exactly as they did. A nightly backfill job stamps historical orders with states derived from their order state and rolls them up (see Fulfilment); it is idempotent and can be disabled with badger.fulfilment.backfill-enabled=false.
Customer Communications¶
- Order Confirmation: Immediate confirmation emails with order details
- Dispatch Notifications: Automated emails when orders are dispatched
- Status Updates: Notify customers of important status changes
- Customizable Templates: Email templates that can be tailored to your brand
Technical Implementation¶
The order system is built around the Order domain model and uses:
- A state machine approach for order processing
- Event-driven architecture for order updates
- Asynchronous processing for long-running operations
- Transactional integrity for critical operations
The OrderService provides key functionalities:
- Creating and updating orders
- Processing payments
- Applying promotions and discounts
- Calculating totals, and the VAT in them for a shop whose prices include it (VAT)
Integration Points¶
The order system integrates with: - Inventory System: For stock checks and reservations - Payment Gateway: For secure payment processing - Customer Accounts: For order history and saved information - Shipping Providers: For fulfillment and tracking - VAT: For the VAT in each order when a shop's prices include it (VAT)
Administration¶
Orders can be managed through: - Web-based admin interface with filtering and search - Order processing dashboards - Detailed order views with complete history - Batch operations for order processing
Upcoming Features¶
- Enhanced fraud detection
- Advanced order analytics and reporting
- Improved multi-channel order management
- Subscription order support