Complete seller order operations with 3-layer architecture: API Gateway → Seller Order & Fulfillment Orchestrator → Core Microservices
View Postman DocumentationRetrieve paginated list of orders with comprehensive filtering, sorting, and pagination (1 step)
GET /merchant/api/v1/domains/:domain_id/orders
Query Parameters:
page - Page numberlimit - Items per pagestatus - Order status filterpayment_status - Payment filterfulfillment_status - Fulfillment filterfinancial_status - Financial filtercustomer_id - Customer filterdate_from / date_tosort_by / sort_ordersearch - Order number searchstore_id - Store filterGET /orders
Orchestrates 1 service call
POST /api/orders/search
Search orders with filters, pagination, and sorting
Retrieve complete order details including line items, customer, payment, shipping, fulfillments, and timeline (3 steps)
GET /merchant/api/v1/domains/:domain_id/orders/:order_id
GET /orders/:order_id
Orchestrates 3 service calls with caching
GET /api/cache/order/:order_id
Check if order is cached
GET /api/orders/:order_id
Get complete order with line items, customer, payment, shipping, fulfillments, timeline
POST /api/cache/set
Cache complete order (TTL: 600 seconds)
Update order status with workflow validation and notifications (5 steps)
PATCH /merchant/api/v1/domains/:domain_id/orders/:order_id/status
Request Body:
{
"status": "processing", // ENUM: pending, confirmed, processing, shipped, delivered, cancelled, refunded
"note": "Order is being prepared for shipment",
"notify_customer": true
}PATCH /orders/:order_id/status
Orchestrates 5 service calls
Valid Status Transitions (if applicable):
Note: Status can be changed to anything unless changed to delivered/cancelled
GET /api/orders/:order_id
Get current order status
Validate Status Transition
Check if transition is allowed (if applicable)
PATCH /api/orders/:order_id/status
Update order status
POST /api/notifications/send
Send email/SMS about status change
DELETE /api/cache/order/:order_id
Invalidate order cache
Create fulfillment for order items with tracking and partial fulfillment support (5 steps)
POST /merchant/api/v1/domains/:domain_id/orders/:order_id/fulfillments
Self-delivery or non-integrated courier. Manual AWB & delivery person details.
{
"items": [
{ "id": "iid_001", "name": "Alfredo Pasta", "quantity": 2, "selling_price": 100 }
],
"awb": "1Z999AA10123456784",
"tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
"provider_id": null,
"shipping_method": "Self-Delivery",
"notify_customer": true,
"customer": {
"name": "Anjali Patel",
"phone": "+918765432109",
"address": {
"type": "HOME", "name": "John Doe", "phone": "+919999999999",
"line1": "123 Main Street", "line2": "Apartment 4B",
"city": "Mumbai", "state": "Maharashtra", "postal_code": "400001",
"country": "India", "country_code": "IN",
"coordinates": { "latitude": 19.076, "longitude": 72.8777 }
}
},
"delivery_person": { "name": "Rider Rahul", "phone": "+919876543210" },
"pickup_address": {
"type": "OFFICE", "name": "Central Kitchen", "phone": "+919999999999",
"line1": "456 Business Hub", "city": "Mumbai", "state": "Maharashtra",
"postal_code": "400001", "country": "India", "country_code": "IN"
}
}
POST /orders/:order_id/fulfillments
Orchestrates 5 service calls
GET /api/orders/:order_id/items
Validate line items exist and quantities are valid
POST /api/shipments
Create & update shipment/fulfillment with tracking
PUT /api/orders/:order_id
Update order fulfillment status: unfulfilled, partial, fulfilled
POST /api/notifications/send
Send tracking email/SMS
DELETE /api/cache/order/:order_id
Invalidate order cache
Cancel order with optional refund, inventory restoration, and notifications (7 steps)
POST /merchant/api/v1/domains/:domain_id/orders/:order_id/cancel
Request Body:
{
"reason": "customer_request", // ENUM: customer_request, out_of_stock, fraud, other
"cancel_reason_details": "Customer requested cancellation via phone",
"refund": true,
"refund_amount": 66.17, // Optional, defaults to full order amount
"restock": true,
"notify_customer": true
}POST /orders/:order_id/cancel
Orchestrates 7 service calls
Cancellation Reasons:
GET /api/orders/:order_id
Get order details
Validate Cancellation
Check: not cancelled, not shipped/delivered, payment status
PATCH /api/orders/:order_id/status
Set status: "cancelled"
POST /api/inventory/restore
Add items back to inventory
PATCH /api/fulfillments/:fulfillment_id/cancel
Cancel each fulfillment
POST /api/notifications/send
Send cancellation email
DELETE /api/cache/order/:order_id
Invalidate order cache
Bulk update multiple orders - status, tags, or fulfillment (5 steps)
PATCH /merchant/api/v1/domains/:domain_id/orders/bulk
Request Body:
{
"order_ids": ["ord_1", "ord_2", "ord_3"],
"action": "update_status", // ENUM: update_status, add_tags, remove_tags, fulfill
"data": {
"status": "processing",
"notify_customers": false
}
}PATCH /orders/bulk
Orchestrates 5 service calls
Bulk Actions:
Validate Order IDs
Verify all order IDs exist and belong to domain
Apply action to each order
Batch database updates
Invalidate caches
Clear cache for all affected orders
Send bulk notifications
Notify customers about updates
Return bulk operation result
{ "success": true, "updated_count": 3, "failed": [], "updated_orders": ["ord_1", "ord_2", "ord_3"] }
Order CRUD, search, status updates, items
Shipments, fulfillments, tracking
Stock restoration on cancellation
Email and SMS notifications
Order caching and invalidation
Orchestration layer
Order & Fulfillment Module - Seller Orchestra Internal API Mapping | 6 APIs | 26 Total Steps
Last Updated: December 2025