Skip to main content

Overview

The Orders API provides comprehensive order management functionality including order creation, status updates, and retrieval for both customers and store owners. It supports real-time order tracking, automated notifications, and complete order lifecycle management. Location: convex/customers/orders.ts

Order Lifecycle

1

Pending

Order created, awaiting store confirmation
2

Confirmed

Store has confirmed the order and will start preparing
3

Preparing

Store is actively preparing the order
4

Ready

Order is ready for pickup or delivery
5

Out for Delivery

Order is on the way to customer (delivery only)
6

Delivered

Order has been completed successfully

Create Order

Creates a new order directly with specified items (alternative to cart-based ordering).
customerId
Id<'customers'>
required
Customer ID placing the order
storeId
Id<'stores'>
required
Store ID receiving the order
orderItems
Array<object>
required
Array of items with productId and quantity
deliveryAddress
object
required
Complete delivery address information
deliveryType
'delivery' | 'pickup'
required
Delivery method selection
deliveryFee
number
required
Delivery fee amount
paymentMethod
'cash' | 'card' | 'wallet'
required
Payment method used
notes
string
Optional order notes
estimatedDeliveryTime
number
Estimated delivery time in minutes

Update Order Status

Update order status with optional notes (available to both store owners and customers).
orderId
Id<'orders'>
required
Order ID to update
status
string
required
New order status: pending, confirmed, preparing, ready, out_for_delivery, delivered, cancelled
notes
string
Optional status update notes

Get Order Details

Retrieve detailed information about a specific order.
orderId
Id<'orders'>
required
Order ID to retrieve

Get Customer Orders

Retrieve all orders for a specific customer.
customerId
Id<'customers'>
required
Customer ID
limit
number
Maximum number of orders to return

Get Store Orders

Retrieve orders for a specific store with optional status filtering.
storeId
Id<'stores'>
required
Store ID
status
string
Filter by order status
limit
number
Maximum number of orders to return

Order Management Components

Complete order management interface:

Order Status Flow

Pending

Initial Status: Order placed, awaiting store confirmation
Actions: Store can confirm or cancel

Confirmed

Store Action: Store has accepted the order
Next: Store will start preparing

Preparing

Active Status: Order is being prepared
ETA: Estimated completion time provided

Ready

Completion: Order ready for pickup/delivery
Actions: Dispatch for delivery or notify for pickup

Out for Delivery

Transit: Order is on the way to customer
Tracking: Real-time delivery updates

Delivered

Final Status: Order completed successfully
Actions: Review and rating available

Error Handling

Status Code: 404
Status Code: 400
Status Code: 403
Status Code: 400
Order status updates automatically trigger notifications to relevant parties and update real-time dashboards for both customers and store owners.
Use the order status history to provide customers with detailed tracking information and resolve any delivery disputes.