Order Management

15 API calls in this section.

Confirm Order with Address and Payment

Storefront & Commerce / Order Management

POST/storefront/orders/confirm

Creates 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.

Valid user credentials required.

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for authenticated users (required) JWT token for authenticated users (required) Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
cartId	string	—
marketId	string	—
deliveryServiceId	string	—
address	object	—
address.full_address	string	—
address.lat	number	—
address.long	number	—
address.country	string	—
address.contact_info	object	—
address.contact_info.phone	string	—
address.contact_info.email	string	—
save_to_address_book	boolean	—

Show 2 more body fields

Additional body parameters

Parameter	Type	Description
paymentMethodTypeId	string	—
backRef	string	—

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/storefront/orders/confirm" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "cartId": "{{cart_id}}",6  "marketId": "{{market_id}}",7  "deliveryServiceId": "{{delivery_service_id}}",8  "address": {9    "full_address": "Customer Address",10    "lat": 33.3152,11    "long": 44.3661,12    "country": "IQ",13    "contact_info": {14      "phone": "+964700000000",15      "email": "[email protected]"16    }17  },18  "save_to_address_book": false,19  "paymentMethodTypeId": "{{payment_method_id}}",20  "backRef": "https://example.com/payment-return"21}'

Replace {{placeholders}} with your own values before sending.

Response examples

200 · Success - COD Payment200 · Success - Wallet Payment200 · Success - Gateway Payment404 · Error - Order Not Found400 · Error - Order Cannot Be Modified404 · Error - Address Not Found400 · Error - Insufficient Wallet Balance400 · Error - Missing Required Fields

200OK

Response body

json

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}

Get Order Payment Status

Storefront & Commerce / Order Management

GET/storefront/orders/{{order_id}}/payment-status

Retrieves order details with current payment status and transaction information. Only returns orders belonging to the authenticated user.

• Required: Valid user authentication

• 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

Path parameters

Parameter	Type	Description
order_idRequired	string	Variable used inside the request path. Variable used inside the request path.

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for authenticated users (required) JWT token for authenticated users (required) Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/storefront/orders/${ORDER_ID}/payment-status" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success - Order with Payment Details200 · Success - COD Order200 · Success - Wallet Order404 · Error - Order Not Found401 · Error - Unauthorized

200OK

Response body

json

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}

List Orders (Admin)

Storefront & Commerce / Order Management

GET/storefront/orders

Retrieves 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.

• Required: Valid Bearer token with tenant admin permissions

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.

Query parameters

