Order Management
15 API calls in this section.
Confirm Order with Address and Payment
/storefront/orders/confirmCreates and confirms a storefront order from the current cart by attaching the shipping address, selected delivery service, and payment method. Key rules: - Requires cartId, marketId, deliveryServiceId, and paymentMethodTypeId. - Accepts either addressId or an address JSON object with lat/long/country. - The backend re-calculates and persists the quoted delivery fee during order creation, before approval-time delivery creation. - When save_to_address_book is false and address is provided, the address is normalized but not saved; it is embedded in the order as JSON. - For gateway payments, backRef (or back_ref) is required. Authentication: Valid user credentials required.
1curl --request POST "$ONDI_BASE_URL/storefront/orders/confirm" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "cartId": "{{cart_id}}",7 "marketId": "{{market_id}}",8 "deliveryServiceId": "{{delivery_service_id}}",9 "address": {10 "full_address": "Customer Address",11 "lat": 33.3152,12 "long": 44.3661,13 "country": "IQ",14 "contact_info": {15 "phone": "+964700000000",16 "email": "user@example.com"17 }18 },19 "save_to_address_book": false,20 "paymentMethodTypeId": "{{payment_method_id}}",21 "backRef": "https://example.com/payment-return"22}'1{2 "cartId": "{{cart_id}}",3 "marketId": "{{market_id}}",4 "deliveryServiceId": "{{delivery_service_id}}",5 "address": {6 "full_address": "Customer Address",7 "lat": 33.3152,8 "long": 44.3661,9 "country": "IQ",10 "contact_info": {11 "phone": "+964700000000",12 "email": "user@example.com"13 }14 },15 "save_to_address_book": false,16 "paymentMethodTypeId": "{{payment_method_id}}",17 "backRef": "https://example.com/payment-return"18}Request body fields
cartIdExampleExample field from the request body.
marketIdExampleExample field from the request body.
deliveryServiceIdExampleExample field from the request body.
addressExampleExample field from the request body.
address.full_addressExampleExample field from the request body.
address.latExampleExample field from the request body.
address.longExampleExample field from the request body.
address.countryExampleExample field from the request body.
address.contact_infoExampleExample field from the request body.
address.contact_info.phoneExampleExample field from the request body.
address.contact_info.emailExampleExample field from the request body.
save_to_address_bookExampleExample field from the request body.
paymentMethodTypeIdExampleExample field from the request body.
backRefExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for authenticated users (required)
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "paymentType": "COD",4 "order": {5 "id": "order-uuid-123",6 "marketId": "market-uuid-abc",7 "userId": "user-uuid-456",8 "status": "pending",9 "paymentStatus": "pending",10 "items": [11 {12 "item_id": "variant-uuid-789",13 "quantity": 2,14 "price": 29.99,15 "name": {16 "en": "Blue T-Shirt Large",17 "ar": "تيشيرت أزرق كبير",18 "ku": "کراسی شینی گەورە"19 }20 }21 ],22 "totalPrice": 59.98,23 "paymentMethod": "cod",24 "shippingAddress": {25 "id": "address-uuid-456",26 "street": "123 Main Street",27 "city": "New York",28 "state": "NY",29 "country": "USA",30 "zipCode": "10001",31 "phone": "+1234567890"32 },33 "createdAt": "2024-01-15T10:30:00Z",34 "updatedAt": "2024-01-15T10:35:00Z"35 },36 "message": "Order confirmed successfully - payment will be collected on delivery",37 "instructions": "Please have exact cash ready when the order is delivered"38}1{2 "success": true,3 "paymentType": "WALLET",4 "order": {5 "id": "order-uuid-123",6 "marketId": "market-uuid-abc",7 "userId": "user-uuid-456",8 "status": "approved",9 "paymentStatus": "paid",10 "items": [11 {12 "item_id": "variant-uuid-789",13 "quantity": 1,14 "price": 149.99,15 "name": {16 "en": "Wireless Headphones"17 }18 }19 ],20 "totalPrice": 149.99,21 "paymentMethod": "wallet",22 "shippingAddress": {23 "id": "address-uuid-456",24 "street": "456 Oak Avenue",25 "city": "Los Angeles",26 "state": "CA",27 "country": "USA",28 "zipCode": "90210"29 },30 "createdAt": "2024-01-15T10:30:00Z",31 "updatedAt": "2024-01-15T10:35:00Z"32 },33 "walletBalance": 850.01,34 "message": "Order confirmed and paid from wallet successfully"35}1{2 "success": true,3 "paymentType": "GATEWAY",4 "order": {5 "id": "order-uuid-123",6 "marketId": "market-uuid-abc",7 "userId": "user-uuid-456",8 "status": "pending",9 "paymentStatus": "pending",10 "items": [11 {12 "item_id": "variant-uuid-789",13 "quantity": 1,14 "price": 999.99,15 "name": {16 "en": "Premium Smartphone"17 }18 }19 ],20 "totalPrice": 999.99,21 "paymentMethod": "gateway",22 "shippingAddress": {23 "id": "address-uuid-456",24 "street": "789 Pine Street",25 "city": "Chicago",26 "state": "IL",27 "country": "USA",28 "zipCode": "60601"29 },30 "createdAt": "2024-01-15T10:30:00Z",31 "updatedAt": "2024-01-15T10:35:00Z"32 },33 "redirectUrl": "https://checkout.razorpay.com/v1/checkout.js",34 "paymentData": {35 "orderId": "rzp_order_AbCdEfGhIjKlMn",36 "amount": 999.99,37 "currency": "USD",38 "keyId": "rzp_test_1234567890",39 "checkoutUrl": "{\"key\":\"rzp_test_1234567890\",\"amount\":99999,\"currency\":\"USD\",\"name\":\"Ondi Store\",\"description\":\"Payment for order order-uuid-123\",\"order_id\":\"rzp_order_AbCdEfGhIjKlMn\"}"40 },41 "message": "Please proceed to payment gateway to complete the order"42}1{2 "success": false,3 "message": "Order not found or does not belong to user"4}1{2 "success": false,3 "message": "Order cannot be modified - only pending orders can be confirmed"4}1{2 "success": false,3 "message": "Shipping address not found or does not belong to user"4}1{2 "success": false,3 "message": "Insufficient balance. Available: 50.00 USD",4 "error": "Insufficient wallet balance"5}1{2 "success": false,3 "message": "Missing required fields",4 "required": [5 "cartId",6 "marketId",7 "deliveryServiceId",8 "addressId_or_address",9 "paymentMethodTypeId"10 ]11}Get Order Payment Status
/storefront/orders/{{order_id}}/payment-statusRetrieves order details with current payment status and transaction information. Only returns orders belonging to the authenticated user. Authentication: - Required: Valid user authentication Path Parameters: - order_id (required): UUID of the order to check Features: - Real-time order and payment status - Complete order details including items and shipping - Payment transaction history - Market information - User access control (own orders only) Order Statuses: - pending: Order created but payment not completed - approved: Payment completed, ready for processing - shipped: Order has been shipped - delivered: Order delivered to customer - cancelled: Order cancelled or payment failed Payment Statuses: - pending: Payment not yet completed - paid: Payment successfully completed - failed: Payment failed or was rejected Use Cases: - Check payment completion after gateway redirect - Order status tracking for customers - Payment confirmation pages - Customer support queries - Real-time order updates
1curl --request GET "$ONDI_BASE_URL/storefront/orders/{{order_id}}/payment-status" \2 --header "Authorization: Bearer {{access_token}}"Path parameters
order_idRequiredVariable used inside the request path.
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for authenticated users (required)
Responses
1{2 "success": true,3 "order": {4 "id": "order-uuid-123",5 "status": "approved",6 "paymentStatus": "paid",7 "totalPrice": 299.99,8 "paymentMethod": "gateway",9 "items": [10 {11 "item_id": "variant-uuid-789",12 "quantity": 2,13 "price": 149.99,14 "name": {15 "en": "Premium Wireless Mouse",16 "ar": "فأرة لاسلكية متميزة",17 "ku": "مشکی بێتەل باش"18 },19 "variant": {20 "color": "Black",21 "size": "Standard"22 }23 }24 ],25 "shippingAddress": {26 "id": "address-uuid-456",27 "street": "123 Main Street",28 "city": "New York",29 "state": "NY",30 "country": "USA",31 "zipCode": "10001",32 "phone": "+1234567890",33 "firstName": "John",34 "lastName": "Doe"35 },36 "createdAt": "2024-01-15T10:30:00Z",37 "updatedAt": "2024-01-15T10:45:00Z",38 "market": {39 "name": "TechMart Electronics",40 "settings": {41 "currency": "USD",42 "deliveryFee": 5.9943 }44 },45 "payments": [46 {47 "id": "payment-uuid-789",48 "status": "SUCCESS",49 "payment_method": "Credit/Debit Card",50 "amount": 299.99,51 "gateway_transaction_id": "rzp_pay_AbCdEfGhIjKlMn",52 "created_at": "2024-01-15T10:30:00Z",53 "processed_at": "2024-01-15T10:32:15Z"54 }55 ]56 }57}1{2 "success": true,3 "order": {4 "id": "order-uuid-456",5 "status": "pending",6 "paymentStatus": "pending",7 "totalPrice": 79.99,8 "paymentMethod": "cod",9 "items": [10 {11 "item_id": "variant-uuid-123",12 "quantity": 1,13 "price": 79.99,14 "name": {15 "en": "Cotton T-Shirt",16 "ar": "تيشيرت قطني",17 "ku": "کراسی لۆکە"18 }19 }20 ],21 "shippingAddress": {22 "street": "456 Oak Avenue",23 "city": "Los Angeles",24 "state": "CA",25 "country": "USA",26 "zipCode": "90210"27 },28 "createdAt": "2024-01-15T09:30:00Z",29 "updatedAt": "2024-01-15T09:35:00Z",30 "market": {31 "name": "Fashion Store",32 "settings": {33 "currency": "USD"34 }35 },36 "payments": []37 }38}1{2 "success": true,3 "order": {4 "id": "order-uuid-789",5 "status": "approved",6 "paymentStatus": "paid",7 "totalPrice": 199.99,8 "paymentMethod": "wallet",9 "items": [10 {11 "item_id": "variant-uuid-999",12 "quantity": 1,13 "price": 199.99,14 "name": {15 "en": "Bluetooth Speaker"16 }17 }18 ],19 "shippingAddress": {20 "street": "789 Pine Street",21 "city": "Chicago",22 "state": "IL",23 "country": "USA",24 "zipCode": "60601"25 },26 "createdAt": "2024-01-15T11:30:00Z",27 "updatedAt": "2024-01-15T11:35:00Z",28 "market": {29 "name": "Electronics Hub",30 "settings": {31 "currency": "USD"32 }33 },34 "payments": [35 {36 "id": "payment-uuid-999",37 "status": "SUCCESS",38 "payment_method": "Digital Wallet",39 "amount": 199.99,40 "gateway_transaction_id": "wallet_order-uuid-789_1705320900000",41 "created_at": "2024-01-15T11:30:00Z",42 "processed_at": "2024-01-15T11:30:05Z"43 }44 ]45 }46}1{2 "success": false,3 "message": "Order not found or does not belong to user"4}1{2 "success": false,3 "message": "Authentication required"4}List Orders (Admin)
/storefront/orders?page=1&limit=10&status=pending&search=M1000-25-12210047&date_from=2024-01-01&date_to=2024-12-31&min_amount=50&max_amount=1000&column_filters={"status":"awaiting_approval","paymentMethod":"COD","city":"Baghdad","totalItems":{"min":2}}&sort_by=createdAt&sort_order=descRetrieves orders for tenant admin management with pagination, additive top-level filters, advanced column filters, server-side sorting, and market KPI stats. Only accessible by tenant administrators for order oversight. Authentication: - Required: Valid Bearer token with tenant admin permissions Query Parameters: - page (optional): Page number for pagination (default: 1) - limit (optional): Items per page (default: 10, max: 100) - status (optional): Existing exact status filter - search (optional): Existing search by order number or order ID - date_from / date_to (optional): Existing created-at range filters - min_amount / max_amount (optional): Existing final amount range filters - column_filters (optional): JSON string. Supported keys: status, paymentMethod, city, finalAmount, deliveryFee, discountAmount, totalItems, createdAt - sort_by (optional): createdAt, finalAmount, deliveryFee, discountAmount, totalItems, status - sort_order (optional): asc or desc (default desc) Important: - Existing query params remain unchanged. - column_filters are AND-combined with each other and with existing filters. - stats are always global market totals and are never affected by filters, search, sorting, or pagination.
1curl --request GET "$ONDI_BASE_URL/storefront/orders?page=1&limit=10&status=pending&search=M1000-25-12210047&date_from=2024-01-01&date_to=2024-12-31&min_amount=50&max_amount=1000&column_filters={"status":"awaiting_approval","paymentMethod":"COD","city":"Baghdad","totalItems":{"min":2}}&sort_by=createdAt&sort_order=desc" \2 --header "Authorization: Bearer {{access_token}}"Query parameters
pageOptional1
Page number for pagination (default: 1)
limitOptional10
Items per page (default: 10, max: 100)
statusOptionalpending
Filter by order status: pending, confirmed, cancelled, completed
searchOptionalM1000-25-12210047
Search orders by order number or order ID (partial match). Order number format: M{market_code}-{YY}-{MM}{DD}{seq4}
date_fromOptional2024-01-01
Filter orders from this date (YYYY-MM-DD format)
date_toOptional2024-12-31
Filter orders until this date (YYYY-MM-DD format)
min_amountOptional50
Filter orders with minimum total amount
max_amountOptional1000
Filter orders with maximum total amount
column_filtersOptional{"status":"awaiting_approval","paymentMethod":"COD","city":"Baghdad","totalItems":{"min":2}}
Advanced column filters JSON. Supported keys: status, paymentMethod, city, finalAmount, deliveryFee, discountAmount, totalItems, createdAt
sort_byOptionalcreatedAt
Sort field. Allowed: createdAt, finalAmount, deliveryFee, discountAmount, totalItems, status
sort_orderOptionaldesc
Sort order: asc or desc. Defaults to desc
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for tenant admin users (required)
Responses
1{2 "success": true,3 "orders": [4 {5 "id": "order-uuid-1",6 "order_number": "M1000-25-12010001",7 "status": "awaiting_approval",8 "paymentMethod": "COD",9 "paymentStatus": "pending",10 "shippingAddress": {11 "city": "Baghdad"12 },13 "deliveryFee": 5000,14 "discountAmount": 1000,15 "finalAmount": 24000,16 "totalItems": 3,17 "createdAt": "2026-04-23T09:30:00.000Z",18 "updatedAt": "2026-04-23T09:30:00.000Z"19 }20 ],21 "pagination": {22 "page": 1,23 "limit": 10,24 "total": 1284,25 "totalPages": 12926 },27 "stats": {28 "totalOrders": 1284,29 "pendingOrders": 42,30 "outForDelivery": 18,31 "deliveredToday": 15632 }33}Get Order Details
/storefront/orders/:order_idRetrieves complete details for a specific order. Includes all order items, customer information, payment details, and delivery status. Authentication: - Required: Valid Bearer token with tenant admin permissions Path Parameters: - order_id (required): UUID of the order to retrieve Features: - Complete order information - Detailed item breakdown - Customer and shipping details - Payment status and history - Delivery tracking information - Order status timeline Response Data: - Full order details with all items - Customer contact information - Complete shipping address - Payment method and transaction details - Order status history - Estimated and actual delivery dates - Individual item details with pricing Use Cases: - Order detail view in admin panel - Customer service inquiries - Order fulfillment processing - Payment verification - Delivery coordination
1curl --request GET "$ONDI_BASE_URL/storefront/orders/:order_id" \2 --header "Authorization: Bearer {{access_token}}"Path parameters
order_idRequiredorder-uuid-123
UUID of the order to retrieve
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for tenant admin users (required)
Responses
1{2 "success": true,3 "data": {4 "order": {5 "id": "order-uuid-123",6 "order_number": "M1000-25-12010001",7 "user_id": "user-uuid-456",8 "market_id": "market-uuid-abc",9 "status": "confirmed",10 "payment_method": "cod",11 "payment_status": "pending",12 "subtotal": 1999.98,13 "tax_amount": 0,14 "shipping_cost": 15,15 "total_price": 2014.98,16 "currency": "USD",17 "customer_notes": "Please handle with care",18 "created_at": "2023-12-01T10:00:00Z",19 "updated_at": "2023-12-01T16:00:00Z",20 "customer": {21 "id": "user-uuid-456",22 "first_name": "John",23 "last_name": "Doe",24 "email": "john.doe@example.com",25 "phone": "+1234567890",26 "verified_customer": true27 },28 "shipping_address": {29 "title": "Home",30 "address_line1": "123 Main Street",31 "address_line2": "Apt 4B",32 "city": "New York",33 "state": "NY",34 "postal_code": "10001",35 "country": "US",36 "phone": "+1234567890",37 "special_instructions": "Leave at the door"38 },39 "items": [40 {41 "id": "order-item-uuid-1",42 "variant_id": "variant-uuid-123",43 "quantity": 2,44 "unit_price": 999.99,45 "total_price": 1999.98,46 "variant": {47 "color": "Space Gray",48 "storage": "256GB"49 },50 "product_name": {51 "en": "iPhone 15 Pro",52 "ar": "آيفون 15 برو",53 "ku": "ئایفۆن 15 پرۆ"54 },55 "product_images": [56 "https://example.com/iphone15-pro-1.jpg"57 ],58 "warehouse_item": {59 "id": "warehouse-item-uuid-456",60 "sku": "IPH15PRO-SG-256",61 "current_stock": 2362 }63 }64 ],65 "status_history": [66 {67 "status": "pending",68 "timestamp": "2023-12-01T10:00:00Z",69 "note": "Order placed"70 },71 {72 "status": "confirmed",73 "timestamp": "2023-12-01T16:00:00Z",74 "note": "Order confirmed by admin",75 "updated_by": "admin-user-uuid-789"76 }77 ],78 "estimated_delivery": {79 "date": "2023-12-05",80 "time_window": "10:00 AM - 2:00 PM",81 "method": "standard"82 },83 "delivery_assignment": {84 "id": "delivery-uuid-456",85 "driver_name": "Mike Johnson",86 "vehicle_info": "Toyota Camry - ABC123",87 "contact_phone": "+1555123456",88 "tracking_url": "https://tracking.example.com/delivery-uuid-456"89 }90 }91 }92}Approve Order
/storefront/orders/:order_id/approveApproves a pending order and moves it to confirmed status. Triggers inventory reservation and delivery assignment processes. Authentication: - Required: Valid Bearer token with tenant admin permissions Path Parameters: - order_id (required): UUID of the order to approve Request Body (optional): - admin_notes (optional): Internal notes about the approval - estimated_delivery_date (optional): Override estimated delivery date Features: - Order status update to 'confirmed' - Inventory reservation - Delivery assignment integration - Admin action logging - Customer notification triggers Business Rules: - Only pending orders can be approved - Stock availability validation - Payment verification (for wallet payments) - Admin permission verification Response Data: - Updated order with confirmed status - Approval timestamp and admin info - Updated delivery estimates - Inventory reservation confirmation Use Cases: - Order approval workflow - Manual order verification - Fraud prevention processes - Inventory management - Customer service operations
1curl --request PUT "$ONDI_BASE_URL/storefront/orders/:order_id/approve" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "admin_notes": "Order approved and ready for fulfillment",7 "estimated_delivery_date": "2023-12-05"8}'1{2 "admin_notes": "Order approved and ready for fulfillment",3 "estimated_delivery_date": "2023-12-05"4}Path parameters
order_idRequiredorder-uuid-123
UUID of the order to approve
Request body fields
admin_notesExampleExample field from the request body.
estimated_delivery_dateExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for tenant admin users (required)
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "data": {4 "order": {5 "id": "order-uuid-123",6 "order_number": "M1000-25-12010001",7 "status": "confirmed",8 "approved_at": "2023-12-01T18:00:00Z",9 "approved_by": "admin-user-uuid-789",10 "admin_notes": "Order approved and ready for fulfillment",11 "estimated_delivery": {12 "date": "2023-12-05",13 "time_window": "10:00 AM - 2:00 PM"14 },15 "updated_at": "2023-12-01T18:00:00Z"16 },17 "inventory_reserved": true,18 "delivery_assigned": {19 "delivery_id": "delivery-uuid-456",20 "driver_assigned": true,21 "tracking_number": "TRK-2023-001234"22 },23 "message": "Order approved successfully"24 }25}Cancel Order
/storefront/orders/:order_id/cancelCancels an order and handles inventory, payment, and delivery cleanup. Available for orders that haven't been shipped. Authentication: - Required: Valid Bearer token with tenant admin permissions Path Parameters: - order_id (required): UUID of the order to cancel Request Body: - reason (required): Cancellation reason (customer_request, out_of_stock, fraud, other) - admin_notes (optional): Internal notes about the cancellation - refund_required (optional): Whether refund processing is needed Cancellation Reasons: - customer_request: Customer-initiated cancellation - out_of_stock: Inventory unavailable - fraud: Suspected fraudulent order - payment_failed: Payment processing failed - other: Other administrative reasons Features: - Order status update to 'cancelled' - Inventory release/restoration - Payment refund processing (for paid orders) - Delivery cancellation - Customer notification Business Rules: - Cannot cancel shipped or delivered orders - Automatic inventory restoration - Refund processing for wallet payments - Delivery assignment cancellation Response Data: - Updated order with cancelled status - Cancellation details and timestamp - Refund processing status - Inventory restoration confirmation Use Cases: - Customer service cancellations - Inventory management - Fraud prevention - Payment processing issues - Business policy enforcement
1curl --request PUT "$ONDI_BASE_URL/storefront/orders/:order_id/cancel" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "reason": "customer_request",7 "admin_notes": "Customer requested cancellation due to change of mind",8 "refund_required": true9}'1{2 "reason": "customer_request",3 "admin_notes": "Customer requested cancellation due to change of mind",4 "refund_required": true5}Path parameters
order_idRequiredorder-uuid-123
UUID of the order to cancel
Request body fields
reasonExampleExample field from the request body.
admin_notesExampleExample field from the request body.
refund_requiredExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for tenant admin users (required)
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "data": {4 "order": {5 "id": "order-uuid-123",6 "order_number": "M1000-25-12010001",7 "status": "cancelled",8 "cancelled_at": "2023-12-01T19:00:00Z",9 "cancelled_by": "admin-user-uuid-789",10 "cancellation_reason": "customer_request",11 "admin_notes": "Customer requested cancellation due to change of mind",12 "updated_at": "2023-12-01T19:00:00Z"13 },14 "inventory_restored": true,15 "refund_processed": {16 "required": true,17 "amount": 2014.98,18 "status": "processed",19 "transaction_id": "refund-txn-uuid-789"20 },21 "delivery_cancelled": {22 "delivery_id": "delivery-uuid-456",23 "status": "cancelled"24 },25 "message": "Order cancelled successfully"26 }27}Get Customer Order History
/storefront/orders/history?page=1&limit=10&status=Retrieves order history for the authenticated customer with pagination and filtering options. Authentication: - Required: Valid Bearer token for customer identification Query Parameters: - page (optional): Page number for pagination (default: 1) - limit (optional): Items per page (default: 10, max: 50) - status (optional): Filter by order status Features: - Customer-scoped order access - Chronological order listing - Status-based filtering - Simplified order summaries - Delivery tracking information Response Data: - Order summaries with key details - Status and delivery information - Item count and total pricing - Order dates and tracking - Quick access to order details Use Cases: - Customer order history page - Order tracking and status - Reorder functionality - Customer service self-help - Mobile app order management
1curl --request GET "$ONDI_BASE_URL/storefront/orders/history?page=1&limit=10&status=" \2 --header "Authorization: Bearer {{access_token}}"Query parameters
pageOptional1
Page number for pagination (default: 1)
limitOptional10
Items per page (default: 10, max: 50)
statusOptionalFilter by order status (optional)
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for authenticated customers (required)
Responses
1{2 "success": true,3 "data": {4 "orders": [5 {6 "id": "order-uuid-123",7 "order_number": "M1000-25-12010001",8 "status": "delivered",9 "total_price": 2014.98,10 "currency": "USD",11 "items_count": 2,12 "created_at": "2023-11-28T10:00:00Z",13 "delivered_at": "2023-12-01T14:30:00Z",14 "market": {15 "id": "market-uuid-abc",16 "store_name": "TechMart",17 "logo_url": "https://example.com/techmart-logo.png"18 },19 "first_item": {20 "name": {21 "en": "iPhone 15 Pro",22 "ar": "آيفون 15 برو",23 "ku": "ئایفۆن 15 پرۆ"24 },25 "image": "https://example.com/iphone15-pro-1.jpg",26 "quantity": 227 },28 "can_review": true,29 "can_reorder": true30 },31 {32 "id": "order-uuid-456",33 "order_number": "M1000-25-12010002",34 "status": "shipped",35 "total_price": 89.99,36 "currency": "USD",37 "items_count": 1,38 "created_at": "2023-12-01T15:00:00Z",39 "estimated_delivery": "2023-12-03",40 "tracking_number": "TRK-2023-001235",41 "market": {42 "id": "market-uuid-def",43 "store_name": "FashionHub",44 "logo_url": "https://example.com/fashionhub-logo.png"45 },46 "first_item": {47 "name": {48 "en": "Premium Cotton T-Shirt",49 "ar": "قميص قطني ممتاز",50 "ku": "کراسی لۆکسی قوتون"51 },52 "image": "https://example.com/tshirt-1.jpg",53 "quantity": 154 },55 "can_review": false,56 "can_reorder": true57 }58 ],59 "pagination": {60 "page": 1,61 "limit": 10,62 "total": 2,63 "totalPages": 164 }65 }66}Get Customer Order Group Details
/storefront/order-groups/:group_idRetrieves detailed information for a specific order group within a customer's order. This is useful for multi-warehouse fulfillment where an order is split into multiple groups. Authentication: - Required: Valid Bearer token for customer identification Path Parameters: - group_id (required): UUID of the specific order group to retrieve Features: - Customer-scoped access (users can only see their own order groups) - Complete group details with all items - Group-specific status and timeline - Warehouse and delivery information - Financial breakdown per group Multi-Warehouse Context: - Orders can be split into multiple groups when items come from different warehouses - Each group has its own status, delivery timeline, and fulfillment process - Customers can track each group independently - Groups may have different delivery dates and tracking numbers Response Data: - Complete group details with items - Group status and timeline - Warehouse information - Delivery details and tracking - Financial breakdown (prices, fees, discounts) - Group-specific items with quantities and pricing Use Cases: - Multi-warehouse order tracking - Group-specific delivery updates - Partial order fulfillment status - Customer service for split orders - Detailed order breakdown view
1curl --request GET "$ONDI_BASE_URL/storefront/order-groups/:group_id" \2 --header "Authorization: Bearer {{access_token}}"Path parameters
group_idRequiredgroup-uuid-456
UUID of the order group to retrieve
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for authenticated customers (required)
Responses
1{2 "success": true,3 "orderGroup": {4 "id": "group-uuid-456",5 "orderId": "order-uuid-123",6 "warehouseId": "warehouse-uuid-789",7 "deliveryId": "delivery-uuid-321",8 "status": "shipped",9 "statusTimeline": [10 {11 "status": "pending",12 "timestamp": "2023-12-01T10:00:00Z",13 "note": "Group created from order"14 },15 {16 "status": "awaiting_approval",17 "timestamp": "2023-12-01T10:30:00Z",18 "note": "Payment confirmed, awaiting approval"19 },20 {21 "status": "approved",22 "timestamp": "2023-12-01T14:00:00Z",23 "note": "Order group approved by admin"24 },25 {26 "status": "shipped",27 "timestamp": "2023-12-02T09:00:00Z",28 "note": "Items shipped from warehouse"29 }30 ],31 "totalPrice": 1299.98,32 "deliveryFee": 15,33 "discountAmount": 50,34 "finalAmount": 1264.98,35 "items": [36 {37 "id": "order-item-uuid-1",38 "productVariantId": "variant-uuid-123",39 "quantity": 1,40 "unitPrice": 999.99,41 "totalPrice": 999.99,42 "product": {43 "name": {44 "en": "iPhone 15 Pro",45 "ar": "آيفون 15 برو",46 "ku": "ئایفۆن 15 پرۆ"47 },48 "images": [49 "https://example.com/iphone15-pro-1.jpg"50 ]51 },52 "variant": {53 "color": "Space Gray",54 "storage": "256GB",55 "sku": "IPH15PRO-SG-256"56 }57 },58 {59 "id": "order-item-uuid-2",60 "productVariantId": "variant-uuid-456",61 "quantity": 1,62 "unitPrice": 299.99,63 "totalPrice": 299.99,64 "product": {65 "name": {66 "en": "AirPods Pro",67 "ar": "إيربودز برو",68 "ku": "ئێرپۆدز پرۆ"69 },70 "images": [71 "https://example.com/airpods-pro-1.jpg"72 ]73 },74 "variant": {75 "color": "White",76 "sku": "AIRPODS-PRO-WHITE"77 }78 }79 ],80 "warehouse": {81 "id": "warehouse-uuid-789",82 "name": "Central Electronics Warehouse",83 "address": {84 "city": "New York",85 "state": "NY",86 "country": "USA"87 }88 },89 "delivery": {90 "id": "delivery-uuid-321",91 "trackingNumber": "TRK-GRP-456-001",92 "estimatedDelivery": "2023-12-04T15:00:00Z",93 "carrier": "Express Delivery Co",94 "status": "in_transit"95 },96 "createdAt": "2023-12-01T10:00:00Z",97 "updatedAt": "2023-12-02T09:00:00Z"98 }99}1{2 "success": false,3 "message": "Order group not found or does not belong to this order"4}1{2 "success": false,3 "message": "Order not found or does not belong to user"4}1{2 "success": false,3 "message": "Authentication required"4}Get Customer Order Details
/storefront/orders/:order_id/detailsRetrieves detailed order information for the authenticated customer. Only shows orders belonging to the authenticated user. Authentication: - Required: Valid Bearer token for customer identification Path Parameters: - order_id (required): UUID of the order to retrieve Features: - Customer-scoped access (users can only see their own orders) - Complete order details and timeline - Delivery tracking information - Payment status and method - Item details with current availability Response Data: - Full order details with items - Order status timeline - Delivery tracking and estimates - Payment information - Shipping address - Item availability for reordering Use Cases: - Customer order detail page - Order tracking and status updates - Reorder functionality - Customer service self-help - Receipt and invoice display
1curl --request GET "$ONDI_BASE_URL/storefront/orders/:order_id/details" \2 --header "Authorization: Bearer {{access_token}}"Path parameters
order_idRequiredorder-uuid-123
UUID of the order to retrieve
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for authenticated customers (required)
Responses
1{2 "success": true,3 "data": {4 "order": {5 "id": "order-uuid-123",6 "order_number": "M1000-25-12010001",7 "status": "delivered",8 "payment_method": "cod",9 "payment_status": "completed",10 "subtotal": 1999.98,11 "tax_amount": 0,12 "shipping_cost": 15,13 "total_price": 2014.98,14 "currency": "USD",15 "created_at": "2023-11-28T10:00:00Z",16 "delivered_at": "2023-12-01T14:30:00Z",17 "shipping_address": {18 "title": "Home",19 "address_line1": "123 Main Street",20 "city": "New York",21 "state": "NY",22 "postal_code": "10001",23 "country": "US"24 },25 "items": [26 {27 "id": "order-item-uuid-1",28 "variant_id": "variant-uuid-123",29 "quantity": 2,30 "unit_price": 999.99,31 "total_price": 1999.98,32 "variant": {33 "color": "Space Gray",34 "storage": "256GB"35 },36 "product_name": {37 "en": "iPhone 15 Pro",38 "ar": "آيفون 15 برو",39 "ku": "ئایفۆن 15 پرۆ"40 },41 "product_images": [42 "https://example.com/iphone15-pro-1.jpg"43 ],44 "current_availability": {45 "in_stock": true,46 "current_price": 949.99,47 "price_changed": true48 }49 }50 ],51 "status_timeline": [52 {53 "status": "pending",54 "timestamp": "2023-11-28T10:00:00Z",55 "description": "Order placed"56 },57 {58 "status": "confirmed",59 "timestamp": "2023-11-28T16:00:00Z",60 "description": "Order confirmed"61 },62 {63 "status": "shipped",64 "timestamp": "2023-11-30T09:00:00Z",65 "description": "Order shipped"66 },67 {68 "status": "delivered",69 "timestamp": "2023-12-01T14:30:00Z",70 "description": "Order delivered successfully"71 }72 ],73 "delivery_info": {74 "tracking_number": "TRK-2023-001234",75 "driver_name": "Mike Johnson",76 "driver_phone": "+1555123456",77 "delivered_by": "Mike Johnson",78 "delivery_notes": "Left at front door as requested"79 },80 "actions_available": {81 "can_review": true,82 "can_reorder": true,83 "can_return": false,84 "can_cancel": false85 }86 }87 }88}Calculate Delivery Price (from Cart)
/storefront/stores/{{store_id}}/delivery/priceCalculates delivery fee for the authenticated user's current cart in a specific store (market). Path Parameters: - store_id (required): ID of the store/market Request Body: - delivery_service_id (required): Delivery service to price - dropoff.latitude (required) - dropoff.longitude (required) Behavior: - The backend loads the authenticated user's current cart for the store - Inventory is planned across warehouses before pricing - If any warehouse quote fails, the whole request fails with success: false - The response still includes data, and message is taken from the first failed quote error Success Response: - data.market: { id, slug, store_name } - data.allocations: [{ warehouse_id, units }] - data.quotes: [{ warehouse_id, units, success, price, error }] - data.total_fee: number
1curl --request POST "$ONDI_BASE_URL/storefront/stores/{{store_id}}/delivery/price" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "delivery_service_id": "service-uuid",7 "dropoff": {8 "latitude": 36.2,9 "longitude": 4410 }11}'1{2 "delivery_service_id": "service-uuid",3 "dropoff": {4 "latitude": 36.2,5 "longitude": 446 }7}Path parameters
store_idRequiredVariable used inside the request path.
Request body fields
delivery_service_idExampleExample field from the request body.
dropoffExampleExample field from the request body.
dropoff.latitudeExampleExample field from the request body.
dropoff.longitudeExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for authenticated users (required)
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "data": {4 "market": {5 "id": "store-uuid",6 "slug": "my-store",7 "store_name": {8 "en": "My Store"9 }10 },11 "allocations": [12 {13 "warehouse_id": "wh-1",14 "units": 215 }16 ],17 "quotes": [18 {19 "warehouse_id": "wh-1",20 "units": 2,21 "success": true,22 "price": 5.523 }24 ],25 "total_fee": 5.526 }27}1{2 "success": false,3 "message": "Delivery location outside delivery zone",4 "data": {5 "market": {6 "id": "store-uuid",7 "slug": "my-store",8 "store_name": {9 "en": "My Store"10 }11 },12 "allocations": [13 {14 "warehouse_id": "wh-1",15 "units": 116 }17 ],18 "quotes": [19 {20 "warehouse_id": "wh-1",21 "units": 1,22 "success": false,23 "price": null,24 "error": "delivery_location_outside_delivery_zone"25 }26 ],27 "total_fee": 028 }29}1{2 "success": false,3 "message": "unauthorized"4}Approve Order Group (Admin)
/storefront/orders/:order_id/groups/:group_id/approveApproves a specific order group that is in 'awaiting_approval'. Updates inventory reservations for just this group and may trigger delivery creation.
1curl --request PUT "$ONDI_BASE_URL/storefront/orders/:order_id/groups/:group_id/approve" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json"Path parameters
order_idRequiredorder-uuid-123
UUID of the order
group_idRequiredgroup-uuid-456
UUID of the group to approve
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for tenant admin users (required)
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "order": { /* ... */ },4 "group": { "id": "group-uuid-456", "status": "approved" },5 "message": "Order group approved successfully"6}Create Delivery for Order Group (Admin)
/storefront/orders/:order_id/groups/:group_id/deliveryCreates and links a delivery for a specific order group. Use this when market settings have auto-delivery disabled, or when delivery was not created during approval. Notes: - Idempotent: if the group already has a delivery_id, returns success with existing linkage. - Creates internal/external delivery based on tenant delivery configuration.
1curl --request POST "$ONDI_BASE_URL/storefront/orders/:order_id/groups/:group_id/delivery" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json"Path parameters
order_idRequiredorder-uuid-123
UUID of the order
group_idRequiredgroup-uuid-456
UUID of the order group
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for tenant admin users (required)
Content-TypeOptionalapplication/json
Responses
No response example is available for this endpoint yet.
Update Order Group Status (Admin)
/storefront/orders/:order_id/groups/:group_id/statusUpdates a specific order group's status. Allowed values: pending, awaiting_approval, approved, rejected, shipped, in_transit, delivered, failed_delivery, returned, cancelled, refunded.
1curl --request PUT "$ONDI_BASE_URL/storefront/orders/:order_id/groups/:group_id/status" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "status": "shipped"7}'1{2 "status": "shipped"3}Path parameters
order_idRequiredorder-uuid-123
UUID of the order
group_idRequiredgroup-uuid-456
UUID of the order group
Request body fields
statusExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for tenant admin users (required)
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "order": { /* ... */ },4 "group": { "id": "group-uuid-456", "status": "shipped" },5 "message": "Order group status updated"6}1{2 "success": false,3 "message": "Validation failed",4 "errors": [5 {6 "field": "status",7 "message": "Invalid status"8 }9 ]10}Edit Order Group Items (Admin)
/storefront/orders/:order_id/groups/:group_id/itemsAllows a tenant admin to edit the products inside a specific order group. The items array is the complete desired state — whatever is in the array becomes the new set of items for the group: - Items in the array but not in the group → added - Items in the group but not in the array → removed - Items in both → quantity updated if changed Warehouse validation: Every variant must belong to the same warehouse as the group. A variant_warehouse_mismatch error is returned if a variant comes from a different warehouse. Allowed group statuses: pending, awaiting_approval, approved. Editing is blocked once the group is shipped or further. Financial recalculation: Group totals and order totals are automatically recalculated after the edit. Request Body: - items (required): Non-empty array of { variantId: string, quantity: number } — must be positive integers.
1curl --request PUT "$ONDI_BASE_URL/storefront/orders/:order_id/groups/:group_id/items" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "items": [7 {8 "variantId": "variant-uuid-111",9 "quantity": 210 },11 {12 "variantId": "variant-uuid-222",13 "quantity": 114 }15 ]16}'1{2 "items": [3 {4 "variantId": "variant-uuid-111",5 "quantity": 26 },7 {8 "variantId": "variant-uuid-222",9 "quantity": 110 }11 ]12}Path parameters
order_idRequiredorder-uuid-123
UUID of the order
group_idRequiredgroup-uuid-456
UUID of the order group
Request body fields
itemsExampleExample field from the request body.
items.variantIdExampleExample field from the request body.
items.quantityExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for tenant admin users (required)
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "order": {4 "id": "order-uuid-123",5 "status": "awaiting_approval",6 "totalPrice": 1500,7 "finalAmount": 15158 },9 "group": {10 "id": "group-uuid-456",11 "warehouseId": "warehouse-uuid-789",12 "status": "awaiting_approval",13 "totalPrice": 1500,14 "finalAmount": 1515,15 "items": [16 {17 "id": "item-uuid-1",18 "variantId": "variant-uuid-111",19 "quantity": 2,20 "unitPrice": 500,21 "totalPrice": 100022 },23 {24 "id": "item-uuid-2",25 "variantId": "variant-uuid-222",26 "quantity": 1,27 "unitPrice": 500,28 "totalPrice": 50029 }30 ]31 },32 "message": "Order group items updated"33}1{2 "success": false,3 "message": "variant_not_in_group_warehouse",4 "details": {5 "error": "variant_warehouse_mismatch",6 "variantId": "variant-uuid-999"7 }8}1{2 "success": false,3 "message": "order_group_not_editable",4 "details": {5 "status": "shipped"6 }7}1{2 "success": false,3 "message": "order_group_not_found"4}Remove Order Group (Admin)
/storefront/orders/:order_id/groups/:group_idRemoves (cancels) a specific order group from an order. Typical use cases: - Customer calls support to drop one warehouse shipment while keeping the rest - A product set from one warehouse can no longer be fulfilled - Admin/support needs to replace a product with a different variant (remove old group item, edit items to add new) Business rules: - The order must have more than one active group — you cannot remove the last active group. Use the cancel order endpoint instead. - The group must not already be shipped, in_transit, delivered, cancelled, or refunded. - Automatically releases inventory reservations and cancels any linked delivery for the group. - Recalculates order financial totals after removal. No request body required.
1curl --request DELETE "$ONDI_BASE_URL/storefront/orders/:order_id/groups/:group_id" \2 --header "Authorization: Bearer {{access_token}}"Path parameters
order_idRequiredorder-uuid-123
UUID of the order
group_idRequiredgroup-uuid-456
UUID of the order group to remove
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for tenant admin users (required)
Responses
1{2 "success": true,3 "order": {4 "id": "order-uuid-123",5 "status": "awaiting_approval",6 "totalPrice": 500,7 "finalAmount": 5158 },9 "group": {10 "id": "group-uuid-456",11 "status": "cancelled"12 },13 "message": "order_group_removed_successfully"14}1{2 "success": false,3 "message": "cannot_remove_last_order_group",4 "details": "Use cancel order to cancel the entire order instead"5}1{2 "success": false,3 "message": "order_group_cannot_be_removed",4 "details": {5 "status": "shipped"6 }7}1{2 "success": false,3 "message": "order_group_not_found"4}