---
title: "Orders API — SpireStock REST API"
description: "Create, list, update and track distribution orders. Covers the order status flow, line items, delivery assignment and filtering by date, route or retailer."
source: https://developers.spirestock.com/api-reference/orders
---

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

Base URL: `https://api.spirestock.com/api/v1`. Every request needs an API key (`X-API-Key`) or a session token (`Authorization: Bearer`); see https://developers.spirestock.com/api-reference/auth.

## Endpoints

- [GET /orders](https://developers.spirestock.com/api-reference/orders#get-orders)
- [GET /orders/summary](https://developers.spirestock.com/api-reference/orders#get-orders-summary)
- [POST /orders](https://developers.spirestock.com/api-reference/orders#post-orders)
- [GET /orders/{id}](https://developers.spirestock.com/api-reference/orders#get-orders-id)
- [PUT /orders/{id}](https://developers.spirestock.com/api-reference/orders#put-orders-id)
- [PATCH /orders/{id}/status](https://developers.spirestock.com/api-reference/orders#patch-orders-id-status)

## GET /orders

List orders with the order filters. Each row carries flat_incentive, bulkpack_incentive and invoice_amount (order total minus incentives). Dates are calendar days in the API server's local time zone (production runs in IST); with no usable date the list defaults to today. Staff only see orders of their own plants.

Access: API key `read` scope; staff need Orders (8) — list.

Paged (page and limit): see https://developers.spirestock.com/api-reference#pagination.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | number | no | Page number (default 1) |
| `limit` | number | no | Items per page (default 20, max 100) (default 20) |
| `status` | number | no | 1 initiated, 2 forwarded, 3 approved, 4 delivered |
| `order_date` | string | no | One day, dd/mm/yyyy or YYYY-MM-DD (overrides the range) |
| `date_from` | string | no | Range start, dd/mm/yyyy or YYYY-MM-DD |
| `date_to` | string | no | Range end (inclusive) |
| `production_unit_id` | number | no | Plant |
| `route_id` | number | no | Route |
| `town_id` | number | no | Town |
| `user_id` | number | no | Customer |
| `user_sap_id` | string | no | Customer SAP id (exact) |
| `user_type` | string | no | e.g. Distributor |
| `town_name` | string | no | Town name contains |
| `route_name` | string | no | Route name contains |
| `search` | string | no | Order code, customer name or SAP id contains |
| `scanned_by_driver` | string | no | true/1 or false/0 |
| `sort_by` | string | no | order_date (default), order_total_amount, order_code, created_at |
| `sort_order` | string | no | ASC or DESC (default) |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/orders?order_date=10/06/2024&production_unit_id=17&status=3&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": [
    {
      "id": 339254,
      "organization_id": 6,
      "order_code": "ORD0001008",
      "user_id": 44658,
      "user_sap_id": "CUST-003",
      "user_name": "Sample User AQ",
      "user_type": "Distributor",
      "town_id": 436,
      "town_name": "Town G",
      "route_id": 78,
      "route_name": "Route H",
      "transporter_name": "",
      "transporter_details": "Driver Name: Sample Driver",
      "vehicle_no": "AB01CD1014",
      "utr_no": null,
      "order_date": "2024-06-10T13:26:11.000Z",
      "order_status": 3,
      "order_shift_id": 10,
      "order_shift_name": "Morning",
      "order_scheme_id": null,
      "order_total_amount": 7707.6,
      "order_items_count": 4,
      "mode_of_payment": "UPI",
      "amount_to_be_paid": 7707,
      "revised_amount": null,
      "outstanding_amount": 0,
      "production_unit_id": 17,
      "production_unit_name": "North Plant",
      "indent_status": 1,
      "dispatch_order_status": 0,
      "delivery_date": null,
      "delivery_proof_name": null,
      "delivery_proof_phone": null,
      "delivery_proof_relation": null,
      "delivery_proof_condition": null,
      "delivery_proof_note": null,
      "delivery_proof_signature": null,
      "delivery_proof_photo": null,
      "delivery_proof_recorded_at": null,
      "tcs_value": null,
      "qr_data": null,
      "qr_code_url": null,
      "scanned_by_driver": false,
      "source": "imported",
      "sales_user_id": null,
      "client_sync_id": null,
      "updated_date": "2024-06-10T13:26:11.000Z",
      "createdAt": "2024-06-10T13:26:12.000Z",
      "updatedAt": "2024-06-11T11:26:10.000Z",
      "flat_incentive": 0,
      "bulkpack_incentive": 0,
      "invoice_amount": 7707.6
    }
  ],
  "pagination": {
    "total": 73,
    "page": 1,
    "limit": 1,
    "total_pages": 73
  }
}
```

## GET /orders/summary

Order counts per status for a day or range (same date parameters as GET /orders).

Access: API key `read` scope; staff need Orders (8) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `order_date` | string | no | One day |
| `date_from` | string | no | Range start |
| `date_to` | string | no | Range end |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/orders/summary?date_from=2024-06-01&date_to=2024-06-10" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": {
    "initiated": 0,
    "forwarded": 0,
    "approved": 0,
    "delivered": 3,
    "total": 3
  }
}
```

## POST /orders

Create an order. Rates, amounts and schemes are always computed on the server from the customer's price list, area and assigned schemes; client-sent rates are ignored (preview first with POST /orders/calculate-schemes). One order per customer per day, within the order cut-off. The approval chain starts on creation. Fires order.created.

Access: API key `write` scope; staff need Orders (8) — add.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | number | yes | Customer (distributor or retailer) id |
| `items` | array | yes | [{ product_variant_id, quantity, packaging_type: "0" crates (default) \| "1" packets }] |
| `mode_of_payment` | string | no | e.g. RTGS, UPI |
| `utr_no` | string | no | Payment reference (max 50) |
| `amount_to_be_paid` | number | no | Committed amount; defaults to the invoice amount |

**Example request**

```bash
curl -X POST https://api.spirestock.com/api/v1/orders \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 44663,
    "items": [
      {
        "product_variant_id": 446,
        "quantity": 3,
        "packaging_type": "0"
      }
    ],
    "mode_of_payment": "RTGS"
  }'
```

**Example response**

```json
{
  "response_code": 201,
  "message": "New Order(ORD0001010) has been initiated",
  "data": {
    "indent_status": 0,
    "dispatch_order_status": 0,
    "scanned_by_driver": false,
    "id": 339500,
    "organization_id": 6,
    "user_id": 44663,
    "user_sap_id": "CODE-001",
    "user_name": "Sample Name",
    "user_type": "Distributor",
    "route_id": 82,
    "route_name": "Route A",
    "town_id": 464,
    "town_name": "Town A",
    "transporter_name": "",
    "transporter_details": "Driver Name: Sample Driver",
    "vehicle_no": "AB01CD1077",
    "production_unit_id": 17,
    "production_unit_name": "North Plant",
    "outstanding_amount": 0,
    "tcs_value": null,
    "order_code": "ORD0001010",
    "order_date": "2026-10-22T10:59:05.290Z",
    "updated_date": "2026-10-22T10:59:05.290Z",
    "order_status": 1,
    "order_shift_id": 1,
    "order_shift_name": "Morning",
    "mode_of_payment": "RTGS",
    "utr_no": null,
    "amount_to_be_paid": 2160,
    "order_total_amount": 2160,
    "order_items_count": 1,
    "order_scheme_id": null,
    "source": "dashboard",
    "sales_user_id": null,
    "client_sync_id": null,
    "updatedAt": "2026-10-22T10:59:05.411Z",
    "createdAt": "2026-10-22T10:59:05.291Z",
    "revised_amount": null,
    "delivery_date": null,
    "delivery_proof_name": null,
    "delivery_proof_phone": null,
    "delivery_proof_relation": null,
    "delivery_proof_condition": null,
    "delivery_proof_note": null,
    "delivery_proof_signature": null,
    "delivery_proof_photo": null,
    "delivery_proof_recorded_at": null,
    "qr_data": "{"v":1,"type":"order","org":6,"id":339500,"ts":"2026-10-22T10:59:05.316Z","code":"ORD0001010","data":{"date":"2026-10-22T10:59:05.290Z","amount":2160,"status":1}}",
    "qr_code_url": null,
    "schemes": [],
    "totals": {
      "order_total_amount": 2160,
      "total_incentive": 0,
      "invoice_amount": 2160,
      "crate_total": 3,
      "items_count": 1
    }
  }
}
```

## GET /orders/{id}

One order with details[] (lines, each with the schemes on that variant), schemes[] (every applied scheme with a readable description), total_incentive and invoice_amount. Orders in another workspace give 404.

Access: API key `read` scope; staff need Orders (8) — view (without it, only their own records).

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | number | yes | Order id |

**Example request**

```bash
curl https://api.spirestock.com/api/v1/orders/339189 \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": {
    "id": 339189,
    "organization_id": 6,
    "order_code": "ORD0001003",
    "user_id": 44663,
    "user_sap_id": "CUST-011",
    "user_name": "Sample User J",
    "user_type": "Distributor",
    "town_id": 464,
    "town_name": "Town J",
    "route_id": 82,
    "route_name": "Route E",
    "transporter_name": "",
    "transporter_details": "Driver Name: Sample Driver",
    "vehicle_no": "AB01CD1063",
    "utr_no": "UTR000000001",
    "order_date": "2024-06-10T08:05:17.000Z",
    "order_status": 3,
    "order_shift_id": 10,
    "order_shift_name": "Morning",
    "order_scheme_id": null,
    "order_total_amount": 27820,
    "order_items_count": 5,
    "mode_of_payment": "UPI",
    "amount_to_be_paid": 27820,
    "revised_amount": null,
    "outstanding_amount": 0,
    "production_unit_id": 17,
    "production_unit_name": "North Plant",
    "indent_status": 1,
    "dispatch_order_status": 0,
    "delivery_date": null,
    "delivery_proof_name": null,
    "delivery_proof_phone": null,
    "delivery_proof_relation": null,
    "delivery_proof_condition": null,
    "delivery_proof_note": null,
    "delivery_proof_signature": null,
    "delivery_proof_photo": null,
    "delivery_proof_recorded_at": null,
    "tcs_value": null,
    "qr_data": null,
    "qr_code_url": null,
    "scanned_by_driver": false,
    "source": "imported",
    "sales_user_id": null,
    "client_sync_id": null,
    "updated_date": "2024-06-10T08:05:17.000Z",
    "createdAt": "2024-06-10T08:05:18.000Z",
    "updatedAt": "2024-06-10T10:50:13.000Z",
    "details": [
      {
        "id": 1573954,
        "organization_id": 6,
        "order_id": 339189,
        "product_id": 191,
        "product_name": "Toned Milk",
        "product_variant_id": 446,
        "product_variant_name": "Gold Milk 500ML",
        "product_variant_size": "0.5",
        "product_no_of_pouch": 24,
        "product_container_size": "12.00 L/CRATE",
        "product_container_type": "CRATE",
        "product_packaging_type_name": "PCS",
        "quantity": 3,
        "rate": 720,
        "amount": 2160,
        "quantity_in_pouch": 72,
        "quantity_in_ltr": 36,
        "packaging_type": "0",
        "is_allow": 0,
        "tally_export_type": 0,
        "order_date": "2024-06-10T08:05:17.000Z",
        "gst": null,
        "createdAt": "2024-06-10T08:05:18.000Z",
        "updatedAt": "2024-06-10T08:05:18.000Z",
        "schemes": [
          {
            "id": 34243,
            "organization_id": 6,
            "order_id": 339189,
            "scheme_id": 21,
            "user_id": 44663,
            "scheme_type": "free",
            "variant_id": 446,
            "on_order_of": 3,
            "free_variant_id": 456,
            "free_variant_container_type": null,
            "free_variant_packaging_type": "PCS",
            "free_variant_container_size": "12.00 L/CRATE",
            "container_quantity": 0,
            "pouch_quantity": 3,
            "quantity_in_ltr": "1.50",
            "incentive_amount": null,
            "unit_id": null,
            "unit_name": null,
            "product_id": 193,
            "product_class_id": "42",
            "createdAt": "2024-06-10T08:05:18.000Z",
            "updatedAt": "2024-06-10T08:05:18.000Z",
            "scheme_name": "SKU-001 Milk 500 ml",
            "variant_name": "SKU-001 Milk 500 ml",
            "free_variant_name": "Toned Milk 500ML",
            "description": "Free Toned Milk 500ML- 3 free PCS."
          }
        ]
      }
    ],
    "schemes": [
      {
        "id": 34243,
        "organization_id": 6,
        "order_id": 339189,
        "scheme_id": 21,
        "user_id": 44663,
        "scheme_type": "free",
        "variant_id": 446,
        "on_order_of": 3,
        "free_variant_id": 456,
        "free_variant_container_type": null,
        "free_variant_packaging_type": "PCS",
        "free_variant_container_size": "12.00 L/CRATE",
        "container_quantity": 0,
        "pouch_quantity": 3,
        "quantity_in_ltr": "1.50",
        "incentive_amount": null,
        "unit_id": null,
        "unit_name": null,
        "product_id": 193,
        "product_class_id": "42",
        "createdAt": "2024-06-10T08:05:18.000Z",
        "updatedAt": "2024-06-10T08:05:18.000Z",
        "scheme_name": "Route F",
        "variant_name": "Gold Milk 500ML",
        "free_variant_name": "Toned Milk 500ML",
        "description": "Free Toned Milk 500ML- 3 free PCS."
      }
    ],
    "total_incentive": 0,
    "invoice_amount": 27820
  }
}
```

## PUT /orders/{id}

Edit an order. With items[]: the lines are replaced, re-priced and schemes re-applied, the indent flag is cleared and the approval chain restarts (data.approval_reset); allowed until the order is delivered. Without items: header-only edit of mode_of_payment, vehicle_no, transporter_name, driver_name, revised_amount, outstanding_amount, order_date, utr_no and amount_to_be_paid, answered with message "Order updated" and the order (no totals or approval_reset).

Access: API key `write` scope; staff need Orders (8) — edit.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | number | yes | Order id |

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array | no | Full line list, same shape as POST /orders |
| `mode_of_payment` | string | no | Header field |
| `amount_to_be_paid` | number | no | 0 or more |
| `utr_no` | string | no | Header field |

**Example request**

```bash
curl -X PUT https://api.spirestock.com/api/v1/orders/339189 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "product_variant_id": 446,
        "quantity": 4,
        "packaging_type": "0"
      }
    ]
  }'
```

**Example response**

```json
{
  "response_code": 200,
  "message": "Order(ORD0001003) has been updated.",
  "data": {
    "id": 339189,
    "organization_id": 6,
    "order_code": "ORD0001003",
    "user_id": 51903,
    "user_sap_id": "CODE-001",
    "user_name": "Sample Name",
    "user_type": "Distributor",
    "town_id": 464,
    "town_name": "Town A",
    "route_id": 82,
    "route_name": "Route A",
    "transporter_name": "",
    "transporter_details": "Driver Name: Sample Driver",
    "vehicle_no": "AB01CD1077",
    "utr_no": null,
    "order_date": "2026-10-22T10:59:05.290Z",
    "order_status": 1,
    "order_shift_id": 1,
    "order_shift_name": "Morning",
    "order_scheme_id": null,
    "order_total_amount": 2880,
    "order_items_count": 1,
    "mode_of_payment": "RTGS",
    "amount_to_be_paid": 2160,
    "revised_amount": null,
    "outstanding_amount": 0,
    "production_unit_id": 17,
    "production_unit_name": "North Plant",
    "indent_status": 0,
    "dispatch_order_status": 0,
    "delivery_date": null,
    "delivery_proof_name": null,
    "delivery_proof_phone": null,
    "delivery_proof_relation": null,
    "delivery_proof_condition": null,
    "delivery_proof_note": null,
    "delivery_proof_signature": null,
    "delivery_proof_photo": null,
    "delivery_proof_recorded_at": null,
    "tcs_value": null,
    "qr_data": "{"v":1,"type":"order","org":6,"id":339500,"ts":"2026-10-22T10:59:05.316Z","code":"ORD0001010","data":{"date":"2026-10-22T10:59:05.290Z","amount":2160,"status":1}}",
    "qr_code_url": null,
    "scanned_by_driver": false,
    "source": "dashboard",
    "sales_user_id": null,
    "client_sync_id": null,
    "updated_date": "2026-10-22T10:59:06.746Z",
    "createdAt": "2026-10-22T10:59:05.291Z",
    "updatedAt": "2026-10-22T10:59:06.746Z",
    "schemes": [],
    "totals": {
      "order_total_amount": 2880,
      "total_incentive": 0,
      "invoice_amount": 2880,
      "crate_total": 4,
      "items_count": 1
    },
    "approval_reset": "engine"
  }
}
```

## PATCH /orders/{id}/status

Move an order through the workflow: status 2 forwards and 3 approves (same level rules as POST /approvals/order/action); 4 marks it delivered (workspace admins only), answers message "Order status updated to 4" with the order and no workflow block, and fires order.delivered. When other approvers of the same level are still pending the message is "Your approval is recorded; waiting for the other approvers of this level." and workflow.waiting is true. Or send action forward | approve with a remark. Orders cannot be declined.

Access: API key `write` scope; staff need Orders (8) — edit.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | number | yes | Order id |

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | number | no | 2 forward, 3 approve, 4 delivered |
| `action` | string | no | forward or approve (instead of status) |
| `remark` | string | no | Shown in the approval trail |

**Example request**

```bash
curl -X PATCH https://api.spirestock.com/api/v1/orders/339403/status \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": 3
  }'
```

**Example response**

```json
{
  "response_code": 200,
  "message": "Order status has been updated successfully.",
  "data": {
    "id": 339403,
    "organization_id": 6,
    "order_code": "CODE-001",
    "user_id": 51903,
    "user_sap_id": "CODE-001",
    "user_name": "Sample Name",
    "user_type": "Distributor",
    "town_id": 464,
    "town_name": "Town A",
    "route_id": 82,
    "route_name": "Route A",
    "transporter_name": "",
    "transporter_details": "Driver Name: Sample Driver",
    "vehicle_no": "AB01CD1077",
    "utr_no": null,
    "order_date": "2026-10-22T10:59:05.290Z",
    "order_status": 3,
    "order_shift_id": 1,
    "order_shift_name": "Morning",
    "order_scheme_id": null,
    "order_total_amount": 2880,
    "order_items_count": 1,
    "mode_of_payment": "RTGS",
    "amount_to_be_paid": 2160,
    "revised_amount": null,
    "outstanding_amount": 0,
    "production_unit_id": 17,
    "production_unit_name": "North Plant",
    "indent_status": 0,
    "dispatch_order_status": 0,
    "delivery_date": null,
    "delivery_proof_name": null,
    "delivery_proof_phone": null,
    "delivery_proof_relation": null,
    "delivery_proof_condition": null,
    "delivery_proof_note": null,
    "delivery_proof_signature": null,
    "delivery_proof_photo": null,
    "delivery_proof_recorded_at": null,
    "tcs_value": null,
    "qr_data": "{"v":1,"type":"order","org":6,"id":339500,"ts":"2026-10-22T10:59:05.316Z","code":"ORD0001010","data":{"date":"2026-10-22T10:59:05.290Z","amount":2160,"status":1}}",
    "qr_code_url": null,
    "scanned_by_driver": false,
    "source": "dashboard",
    "sales_user_id": null,
    "client_sync_id": null,
    "updated_date": "2026-10-22T10:59:06.775Z",
    "createdAt": "2026-10-22T10:59:05.291Z",
    "updatedAt": "2026-10-22T10:59:06.792Z"
  },
  "workflow": {
    "id": 339403,
    "ok": true,
    "status": 3,
    "status_label": "Approved",
    "waiting": false
  }
}
```
