The OMS (Order Management System) module handles order processing, fulfillment, and tracking in EverShop.
Overview The OMS module provides:
Order Management - Create, view, and manage ordersOrder Status Tracking - Track order, payment, and shipment statusShipment Management - Create and track shipmentsOrder Activities - Activity log for order changesInvoicing - Generate and manage invoicesOrder Notes - Internal notes and customer comments
Module Structure oms/ ├── api/ # Order API endpoints ├── graphql/ # GraphQL types and resolvers │ ├── types/ │ │ ├── Order/ # Order types │ │ ├── OrderItem/ # Order item types │ │ └── Shipment/ # Shipment types ├── migration/ # Database migrations ├── pages/ # Order management pages ├── services/ # Order services └── bootstrap.js # Module initialization
GraphQL Types Order Type type Order { orderId : Int ! uuid : String ! orderNumber : String ! cartId : Int ! orderDate : String ! currency : String ! customerId : ID customerEmail : String customerFullName : String status : Status ! paymentStatus : PaymentStatus ! shipmentStatus : ShipmentStatus ! items : [ OrderItem ] ! shippingAddress : OrderAddress billingAddress : OrderAddress shippingMethod : String shippingMethodName : String shippingNote : String paymentMethod : String paymentMethodName : String discountAmount : Float coupon : String taxAmount : Float shippingFeeExclTax : Float shippingFeeInclTax : Float subTotal : Float subTotalInclTax : Float totalQty : Int ! totalWeight : Float grandTotal : Float ! activities : [ Activity ] shipments : [ Shipment ] }
Order Status Types type Status { code : String ! badge : String ! progress : String ! name : String ! } type PaymentStatus { code : String ! badge : String ! progress : String ! name : String ! } type ShipmentStatus { code : String ! badge : String ! progress : String ! name : String ! }
Order Lifecycle 1. Order Creation Orders are created when:
Customer completes checkout
Admin creates order manually
Order is imported from external system
// Order is created from cart during checkout const order = await cart . placeOrder ();
2. Order Statuses Orders progress through these statuses:
Pending
Order placed, awaiting payment confirmation
Processing
Payment confirmed, order being prepared
Shipped
Order shipped to customer
Delivered
Order delivered to customer
Complete
Order finalized and closed
Other statuses:
Cancelled - Order cancelled before shipmentOn Hold - Order temporarily on holdRefunded - Payment refunded to customer
3. Payment Status Payment tracking:
Pending - Payment not yet receivedPaid - Payment confirmedPartially Paid - Partial payment receivedRefunded - Payment refundedFailed - Payment failed
4. Shipment Status Shipment tracking:
Unshipped - Not yet shippedPartially Shipped - Some items shippedShipped - All items shippedDelivered - Package delivered
Order Items OrderItem Type type OrderItem { orderItemId : Int ! uuid : String ! orderId : Int ! productId : Int ! productSku : String ! productName : String ! thumbnail : String productWeight : Float qty : Int ! price : Float ! finalPrice : Float ! finalPriceInclTax : Float ! taxPercent : Float taxAmount : Float discountAmount : Float subTotal : Float ! total : Float ! variantGroupId : ID variantOptions : String productCustomOptions : String }
Order items store:
Product information (snapshot at time of order)
Pricing and discounts
Tax calculations
Variant and custom options
Shipment Management Creating Shipments Shipments are created for orders:
// POST /api/orders/:id/shipments await fetch ( `/api/orders/ ${ orderId } /shipments` , { method: 'POST' , headers: { 'Content-Type' : 'application/json' }, body: JSON . stringify ({ items: [ { orderItemId: 1 , qty: 2 }, { orderItemId: 2 , qty: 1 } ], trackingNumber: 'TRACK123456' , carrier: 'UPS' , note: 'Shipment created' }) });
Shipment Type type Shipment { shipmentId : Int ! uuid : String ! shipmentNumber : String ! orderId : Int ! carrier : String trackingNumber : String shippedAt : String deliveredAt : String status : String ! }
Partial Shipments Orders can be shipped in multiple shipments:
Ship available items first
Track each shipment separately
Update order status automatically
Order Activities Activity log tracks all order changes:
type Activity { activityId : Int ! orderId : Int ! comment : String ! customerNotified : Boolean ! createdAt : String ! username : String }
Activities are logged for:
Status changes
Payment updates
Shipment creation
Order notes
Cancellations and refunds
Order Services The OMS module exports these services:
import { updatePaymentStatus , updateShipmentStatus , createShipment , cancelOrder } from '@evershop/evershop/oms/services' ; // Update payment status await updatePaymentStatus ( orderId , 'paid' ); // Update shipment status await updateShipmentStatus ( orderId , 'shipped' ); // Create shipment const shipment = await createShipment ( orderId , { items: [{ orderItemId: 1 , qty: 2 }], trackingNumber: 'TRACK123' , carrier: 'FedEx' }); // Cancel order await cancelOrder ( orderId , 'Customer requested cancellation' );
Database Schema The OMS module defines:
order - Order header dataorder_item - Order line itemsorder_address - Shipping and billing addressesorder_activity - Activity logshipment - Shipment recordsshipment_item - Shipment line items
Order Queries Get Order query { order ( id : "abc123" ) { orderNumber orderDate status { name badge } grandTotal items { productName qty total } shippingAddress { fullName address1 city } shipments { trackingNumber carrier shippedAt } } }
Get Orders (Admin) query { orders ( filters : [{ key : "status" , operation : eq , value : "processing" }]) { items { orderId orderNumber customerFullName grandTotal status { name } } total currentPage } }
Admin Order Management Administrators can:
View all orders with filtering
Update order status
Create shipments
Add order notes
Issue refunds
Cancel orders
Print invoices and packing slips
Email customers
Order Notifications Customers receive email notifications for:
Order confirmation
Payment received
Order shipped
Delivery confirmation
Cancellation or refund
Inventory Updates The OMS module updates inventory:
On order placement - Decrements stockOn cancellation - Returns stockOn refund - Optional stock return
Best Practices Order Numbers : Order numbers are automatically generated and guaranteed to be unique. They can be customized using the order number prefix in settings.
Order Modification : Once an order is placed, avoid modifying order items. Instead, issue refunds and create new orders if changes are needed.
Activity Logging : Always add activity log entries when making manual changes to orders. This creates an audit trail.
Order Reports Generate reports for:
Sales by date range
Top selling products
Revenue by payment method
Order status breakdown
Customer order history
API Endpoints Key OMS API endpoints:
GET /api/orders - List orders (admin)GET /api/orders/:id - Get order detailsPATCH /api/orders/:id - Update orderPOST /api/orders/:id/cancel - Cancel orderPOST /api/orders/:id/shipments - Create shipmentPATCH /api/orders/:id/shipments/:shipmentId - Update shipmentPOST /api/orders/:id/activities - Add activity log
OMS Services API Learn about the OMS services API
Checkout Module How orders are created from carts
Customer Module Customer order history
GraphQL Queries Order GraphQL queries