Parameter	Type	Description
pageOptional	string	Page number for pagination (default: 1) Page number for pagination (default: 1) Example: 1
limitOptional	string	Items per page (default: 10, max: 100) Items per page (default: 10, max: 100) Example: 10
statusOptional	string	Filter by order status: pending, confirmed, cancelled, completed Existing exact status filter Filter by order status: pending, confirmed, cancelled, completed Existing exact status filter Example: pending
searchOptional	string	Search orders by order number or order ID (partial match). Order number format: M{market_code}-{YY}-{MM}{DD}{seq4} Existing search by order number or order ID Search orders by order number or order ID (partial match). Order number format: M{market_code}-{YY}-{MM}{DD}{seq4} Existing search by order number or order ID Example: M1000-25-12210047
date_fromOptional	string	Filter orders from this date (YYYY-MM-DD format) / date_to (optional): Existing created-at range filters Filter orders from this date (YYYY-MM-DD format) / date_to (optional): Existing created-at range filters Example: 2024-01-01
date_to	string	Filter orders until this date (YYYY-MM-DD format) Filter orders until this date (YYYY-MM-DD format) Example: 2024-12-31
min_amountOptional	string	Filter orders with minimum total amount / max_amount (optional): Existing final amount range filters Filter orders with minimum total amount / max_amount (optional): Existing final amount range filters Example: 50
max_amount	string	Filter orders with maximum total amount Filter orders with maximum total amount Example: 1000
column_filtersOptional	string	Advanced column filters JSON. Supported keys: status, paymentMethod, city, finalAmount, deliveryFee, discountAmount, totalItems, createdAt JSON string. Supported keys: status, paymentMethod, city, finalAmount, deliveryFee, discountAmount, totalItems, createdAt Advanced column filters JSON. Supported keys: status, paymentMethod, city, finalAmount, deliveryFee, discountAmount, totalItems, createdAt JSON string. Supported keys: status, paymentMethod, city, finalAmount, deliveryFee, discountAmount, totalItems, createdAt Example: {"status":"awaiting_approval","paymentMethod":"COD","city":"Baghdad","totalItems":{"min":2}}
sort_byOptional	string	Sort field. Allowed: createdAt, finalAmount, deliveryFee, discountAmount, totalItems, status Sort field. Allowed: createdAt, finalAmount, deliveryFee, discountAmount, totalItems, status Example: createdAt
sort_orderOptional	string	Sort order: asc or desc. Defaults to desc asc or desc (default desc) Sort order: asc or desc. Defaults to desc asc or desc (default desc) Example: desc

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for tenant admin users (required) JWT token for tenant admin users (required) Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/storefront/orders?page=1&limit=10&status=pending&search=ord-123&date_from=2024-01-01&date_to=2024-12-31&min_amount=50&max_amount=1000" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200OK

Response body

json

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 & Commerce / Order Management

GET/storefront/orders/:order_id

Retrieves complete details for a specific order. Includes all order items, customer information, payment details, and delivery status.

• Required: Valid Bearer token with tenant admin permissions

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

Path parameters

