Orders

Prefix: /v1/orders on the Public API. Auth: Customer for every route.

Method	Path	Purpose
POST	/v1/orders	Place the current cart
GET	/v1/orders	List the customer's orders
GET	/v1/orders/:orderId	Order detail
POST	/v1/orders/:orderId/cancel	Cancel

Place order

The server snapshots the cart, delivery selection, and prices. Empty carts fail with CART_EMPTY.

Send the customer JWT. Guests cannot place an order.

Body

Field	Required	Notes
paymentMethod	yes	cod or wallet only
notes	no	Max 256 chars
address	no	Checkout address details (label, block, street, …)
deliverySlot	scheduled delivery	{ templateId, date } where date is YYYY-MM-DD

Example

POST /v1/orders
Content-Type: application/json
Authorization: Bearer <accessToken>

{
  "paymentMethod": "cod",
  "notes": "Call on arrival",
  "address": {
    "label": "Home",
    "block": "4",
    "street": "1",
    "building": "12",
    "phone": "50000000"
  },
  "deliverySlot": {
    "templateId": "665f0c0c0c0c0c0c0c0c0c0e",
    "date": "2026-09-13"
  }
}

results is the full order document (ids, lines, totals in fils, status placed).

Wallet payment fails if the balance is insufficient. Online methods are rejected even if dashboard toggles show them.

List and get

GET /v1/orders is paginated. GET /v1/orders/:orderId returns one order the customer owns.

Cancel

Body

Field	Required	Values
reason	yes	changed_mind, ordered_by_mistake, too_slow, found_elsewhere, other
note	no	Max 256

Cancellation is only allowed while the order is still in a cancellable status (typically before picking completes). Staff may cancel later from the dashboard with a different reason set.

Status values

Status	Customer meaning
placed	Submitted
confirmed	Store accepted; waiting for a picker
picking	Being picked
ready	Packed / ready for driver or pickup
out_for_delivery	On the way
delivered	Done
delivery_failed	Last attempt failed
cancelled	Cancelled

After confirmed, the Picker API and Driver API own the remaining transitions.