Overview
The OMS Service is the platform’s system of record for orders after checkout. Once the cart service places an order and payment is authorised, OMS owns the order for its entire post-purchase life: creation, validation, workflow-driven fulfilment, invoicing, payments, cancellations, returns, replacements/exchanges, and event notification to downstream systems.
It is a multi-tenant service — every order and related record is scoped to an instanceId (a tenant/store/business unit). The instanceId is passed as a query parameter and resolved into an instance context that carries per-tenant configuration properties.
Business Value
| Capability | Business value |
|---|---|
| Single source of truth for orders | Complete, auditable record of every order from capture to closure |
| Rich order-capture validation | Rejects malformed/mispriced orders at the door (P0 math, payment, fulfilment, discount validators) |
| Workflow orchestration (Step Functions) | Coordinates accounts, promotion, payment, inventory, fraud, and notification steps automatically |
| Cancellations & partial cancellations | Customer/CSR/SAP-initiated cancels with a time window and compensation (payment/inventory revert) |
| Returns, replacements & exchanges | Full RMA lifecycle with refund tracking and return shipping labels |
| Invoicing & payments | Per-order invoices and payment records with status lifecycles |
| Domain events | Publishes lifecycle events to EventBridge so inventory, notifications, accounts, and ERP stay in sync |
| Per-tenant configurability | V2 order PATCH lets each instance define allowed statuses and bypass workflow step-enforcement |
Who Uses It
| Consumer | How they use it |
|---|---|
| Cart / checkout service | Creates orders via POST /v1/orders after payment authorisation |
| CSR / admin back-office | Views, patches, cancels, splits orders; manages returns, invoices, payments; completes human workflow tasks |
| Storefront / customer app | Reads order status/history; initiates returns; guest order lookup |
| Downstream services (inventory, payment, accounts, promotion, notification) | Receive EventBridge events and send callbacks that resume Step Function tasks |
| Warehouse / fulfilment | Signals shipment and return-collection via task callbacks / EventBridge (returnCollected) |
| Platform ops | Manage tenant instances and instance attributes; run GDPR export/delete jobs |
Core Features
| # | Feature | Summary |
|---|---|---|
| 1 | Order Creation | Order creation with deep multi-mode math/payment/fulfilment validation |
| 2 | Order Retrieval | Order retrieval, filtering, sort, pagination, guest lookup |
| 3 | Order Update | Order update / status transition (V1 hardcoded enum, V2 instance-configurable) |
| 4 | Full order cancellation | Full order cancellation (SAP/User/Admin) with cancel window and workflow compensation |
| 5 | Partial Cancellation | Partial (per-item) cancellation |
| 6 | Order Notes | Order notes and notification-preference updates |
| 7 | Full Returns | Returns: create, list, lifecycle (accept → refund), labels |
| Partial Returns | Returns: create, list, lifecycle (accept → refund), labels | |
| 8 | Order Summary | Order summary (lightweight aggregate list) |
| 9 | Product/SKU Quantity | Product/SKU quantity counts |
| 10 | Domain-Event | Domain-event resend/replay |
| 11 | Multi-Tenant | Multi-tenant instance & instance-attribute management |
| 12 | Marketplace Connector | Marketplace connector integration (optional) |
| 13 | In-Memory | In-memory mode (no external dependencies) |
Related Resources
- Postman API collection and testing guide
- Feature notes: in-memory mode, async callbacks, observability and audit
- Functional docs: order capture & query, order processing, invoice management
Revision History
2026-08-05 | JP – Created the page and added the content.