Parameter	Type	Description
order_idRequired	string	UUID of the order to retrieve UUID of the order to retrieve Example: order-uuid-123

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for tenant admin users (required) JWT token for tenant admin users (required) Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/storefront/orders/${ORDER_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200OK

Response body

json

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": "[email protected]",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 & Commerce / Order Management

PUT/storefront/orders/:order_id/approve

Approves a pending order and moves it to confirmed status. Triggers inventory reservation and delivery assignment processes.

• Required: Valid Bearer token with tenant admin permissions

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

Path parameters

Parameter	Type	Description
order_idRequired	string	UUID of the order to approve UUID of the order to approve Example: order-uuid-123

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for tenant admin users (required) JWT token for tenant admin users (required) Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
admin_notesOptional	string	Internal notes about the approval Internal notes about the approval
estimated_delivery_dateOptional	string	Override estimated delivery date Override estimated delivery date

Staging

Request

curl

1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/storefront/orders/${ORDER_ID}/approve" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "admin_notes": "Order approved and ready for fulfillment",6  "estimated_delivery_date": "2023-12-05"7}'

Response examples

200OK

Response body

json

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 & Commerce / Order Management

PUT/storefront/orders/:order_id/cancel

Cancels an order and handles inventory, payment, and delivery cleanup. Available for orders that haven't been shipped.

• Required: Valid Bearer token with tenant admin permissions

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

Path parameters

Parameter	Type	Description
order_idRequired	string	UUID of the order to cancel UUID of the order to cancel Example: order-uuid-123

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for tenant admin users (required) JWT token for tenant admin users (required) Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
reasonRequired	string	Cancellation reason (customer_request, out_of_stock, fraud, other) Cancellation reason (customer_request, out_of_stock, fraud, other)
admin_notesOptional	string	Internal notes about the cancellation Internal notes about the cancellation
refund_requiredOptional	boolean	Whether refund processing is needed Whether refund processing is needed

Staging

Request

curl

1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/storefront/orders/${ORDER_ID}/cancel" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "reason": "customer_request",6  "admin_notes": "Customer requested cancellation due to change of mind",7  "refund_required": true8}'

Response examples

200OK

Response body

json

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 & Commerce / Order Management

GET/storefront/orders/history

Retrieves order history for the authenticated customer with pagination and filtering options.

• Required: Valid Bearer token for customer identification

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

Query parameters

Parameter	Type	Description
pageOptional	string	Page number for pagination (default: 1) Page number for pagination (default: 1) Example: 1
limitOptional	string	Items per page (default: 10, max: 50) Items per page (default: 10, max: 50) Example: 10
statusOptional	string	Filter by order status (optional) Filter by order status (optional)

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for authenticated customers (required) JWT token for authenticated customers (required) Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/storefront/orders/history?page=1&limit=10&status=" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200OK

Response body

json

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 & Commerce / Order Management

GET/storefront/order-groups/:group_id

Retrieves 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.

• Required: Valid Bearer token for customer identification

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

Path parameters

Parameter	Type	Description
group_idRequired	string	UUID of the order group to retrieve UUID of the specific order group to retrieve UUID of the order group to retrieve UUID of the specific order group to retrieve Example: group-uuid-456

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for authenticated customers (required) JWT token for authenticated customers (required) Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/storefront/order-groups/${GROUP_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success - Order Group Details404 · Error - Order Group Not Found404 · Error - Order Not Found401 · Error - Unauthorized

200OK

Response body

json

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}

Get Customer Order Details

Storefront & Commerce / Order Management

GET/storefront/orders/:order_id/details

Retrieves detailed order information for the authenticated customer. Only shows orders belonging to the authenticated user.

• Required: Valid Bearer token for customer identification

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

Path parameters

Parameter	Type	Description
order_idRequired	string	UUID of the order to retrieve UUID of the order to retrieve Example: order-uuid-123

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for authenticated customers (required) JWT token for authenticated customers (required) Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/storefront/orders/${ORDER_ID}/details" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200OK

Response body

json

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 & Commerce / Order Management

POST/storefront/stores/{{store_id}}/delivery/price

Calculates delivery fee for the authenticated user's current cart in a specific store (market).

• store_id (required): ID of the store/market

• 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 localized from the first failed quote error

• A unit-range failure returns code can_not_use_this_delivery_for_this_unit_size plus calculated/allowed unit fields at the top level and on the failed quote

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

Frontend integration

display message; use code for branching and the numeric range fields to explain why another service or cart adjustment is required.

Path parameters

Parameter	Type	Description
store_idRequired	string	Variable used inside the request path. Variable used inside the request path.

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for authenticated users (required) JWT token for authenticated users (required) Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
delivery_service_id	string	—
dropoff	object	—
dropoff.latitude	number	—
dropoff.longitude	number	—

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/storefront/stores/${STORE_ID}/delivery/price" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "delivery_service_id": "service-uuid",6  "dropoff": {7    "latitude": 36.2,8    "longitude": 449  }10}'

Response examples

200 · Success400 · Pricing Failed400 · Calculated Units Outside Service Range401 · Unauthorized

200OK

Response body

json

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}

Approve Order Group (Admin)

Storefront & Commerce / Order Management

PUT/storefront/orders/:order_id/groups/:group_id/approve

Approves a specific order group that is in 'awaiting_approval'. Updates inventory reservations for just this group and may trigger delivery creation.

Path parameters

Parameter	Type	Description
order_idRequired	string	UUID of the order UUID of the order Example: order-uuid-123
group_idRequired	string	UUID of the group to approve UUID of the group to approve Example: group-uuid-456

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for tenant admin users (required) JWT token for tenant admin users (required) Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Staging

Request

curl

1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/storefront/orders/${ORDER_ID}/groups/${GROUP_ID}/approve" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json"

Response examples

200OK

Response body

text

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 & Commerce / Order Management

POST/storefront/orders/:order_id/groups/:group_id/delivery

Creates 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.

• Internal unit-range failures return code can_not_use_this_delivery_for_this_unit_size, a localized message, and calculated/allowed unit fields.

