Orders API

Create, manage, and track wholesale orders.

Endpoints

List Orders

GET /api/v1/orders
Authorization: Bearer {token}

Query Parameters:

Parameter	Type	Description
status	string	Filter by status
wholesaler_id	string	Filter by wholesaler
start_date	date	Orders after this date
end_date	date	Orders before this date

Response:

{
  "data": [
    {
      "id": "order-uuid",
      "order_number": "ORD-2026-001234",
      "status": "pending",
      "wholesaler": {
        "id": "ws-uuid",
        "name": "Green Wholesale Co"
      },
      "retailer": {
        "id": "rt-uuid",
        "name": "Main Street Dispensary"
      },
      "items": [
        {
          "product_id": "prod-uuid",
          "product_name": "Blue Dream 1/8",
          "quantity": 50,
          "unit_price": 25.00,
          "total": 1250.00
        }
      ],
      "subtotal": 1250.00,
      "tax": 0,
      "total": 1250.00,
      "delivery_date": "2026-01-30",
      "created_at": "2026-01-27T10:30:00Z"
    }
  ]
}

Create Order

POST /api/v1/orders
Authorization: Bearer {token}

{
  "wholesaler_id": "ws-uuid",
  "items": [
    {
      "product_id": "prod-uuid",
      "quantity": 50
    }
  ],
  "delivery_date": "2026-01-30",
  "delivery_window": "AM",
  "notes": "Please call before delivery"
}

Get Order

GET /api/v1/orders/{id}

Update Order Status

PATCH /api/v1/orders/{id}/status
Authorization: Bearer {token}

{
  "status": "accepted",
  "notes": "Order confirmed, preparing for shipment"
}

Status Flow:

pending → accepted → preparing → shipped → delivered
                  ↘ cancelled

Cancel Order

POST /api/v1/orders/{id}/cancel
Authorization: Bearer {token}

{
  "reason": "Customer requested cancellation"
}

Order Statuses

Status	Description
pending	Awaiting wholesaler review
accepted	Confirmed by wholesaler
preparing	Being picked/packed
shipped	In transit
delivered	Successfully delivered
cancelled	Order cancelled

Order Items

Add Item to Order

POST /api/v1/orders/{id}/items

Update Item Quantity

PATCH /api/v1/orders/{id}/items/{item_id}

Remove Item

DELETE /api/v1/orders/{id}/items/{item_id}

Webhooks

• order.created - New order placed
• order.updated - Order status changed
• order.shipped - Order dispatched
• order.delivered - Order completed