---
title: "Crates & Logistics API — SpireStock REST API"
description: "Track returnable crates across the party, vehicle and plant ledgers: balances, monthly and day-wise summaries, delivery approvals, manual entries and the OTP-verified plant gate flow."
source: https://developers.spirestock.com/api-reference/crates
---

# Crates & Logistics API

Track returnable crates across the party, vehicle and plant ledgers: balances, monthly and day-wise summaries, delivery approvals, manual entries and the OTP-verified plant gate flow.

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 /crates/summary](https://developers.spirestock.com/api-reference/crates#get-crates-summary)
- [GET /crates/ledger](https://developers.spirestock.com/api-reference/crates#get-crates-ledger)
- [GET /crates/crate-summary](https://developers.spirestock.com/api-reference/crates#get-crates-crate-summary)
- [GET /crates/user-crate-summary](https://developers.spirestock.com/api-reference/crates#get-crates-user-crate-summary)
- [GET /crates/approvals](https://developers.spirestock.com/api-reference/crates#get-crates-approvals)
- [POST /crates/manual](https://developers.spirestock.com/api-reference/crates#post-crates-manual)
- [POST /crates/plant/send-otp](https://developers.spirestock.com/api-reference/crates#post-crates-plant-send-otp)
- [GET /crates/monthly-summary](https://developers.spirestock.com/api-reference/crates#get-crates-monthly-summary)
- [GET /crates/distributors](https://developers.spirestock.com/api-reference/crates#get-crates-distributors)

## GET /crates/summary

Current crate balance per party from the party ledger. Crates are tracked in three ledgers (party, transporter/vehicle, plant); normal and jumbo crates are counted separately, and a positive party balance is crates the party holds.

Access: API key `read` scope; staff need Crate Summary (41) or User Crate Summary (42) — list.

**Example request**

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

**Example response**

```json
{
  "response_code": 200,
  "data": [
    {
      "user_id": 41549,
      "first_name": "Sample",
      "last_name": "User",
      "store_name": "Demo Store F",
      "emp_sap_id": "CUST-014",
      "normal_balance": -280,
      "jumbo_balance": 0
    }
  ]
}
```

## GET /crates/ledger

Party-ledger entries, newest first.

Access: API key `read` scope; staff need Crate Summary (41) or User Crate Summary (42) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | number | no | One party |
| `page` | number | no | Default 1 |
| `limit` | number | no | Default 20 |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/crates/ledger?limit=2" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": [
    {
      "id": 5784,
      "organization_id": 6,
      "user_id": 41518,
      "transporter_id": 99,
      "driver_id": 88,
      "driver_name": "Sample User Y",
      "normal_credit": 3,
      "normal_debit": 0,
      "normal_balance": 12,
      "jumbo_credit": 1,
      "jumbo_debit": 0,
      "jumbo_balance": 1,
      "updated_datetime": "2026-10-22T04:26:23.933Z",
      "createdAt": "2024-01-09T09:36:53.000Z",
      "updatedAt": "2024-01-09T09:36:53.000Z"
    }
  ],
  "pagination": {
    "total": 1450,
    "page": 1,
    "limit": 2,
    "total_pages": 725
  }
}
```

## GET /crates/crate-summary

Crate summary grid: per distributor, opening, daily dispatch and receive for each day of the month, month totals and shortage for the month and since starting. routes lists the route filter options.

Access: API key `read` scope; staff need Crate Summary (41) or User Crate Summary (42) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `month` | string | no | Month, YYYY-MM (MM/YYYY also accepted). Default: the current IST month |
| `crate_type` | string | no | normal (default) or jumbo |
| `route_id` | number | no | Route |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/crates/crate-summary?month=2024-06" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": {
    "days": [
      "2024-06-01",
      "2024-06-02"
    ],
    "rows": [
      {
        "sr_no": 1,
        "user_id": 44165,
        "customer_code": "CUST-016",
        "name": "Sample User A",
        "opening": 0,
        "daily": [
          {
            "dispatch": 0,
            "receive": 0
          },
          {
            "dispatch": 0,
            "receive": 0
          }
        ],
        "receive": 0,
        "dispatch": 0,
        "short_for_month": 0,
        "short_since_starting": 0
      },
      {
        "sr_no": 2,
        "user_id": 44844,
        "customer_code": "CUST-017",
        "name": "Sample User U",
        "opening": 0,
        "daily": [
          {
            "dispatch": 0,
            "receive": 0
          },
          {
            "dispatch": 0,
            "receive": 0
          }
        ],
        "receive": 0,
        "dispatch": 0,
        "short_for_month": 0,
        "short_since_starting": 0
      }
    ],
    "totals": {
      "opening": -8327,
      "receive": 0,
      "dispatch": 0,
      "short_for_month": 0,
      "short_since_starting": -8327,
      "daily": [
        {
          "dispatch": 0,
          "receive": 0
        },
        {
          "dispatch": 0,
          "receive": 0
        }
      ]
    },
    "month": {
      "year": 2024,
      "month": 6
    },
    "crate_type": "normal"
  },
  "routes": [
    {
      "id": 95,
      "route": "Route A",
      "route_code": "R0018"
    }
  ]
}
```

## GET /crates/user-crate-summary

One party's month: dispatched from plant, returned to vehicle, deposited in plant, and the differences with vehicle and party, per day.

Access: API key `read` scope; staff need Crate Summary (41) or User Crate Summary (42) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `month` | string | no | Month, YYYY-MM (MM/YYYY also accepted). Default: the current IST month |
| `user_id` | number | yes | Party id |
| `crate_type` | string | no | normal or jumbo |
| `include_legacy` | string | no | "1" adds legacy-formula columns |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/crates/user-crate-summary?month=2024-06&user_id=44663" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": {
    "user": {
      "id": 44663,
      "first_name": "Sample",
      "middle_name": "",
      "last_name": "User",
      "store_name": "Demo Store E",
      "emp_sap_id": "CUST-011",
      "name": "Sample User AJ"
    },
    "opening": 0,
    "rows": [
      {
        "sr_no": 1,
        "date": "01/06/2024",
        "day": "2024-06-01",
        "dispatched_from_plant": 0,
        "return_to_vehicle": 0,
        "deposit_in_plant": 0,
        "difference_with_vehicle": 0,
        "difference_with_party": 0
      },
      {
        "sr_no": 2,
        "date": "02/06/2024",
        "day": "2024-06-02",
        "dispatched_from_plant": 0,
        "return_to_vehicle": 0,
        "deposit_in_plant": 0,
        "difference_with_vehicle": 0,
        "difference_with_party": 0
      }
    ],
    "totals": {
      "dispatched_from_plant": 0,
      "return_to_vehicle": 0,
      "deposit_in_plant": 0,
      "difference_with_vehicle": 0,
      "difference_with_party": 0
    },
    "month": {
      "year": 2024,
      "month": 6
    },
    "crate_type": "normal"
  }
}
```

## GET /crates/approvals

Driver-raised delivery and return confirmations. actionable is true for pending requests raised today (IST); only those can be decided with PATCH /crates/approvals/{id} { status: 2 approve | 3 decline }, which also marks the order delivered and posts the ledgers.

Access: API key `read` scope; staff need Approval Pending Report (57) — list.

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

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | 1 pending, 2 approved, 3 declined |
| `user_id` | number | no | Party |
| `date` | string | no | Day, YYYY-MM-DD or DD/MM/YYYY. Default: today in IST |
| `page` | number | no | Default 1 |
| `limit` | number | no | Default 30, max 100 |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/crates/approvals?limit=2" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": [
    {
      "id": 11561,
      "organization_id": 6,
      "order_id": 328333,
      "transporter_id": 103,
      "driver_id": 95,
      "driver_name": "Sample User AC",
      "user_id": 43537,
      "user_name": "Sample User H",
      "delivered_normal": 205,
      "delivered_jumbo": 0,
      "received_normal": 205,
      "received_jumbo": 0,
      "status": 2,
      "updated_datetime": "2024-01-07T18:30:00.000Z",
      "createdAt": "2024-01-09T04:41:28.000Z",
      "updatedAt": "2024-01-09T09:36:53.000Z",
      "vehicle_no": "AB01CD1100",
      "order_code": "ORD0001006",
      "status_label": "Approved",
      "actionable": false
    }
  ],
  "pagination": {
    "total": 2890,
    "page": 1,
    "limit": 2,
    "total_pages": 1445
  }
}
```

## POST /crates/manual

Manual crate entry for a party and day (Dispatch credits, Receive debits the party ledger). The party must have an order that day, and only one dispatch per party per day (409).

Access: API key `write` scope; staff need Crate Summary (41) — add.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | number | yes | Party id |
| `crates_type` | string | yes | Dispatch or Receive |
| `crate_date` | string | yes | YYYY-MM-DD or DD/MM/YYYY |
| `normal` | number | no | Normal crates |
| `jumbo` | number | no | Jumbo crates |

**Example request**

```bash
curl -X POST https://api.spirestock.com/api/v1/crates/manual \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 44663,
    "crates_type": "Dispatch",
    "crate_date": "2024-06-10",
    "normal": 4,
    "jumbo": 0
  }'
```

**Example response**

```json
{
  "response_code": 201,
  "message": "Record has been saved successfully.",
  "data": {
    "id": 5790,
    "organization_id": 6,
    "user_id": 44663,
    "transporter_id": null,
    "driver_id": null,
    "driver_name": null,
    "normal_credit": 4,
    "normal_debit": 0,
    "jumbo_credit": 0,
    "jumbo_debit": 0,
    "normal_balance": 4,
    "jumbo_balance": 0,
    "updated_datetime": "2026-10-22T06:30:00.000Z",
    "updatedAt": "2026-10-22T10:59:06.841Z",
    "createdAt": "2026-10-22T10:59:06.841Z"
  }
}
```

## POST /crates/plant/send-otp

Plant gate, step 1: sends a 4-digit OTP to the vehicle's driver in the driver app. Step 2 is POST /crates/plant/dispatch (with order_id) or /crates/plant/receive, carrying the OTP and crates_list [{ user_id, normal_crate, jumbo_crate }]. The OTP is single-use and replaced by the next one sent.

Access: API key `write` scope; staff need Crate Summary (41) — add.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `vehicle_id` | number | yes | Vehicle id |
| `normal_crates` | number | no | Normal crates |
| `jumbo_crates` | number | no | Jumbo crates |
| `otp_type` | string | no | "0" dispatch (default), "1" receive |

**Example request**

```bash
curl -X POST https://api.spirestock.com/api/v1/crates/plant/send-otp \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicle_id": 103,
    "normal_crates": 120,
    "jumbo_crates": 0,
    "otp_type": "0"
  }'
```

**Example response**

```json
{
  "response_code": 200,
  "message": "OTP sent successfully"
}
```

## GET /crates/monthly-summary

Opening, dispatched, received, shortage and closing crates (normal and jumbo) per active distributor or retailer for one IST month. Sorted by first name, then id.

Access: API key `read` scope; staff need Crate Summary (41) or User Crate Summary (42) — list.

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

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `month` | string | no | YYYY-MM (MM/YYYY and MM-YYYY also accepted). Default: the current IST month |
| `search` | string | no | Case-insensitive contains on the customer's name, store name or SAP id; max 100 characters, % and _ match literally |
| `page` | number | no | Page number; junk or a value below 1 reads as 1 (default 1) |
| `limit` | number | no | Page size, default 50, max 100 (larger values are clamped) (default 50) |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/crates/monthly-summary?month=2024-05&limit=50" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": [
    {
      "user_id": 44165,
      "first_name": "Sample",
      "last_name": "User A",
      "store_name": "Demo Store A",
      "opening_normal": 0,
      "opening_jumbo": 0,
      "dispatch_normal": 0,
      "received_normal": 0,
      "dispatch_jumbo": 0,
      "received_jumbo": 0,
      "shortage_normal": 0,
      "shortage_jumbo": 0,
      "closing_normal": 0,
      "closing_jumbo": 0
    }
  ],
  "month": "2024-05",
  "pagination": {
    "total": 10026,
    "page": 1,
    "limit": 2,
    "total_pages": 5013
  }
}
```

## GET /crates/distributors

Active distributors for the crate screens' picker. Sorted by first name, then id. Cached 60 seconds.

Access: API key `read` scope; staff need Crate Summary (41) or User Crate Summary (42) — list.

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

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `search` | string | no | Case-insensitive contains on first name, last name, store name or SAP id; max 100 characters, % and _ match literally |
| `page` | number | no | Page number; junk or a value below 1 reads as 1 (default 1) |
| `limit` | number | no | Page size, default 50, max 100 (larger values are clamped) (default 50) |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/crates/distributors?search=demo" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": [
    {
      "id": 44165,
      "first_name": "Sample",
      "middle_name": "",
      "last_name": "User A",
      "store_name": "Demo Store A",
      "emp_sap_id": "EMP-001",
      "name": "Sample User A"
    }
  ],
  "pagination": {
    "total": 112,
    "page": 1,
    "limit": 2,
    "total_pages": 56
  }
}
```
