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.

6 endpointsBase URL https://api.spirestock.com/api/v1

Every request needs an API key or a session token. Last updated .

On this page (6)

GEThttps://api.spirestock.com/api/v1/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.

Pagedpage and limit (max 100), id as the final sort key. How pagination works

Parameters

pagenumber
Page number Default 1.
limitnumber
Items per page (default 20, max 100)
statusnumber
1 initiated, 2 forwarded, 3 approved, 4 delivered
order_datestring
One day, dd/mm/yyyy or YYYY-MM-DD (overrides the range)
date_fromstring
Range start, dd/mm/yyyy or YYYY-MM-DD
date_tostring
Range end (inclusive)
production_unit_idnumber
Plant
route_idnumber
Route
town_idnumber
Town
user_idnumber
Customer
user_sap_idstring
Customer SAP id (exact)
user_typestring
e.g. Distributor
town_namestring
Town name contains
route_namestring
Route name contains
searchstring
Order code, customer name or SAP id contains
scanned_by_driverstring
true/1 or false/0
sort_bystring
order_date (default), order_total_amount, order_code, created_at
sort_orderstring
ASC or DESC (default)
Example request
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
{
  "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
  }
}

GEThttps://api.spirestock.com/api/v1/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

order_datestring
One day
date_fromstring
Range start
date_tostring
Range end
Example request
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
{
  "response_code": 200,
  "data": {
    "initiated": 0,
    "forwarded": 0,
    "approved": 0,
    "delivered": 3,
    "total": 3
  }
}

POSThttps://api.spirestock.com/api/v1/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

user_idnumberrequired
Customer (distributor or retailer) id
itemsarrayrequired
[{ product_variant_id, quantity, packaging_type: "0" crates (default) | "1" packets }]
mode_of_paymentstring
e.g. RTGS, UPI
utr_nostring
Payment reference (max 50)
amount_to_be_paidnumber
Committed amount; defaults to the invoice amount
Example request
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
{
  "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
    }
  }
}

GEThttps://api.spirestock.com/api/v1/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

idnumberrequired
Order id
Example request
curl https://api.spirestock.com/api/v1/orders/339189 \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "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
  }
}

PUThttps://api.spirestock.com/api/v1/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

idnumberrequired
Order id

Request body

itemsarray
Full line list, same shape as POST /orders
mode_of_paymentstring
Header field
amount_to_be_paidnumber
0 or more
utr_nostring
Header field
Example request
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
{
  "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"
  }
}

PATCHhttps://api.spirestock.com/api/v1/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

idnumberrequired
Order id

Request body

statusnumber
2 forward, 3 approve, 4 delivered
actionstring
forward or approve (instead of status)
remarkstring
Shown in the approval trail
Example request
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
{
  "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
  }
}