Frontend integration

display message; use code only for branching. On a unit-range failure, keep the group unlinked and show the numeric mismatch.

Path parameters

Parameter	Type	Description
order_idRequired	string	UUID of the order UUID of the order Example: order-uuid-123
group_idRequired	string	UUID of the order group UUID of the order group Example: group-uuid-456

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for tenant admin users (required) JWT token for tenant admin users (required) Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/storefront/orders/${ORDER_ID}/groups/${GROUP_ID}/delivery" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json"

Response examples

400Bad Request

Response body

json

1{2  "success": false,3  "code": "can_not_use_this_delivery_for_this_unit_size",4  "message": "Your items require 6 units, but this service supports up to 4 units. Choose another service or adjust the package details.",5  "field": "unit_size",6  "calculated_unit_size": 6,7  "allowed_unit_min": 1,8  "allowed_unit_max": 4,9  "violation": "above_maximum",10  "origin": "internal"11}

Update Order Group Status (Admin)

Storefront & Commerce / Order Management

PUT/storefront/orders/:order_id/groups/:group_id/status

Updates a specific order group's status. Allowed values: pending, awaiting_approval, approved, rejected, shipped, in_transit, delivered, failed_delivery, returned, cancelled, refunded.

Path parameters

Parameter	Type	Description
order_idRequired	string	UUID of the order UUID of the order Example: order-uuid-123
group_idRequired	string	UUID of the order group UUID of the order group Example: group-uuid-456

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for tenant admin users (required) JWT token for tenant admin users (required) Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
status	string	—

Staging

Request

curl

1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/storefront/orders/${ORDER_ID}/groups/${GROUP_ID}/status" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "status": "shipped"6}'

Response examples

200 · Success - Group Status Updated400 · Validation Error

200OK

Response body

text

1{2  "success": true,3  "order": { /* ... */ },4  "group": { "id": "group-uuid-456", "status": "shipped" },5  "message": "Order group status updated"6}

Edit Order Group Items (Admin)

Storefront & Commerce / Order Management

PUT/storefront/orders/:order_id/groups/:group_id/items

Allows 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.

Path parameters

Parameter	Type	Description
order_idRequired	string	UUID of the order UUID of the order Example: order-uuid-123
group_idRequired	string	UUID of the order group UUID of the order group Example: group-uuid-456

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for tenant admin users (required) JWT token for tenant admin users (required) Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
itemsRequired	array<object>	Non-empty array of { variantId: string, quantity: number } — must be positive integers. Non-empty array of { variantId: string, quantity: number } — must be positive integers.
items.variantId	string	—
items.quantity	number	—

Staging

Request

curl

1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/storefront/orders/${ORDER_ID}/groups/${GROUP_ID}/items" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "items": [6    {7      "variantId": "variant-uuid-111",8      "quantity": 29    },10    {11      "variantId": "variant-uuid-222",12      "quantity": 113    }14  ]15}'

Response examples

200 · Success - Items Updated400 · Error - Variant from Wrong Warehouse400 · Error - Group Not Editable404 · Error - Order Group Not Found

200OK

Response body

json

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}

Remove Order Group (Admin)

Storefront & Commerce / Order Management

DELETE/storefront/orders/:order_id/groups/:group_id

Removes (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.

Path parameters

Parameter	Type	Description
order_idRequired	string	UUID of the order UUID of the order Example: order-uuid-123
group_idRequired	string	UUID of the order group to remove UUID of the order group to remove Example: group-uuid-456

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for tenant admin users (required) JWT token for tenant admin users (required) Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request DELETE "https://staging-api.ondi.io/functions/v1/storefront/orders/${ORDER_ID}/groups/${GROUP_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success - Group Removed400 · Error - Last Active Group400 · Error - Group Cannot Be Removed404 · Error - Order Group Not Found

200OK

Response body

json

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}