Orders API

Create, list, update and track distribution orders. Covers the order status flow, line items, delivery assignment and filtering by date, route or retailer.

4 endpoints. Every request needs an API key or a session token — see Authentication. To send one of these calls from the browser, use the interactive reference.

GEThttps://api.spirestock.com/api/v1/orders

List orders with pagination, filtering by status, date range, user, and search query. Status values are integers: 1 (initiated), 2 (forwarded), 3 (approved), 4 (delivered).

Parameters

page (number) — Page number (default: 1)
limit (number) — Items per page (default: 20, max: 100)
status (number) — Filter by status: 1 (initiated), 2 (forwarded), 3 (approved), 4 (delivered)
date_from (string) — Start date (YYYY-MM-DD)
date_to (string) — End date (YYYY-MM-DD)
user_id (number) — Filter orders by a specific user ID
search (string) — Search by order code or user name

Example request

curl "https://api.spirestock.com/api/v1/orders?page=1&limit=20&status=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example response

{
  "response_code": 200,
  "data": [
    {
      "id": 142,
      "order_code": "ORD-2026-0142",
      "order_status": 1,
      "order_date": "2026-05-30",
      "user_id": 42,
      "user_name": "Ravi Kumar",
      "user_type": 2,
      "town_name": "Lucknow",
      "route_name": "Route A",
      "order_total_amount": 1400.00,
      "order_items_count": 3,
      "production_unit_name": "Unit 1",
      "delivery_date": null,
      "createdAt": "2026-05-30T08:15:00Z",
      "updatedAt": "2026-05-30T08:15:00Z"
    }
  ],
  "pagination": {
    "total": 148,
    "page": 1,
    "limit": 20,
    "total_pages": 8
  }
}

POSThttps://api.spirestock.com/api/v1/orders

Create a new order. Items are specified as an array of product variant IDs with quantities.

Request body

user_id (number)required — The customer (retailer/distributor) user ID
items (array)required — Array of { product_variant_id, quantity }
order_date (string) — Order date (YYYY-MM-DD)
delivery_date (string) — Requested delivery date (YYYY-MM-DD)

Example request

curl -X POST https://api.spirestock.com/api/v1/orders \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 42,
    "items": [
      { "product_variant_id": 10, "quantity": 20 },
      { "product_variant_id": 15, "quantity": 10 }
    ],
    "delivery_date": "2026-06-02"
  }'

Example response

{
  "response_code": 201,
  "message": "Order created",
  "data": {
    "id": 149,
    "order_code": "ORD-2026-0149",
    "order_status": 1,
    "user_id": 42,
    "user_name": "Ravi Kumar",
    "order_total_amount": 1110.00,
    "order_items_count": 2,
    "delivery_date": "2026-06-02",
    "delivery_otp": "4821",
    "createdAt": "2026-06-01T10:30:00Z"
  }
}

GEThttps://api.spirestock.com/api/v1/orders/{id}

Retrieve a single order by ID, including items, user details, and delivery info.

Parameters

id (number)required — Order ID (integer)

Example request

curl https://api.spirestock.com/api/v1/orders/142 \
  -H "Authorization: Bearer YOUR_TOKEN"

Example response

{
  "response_code": 200,
  "data": {
    "id": 142,
    "order_code": "ORD-2026-0142",
    "order_status": 3,
    "order_date": "2026-05-30",
    "user_id": 42,
    "user_name": "Ravi Kumar",
    "user_type": 2,
    "town_name": "Lucknow",
    "route_name": "Route A",
    "order_total_amount": 1400.00,
    "order_items_count": 3,
    "production_unit_name": "Unit 1",
    "delivery_date": "2026-05-31",
    "mode_of_payment": "credit",
    "createdAt": "2026-05-30T08:15:00Z",
    "updatedAt": "2026-05-30T09:00:00Z"
  }
}

PATCHhttps://api.spirestock.com/api/v1/orders/{id}/status

Update the status of an order. Status flow: 1 (initiated) → 2 (forwarded) → 3 (approved) → 4 (delivered).

Parameters

id (number)required — Order ID (integer)

Request body

order_status (number)required — New status: 2 (forwarded), 3 (approved), or 4 (delivered)

Example request

curl -X PATCH https://api.spirestock.com/api/v1/orders/142/status \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order_status": 3
  }'

Example response

{
  "response_code": 200,
  "message": "Order status updated",
  "data": {
    "id": 142,
    "order_status": 3,
    "updatedAt": "2026-06-01T06:30:00Z"
  }
}