---
title: "Reports API — SpireStock REST API"
description: "Pull the dispatch and MIS reports a dairy runs on: indent, daily sale, truck sheet, sales statement, amount to be paid, summary sheet, SKU and distributor contribution, tagging, visits and their filters, HO entry and packing station."
source: https://developers.spirestock.com/api-reference/reports
---

# Reports API

Pull the dispatch and MIS reports a dairy runs on: indent, daily sale, truck sheet, sales statement, amount to be paid, summary sheet, SKU and distributor contribution, tagging, visits and their filters, HO entry and packing station.

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 /reports/filters](https://developers.spirestock.com/api-reference/reports#get-reports-filters)
- [GET /reports/indent](https://developers.spirestock.com/api-reference/reports#get-reports-indent)
- [POST /reports/indent/generate](https://developers.spirestock.com/api-reference/reports#post-reports-indent-generate)
- [GET /reports/daily-sale](https://developers.spirestock.com/api-reference/reports#get-reports-daily-sale)
- [GET /reports/dist-date-wise](https://developers.spirestock.com/api-reference/reports#get-reports-dist-date-wise)
- [GET /reports/trucksheet-dispatch](https://developers.spirestock.com/api-reference/reports#get-reports-trucksheet-dispatch)
- [GET /reports/sales-statement](https://developers.spirestock.com/api-reference/reports#get-reports-sales-statement)
- [GET /reports/amount-to-be-paid](https://developers.spirestock.com/api-reference/reports#get-reports-amount-to-be-paid)
- [GET /reports/summary-sheet](https://developers.spirestock.com/api-reference/reports#get-reports-summary-sheet)
- [GET /reports/summary](https://developers.spirestock.com/api-reference/reports#get-reports-summary)
- [GET /reports/sku-contribution](https://developers.spirestock.com/api-reference/reports#get-reports-sku-contribution)
- [GET /reports/tagging](https://developers.spirestock.com/api-reference/reports#get-reports-tagging)
- [GET /reports/visits](https://developers.spirestock.com/api-reference/reports#get-reports-visits)
- [GET /reports/ho-entry](https://developers.spirestock.com/api-reference/reports#get-reports-ho-entry)
- [GET /reports/packing-station](https://developers.spirestock.com/api-reference/reports#get-reports-packing-station)
- [GET /reports/visits/filter-options](https://developers.spirestock.com/api-reference/reports#get-reports-visits-filter-options)

## GET /reports/filters

Plants, routes, customers and vehicle numbers for the dispatch-report filters, limited to the plants the caller can see for the chosen report.

Access: API key `read` scope; staff need any report sub-module (the /reports/* catch-all) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `report` | string | no | Scope rules: dashboard, indent, contribution, summary (default), trucksheet, dailySale, sales |
| `production_unit_id` | number | no | Plant filter; a plant outside your scope is 403 |

**Example request**

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

**Example response**

```json
{
  "response_code": 200,
  "data": {
    "plants": [
      {
        "id": 18,
        "production_unit_name": "South Plant",
        "production_unit_code": "1300"
      }
    ],
    "routes": [
      {
        "id": 95,
        "route": "Route A",
        "route_code": "R0018",
        "production_unit_id": 17
      }
    ],
    "customers": [
      {
        "id": 41518,
        "store_name": "Demo Store E",
        "emp_sap_id": "CUST-008",
        "name": "Sample User S"
      }
    ],
    "vehicles": [
      "AB01CD1234"
    ]
  }
}
```

## GET /reports/indent

Indent: per-customer crates for one plant and day, milk and other variants with free (scheme) quantities, crate totals, incentives, invoice amount and amount to be paid. rows is empty until the indent is generated; counts and action (generate, regenerate, generated) say where the day stands. milk[] and other[] line up with milk_variants[] and other_variants[].

Access: API key `read` scope; staff need the indent permission of the requested plant (indent access is granted per plant) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `date` | string | no | Day, YYYY-MM-DD only (dd/mm/yyyy is rejected with 400). Default: today in IST |
| `production_unit_id` | number | yes | Plant (production unit) id; see GET /reports/filters |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/reports/indent?date=2024-06-10&production_unit_id=17" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": {
    "date": "2024-06-10",
    "plant": {
      "id": 17,
      "production_unit_name": "North Plant",
      "production_unit_code": "1200"
    },
    "milk_class": "Milk",
    "milk_variants": [
      {
        "id": 508,
        "variant_name": "Toned Milk 1000ML",
        "item_sku_code": "SKU-001",
        "sap_code": "MAT-001",
        "variant_size": "1",
        "no_of_pouch": 10,
        "product_class_id": 42,
        "production_unit_id": 17
      },
      {
        "id": 510,
        "variant_name": "Double Toned Milk 400ML",
        "item_sku_code": "SKU-002",
        "sap_code": "MAT-002",
        "variant_size": "0.4",
        "no_of_pouch": 24,
        "product_class_id": 42,
        "production_unit_id": 17
      }
    ],
    "other_variants": [
      {
        "id": 488,
        "variant_name": "Lassi 180ML",
        "item_sku_code": "SKU-003",
        "sap_code": "MAT-003",
        "variant_size": "0.18",
        "no_of_pouch": 12,
        "product_class_id": 47,
        "production_unit_id": 17
      },
      {
        "id": 501,
        "variant_name": "Khoa 250GM",
        "item_sku_code": "SKU-004",
        "sap_code": "MAT-004",
        "variant_size": "0.25",
        "no_of_pouch": 1,
        "product_class_id": 46,
        "production_unit_id": 17
      }
    ],
    "counts": {
      "total_orders": 73,
      "indented_orders": 73,
      "pending_indent_orders": 0,
      "approved_orders": 73,
      "approved_not_indented": 0,
      "last_indent_at": "2024-06-11T11:26:10.000Z"
    },
    "action": "generated",
    "rows": [
      {
        "user_id": 44216,
        "order_id": 339182,
        "emp_sap_id": "CUST-001",
        "name": "Sample User A",
        "store_name": "Demo Store A",
        "town_name": "Town A",
        "milk": [
          0,
          0
        ],
        "other": [
          0,
          0
        ],
        "free_milk": [
          0,
          0
        ],
        "free_other": [
          0,
          0
        ],
        "total_milk_crates": 59,
        "total_crates": 66,
        "flat_incentive": 0,
        "bulk_incentive": 0,
        "total_discount": 0,
        "order_total_amount": 34531.4,
        "invoice_amount": 34531.4,
        "amount_to_be_paid": 34531,
        "outstanding_amount": 0,
        "security_amount": 0,
        "balance_after_deposit": 0.4000000000014552,
        "balance_security": -0.4000000000014552,
        "mode_of_payment": "RTGS"
      },
      {
        "user_id": 41598,
        "order_id": 339183,
        "emp_sap_id": "CUST-002",
        "name": "Sample User B",
        "store_name": "Demo Store B",
        "town_name": "Town B",
        "milk": [
          0,
          0
        ],
        "other": [
          0,
          0
        ],
        "free_milk": [
          0,
          0
        ],
        "free_other": [
          0,
          0
        ],
        "total_milk_crates": 14,
        "total_crates": 14,
        "flat_incentive": 0,
        "bulk_incentive": 0,
        "total_discount": 0,
        "order_total_amount": 8368.9,
        "invoice_amount": 8368.9,
        "amount_to_be_paid": 2700,
        "outstanding_amount": 0,
        "security_amount": 0,
        "balance_after_deposit": 5668.9,
        "balance_security": -5668.9,
        "mode_of_payment": "UPI"
      }
    ],
    "totals": {
      "milk": [
        138,
        88.5
      ],
      "other": [
        18,
        0
      ],
      "free_milk": [
        0,
        0
      ],
      "free_other": [
        0,
        0
      ],
      "total_milk_crates": 2248.5,
      "total_crates": 2496,
      "total_discount": 0,
      "invoice_amount": 1550166.59,
      "amount_to_be_paid": 1616026,
      "outstanding_amount": 0
    }
  }
}
```

## POST /reports/indent/generate

Generate (or regenerate) the indent: marks every approved order of the plant for that day as indented. Answers 400 with error: true and "No Order Found." when there are no approved orders.

Access: API key `write` scope; staff need the indent permission of the requested plant (indent access is granted per plant) — edit.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `production_unit_id` | number | yes | Plant id |
| `date` | string | no | Day, YYYY-MM-DD only (dd/mm/yyyy is rejected with 400). Default: today in IST |
| `regenerate` | boolean | no | true to regenerate an existing indent |

**Example request**

```bash
curl -X POST https://api.spirestock.com/api/v1/reports/indent/generate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "production_unit_id": 17,
    "date": "2024-06-10"
  }'
```

**Example response**

```json
{
  "response_code": 200,
  "error": false,
  "message": "Indent Report is generating. Please wait...",
  "data": {
    "date": "2024-06-10",
    "production_unit_id": 17,
    "orders_indented": 73,
    "generated_at": "2024-06-11T11:26:10.000Z"
  }
}
```

## GET /reports/daily-sale

Daily sale / demand sheet: milk-class crates per customer and variant over a date range, with per-variant totals. /reports/daily-demand returns the same data.

Access: API key `read` scope; staff need Daily Demand Sheet (51) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `date_from` | string | no | Start day, YYYY-MM-DD only (dd/mm/yyyy is rejected with 400). Aliases from_date, start_date, date. Default: today in IST |
| `date_to` | string | no | End day (inclusive), same format. Aliases to_date, end_date. Default: the start day |
| `production_unit_id` | number | no | Plant filter; a plant outside your scope is 403 |
| `user_id` | number | no | One customer |

**Example request**

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

**Example response**

```json
{
  "response_code": 200,
  "data": {
    "date_from": "2024-06-10",
    "date_to": "2024-06-10",
    "variants": [
      {
        "id": 458,
        "variant_name": "Gold 500ML",
        "item_sku_code": "SKU-005",
        "sap_code": "MAT-005",
        "variant_size": "0.5",
        "no_of_pouch": 24,
        "product_class_id": 42,
        "production_unit_id": 18
      },
      {
        "id": 459,
        "variant_name": "Gold 6 lt",
        "item_sku_code": "SKU-006",
        "sap_code": "MAT-006",
        "variant_size": "6",
        "no_of_pouch": 2,
        "product_class_id": 42,
        "production_unit_id": 18
      }
    ],
    "rows": [
      {
        "user_id": 44216,
        "emp_sap_id": "CUST-001",
        "store_name": "Demo Store C",
        "zone_name": "North Zone",
        "items": [
          0,
          0
        ],
        "total": 59
      },
      {
        "user_id": 41598,
        "emp_sap_id": "CUST-002",
        "store_name": "Demo Store D",
        "zone_name": "North Zone",
        "items": [
          0,
          0
        ],
        "total": 14
      }
    ],
    "totals": [
      0,
      0
    ]
  }
}
```

## GET /reports/dist-date-wise

Distributor-wise date-wise report: one row per customer per order day with every variant's quantity (null where not ordered).

Access: API key `read` scope; staff need Distributorwise Datewise Report (29) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `date_from` | string | no | Start day, YYYY-MM-DD only (dd/mm/yyyy is rejected with 400). Aliases from_date, start_date, date. Default: today in IST |
| `date_to` | string | no | End day (inclusive), same format. Aliases to_date, end_date. Default: the start day |
| `production_unit_id` | number | no | Plant filter; a plant outside your scope is 403 |
| `user_id` | number | no | One customer |

**Example request**

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

**Example response**

```json
{
  "response_code": 200,
  "data": {
    "date_from": "2024-06-01",
    "date_to": "2024-06-10",
    "variants": [
      {
        "id": 458,
        "variant_name": "Gold 500ML",
        "item_sku_code": "SKU-005",
        "sap_code": "MAT-005",
        "variant_size": "0.5",
        "no_of_pouch": 24,
        "product_class_id": 42,
        "production_unit_id": 18
      },
      {
        "id": 459,
        "variant_name": "Gold 6 lt",
        "item_sku_code": "SKU-006",
        "sap_code": "MAT-006",
        "variant_size": "6",
        "no_of_pouch": 2,
        "product_class_id": 42,
        "production_unit_id": 18
      }
    ],
    "rows": [
      {
        "order_day": "2024-06-01",
        "user_id": 44216,
        "user_sap_id": "CUST-001",
        "store_name": "Demo Store C",
        "town_name": "Town A",
        "items": [
          null,
          null
        ]
      },
      {
        "order_day": "2024-06-01",
        "user_id": 41570,
        "user_sap_id": "CUST-007",
        "store_name": "Demo Store D",
        "town_name": "Town H",
        "items": [
          null,
          null
        ]
      }
    ],
    "totals": [
      0,
      0
    ]
  }
}
```

## GET /reports/trucksheet-dispatch

Truck sheet by route: every order on the route with milk, other and free quantities and crates, plus the route's vehicle and driver. GET /reports/truck-sheet is the same report by vehicle_no (mode: "vehicle"). An unknown route returns 200 with empty lists.

Access: API key `read` scope; staff need Truck Sheet Report (30) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `date_from` | string | no | Start day, YYYY-MM-DD only (dd/mm/yyyy is rejected with 400). Aliases from_date, start_date, date. Default: today in IST |
| `date_to` | string | no | End day (inclusive), same format. Aliases to_date, end_date. Default: the start day |
| `production_unit_id` | number | yes | Plant (production unit) id; see GET /reports/filters |
| `route_id` | number | no | Route id (or route_code) |
| `route_code` | string | no | Route code, e.g. R0019 |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/reports/trucksheet-dispatch?date=2024-06-10&production_unit_id=17&route_id=96" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": {
    "date_from": "2024-06-10",
    "date_to": "2024-06-10",
    "mode": "route",
    "route": {
      "id": 96,
      "route": "Route C",
      "route_code": "R0019"
    },
    "vehicle": {
      "vehicle_number": "AB01CD1040",
      "transporter": "",
      "driver_name": "Sample User U"
    },
    "milk_variants": [
      {
        "id": 508,
        "variant_name": "Toned Milk 1000ML",
        "item_sku_code": "SKU-001",
        "sap_code": "MAT-001",
        "variant_size": "1",
        "no_of_pouch": 10,
        "product_class_id": 42,
        "production_unit_id": 17
      },
      {
        "id": 510,
        "variant_name": "Double Toned Milk 400ML",
        "item_sku_code": "SKU-002",
        "sap_code": "MAT-002",
        "variant_size": "0.4",
        "no_of_pouch": 24,
        "product_class_id": 42,
        "production_unit_id": 17
      }
    ],
    "other_variants": [
      {
        "id": 488,
        "variant_name": "Lassi 180ML",
        "item_sku_code": "SKU-003",
        "sap_code": "MAT-003",
        "variant_size": "0.18",
        "no_of_pouch": 12,
        "product_class_id": 47,
        "production_unit_id": 17
      },
      {
        "id": 501,
        "variant_name": "Khoa 250GM",
        "item_sku_code": "SKU-004",
        "sap_code": "MAT-004",
        "variant_size": "0.25",
        "no_of_pouch": 1,
        "product_class_id": 46,
        "production_unit_id": 17
      }
    ],
    "rows": [
      {
        "s_no": 1,
        "order_id": 339233,
        "order_code": "ORD0001001",
        "order_date": "2024-06-10",
        "user_id": 41547,
        "name": "Sample User B",
        "store_name": "Demo Store A",
        "emp_sap_id": "CUST-009",
        "contact_number1": "9876500021",
        "contact_number2": "",
        "milk": [
          0,
          0
        ],
        "other": [
          3,
          0
        ],
        "free_milk": [
          0,
          0
        ],
        "free_other": [
          0,
          0
        ],
        "total_crates": 112.5
      }
    ],
    "totals": {
      "milk": [
        0,
        0
      ],
      "other": [
        3,
        0
      ],
      "free_milk": [
        0,
        0
      ],
      "free_other": [
        0,
        0
      ]
    }
  }
}
```

## GET /reports/sales-statement

Sales statement: per order, opening outstanding, milk and other sale amounts, amount received, closing outstanding and the crate position.

Access: API key `read` scope; staff need Sales Report (45) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `date_from` | string | no | Start day, YYYY-MM-DD only (dd/mm/yyyy is rejected with 400). Aliases from_date, start_date, date. Default: today in IST |
| `date_to` | string | no | End day (inclusive), same format. Aliases to_date, end_date. Default: the start day |
| `production_unit_id` | number | no | Plant filter; a plant outside your scope is 403 |
| `user_id` | number | no | One customer |

**Example request**

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

**Example response**

```json
{
  "response_code": 200,
  "data": {
    "date_from": "2024-06-01",
    "date_to": "2024-06-10",
    "rows": [
      {
        "order_id": 339254,
        "order_date": "2024-06-10",
        "user_id": 44658,
        "user_sap_id": "CUST-003",
        "user_name": "Sample User Q",
        "town_name": "Town G",
        "opening_outstanding": 0,
        "milk_sale_amount": 0,
        "other_sale_amount": 7707.6,
        "total_sale": 7707.6,
        "amount_received": 7707,
        "closing_outstanding": 0,
        "opening_crates": 0,
        "dispatch_crates": 0,
        "received_crates": 0,
        "outstanding_crates": 0,
        "security_amount": 0
      },
      {
        "order_id": 339253,
        "order_date": "2024-06-10",
        "user_id": 44703,
        "user_sap_id": "CUST-004",
        "user_name": "Sample User R",
        "town_name": "Town G",
        "opening_outstanding": 0,
        "milk_sale_amount": 0,
        "other_sale_amount": 3570.6,
        "total_sale": 3570.6,
        "amount_received": 3570,
        "closing_outstanding": 0,
        "opening_crates": 0,
        "dispatch_crates": 0,
        "received_crates": 0,
        "outstanding_crates": 0,
        "security_amount": 0
      }
    ]
  }
}
```

## GET /reports/amount-to-be-paid

Invoice amount against the amount each customer committed to pay, with UTR and security deposit. data is empty until the day's indent is generated (meta.indent_generated).

Access: API key `read` scope; staff need Amount to be paid (12) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `date` | string | no | Day, YYYY-MM-DD only (dd/mm/yyyy is rejected with 400) (alias order_date). Default: today in IST |
| `production_unit_id` | number | no | Plant filter; a plant outside your scope is 403 |
| `user_type` | string | no | distributor or retailer |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/reports/amount-to-be-paid?date=2024-06-10" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": [
    {
      "order_id": 339254,
      "user_id": 44658,
      "emp_sap_id": "CUST-003",
      "store_name": "Demo Store E",
      "user_name": "Sample User C",
      "invoice_amount": 7707.6,
      "amount_to_be_paid": 7707,
      "utr_no": null,
      "security_amount": 0
    }
  ],
  "meta": {
    "date": "2024-06-10",
    "indent_generated": true
  }
}
```

## GET /reports/summary-sheet

Summary sheet: litres and pouches per class and variant split into without scheme, scheme, bonus, employee and FOC; product totals; town-wise totals per class.

Access: API key `read` scope; staff need Summary Report (26) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `date_from` | string | no | Start day, YYYY-MM-DD only (dd/mm/yyyy is rejected with 400). Aliases from_date, start_date, date. Default: today in IST |
| `date_to` | string | no | End day (inclusive), same format. Aliases to_date, end_date. Default: the start day |
| `production_unit_id` | number | no | Plant filter; a plant outside your scope is 403 |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/reports/summary-sheet?date=2024-06-10" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": {
    "date_from": "2024-06-10",
    "date_to": "2024-06-10",
    "classes": [
      {
        "id": 42,
        "product_class": "Milk",
        "unit": "L",
        "variants": [
          {
            "id": 458,
            "variant_name": "Gold 500ML",
            "product_id": 191,
            "product_class_id": 42,
            "ltr_wo_scheme": 0,
            "ltr_scheme": 0,
            "ltr_bonus": 0,
            "ltr_employee": 0,
            "ltr_foc": 0,
            "pouch_wo_scheme": 0,
            "pouch_scheme": 0,
            "pouch_bonus": 0,
            "pouch_employee": 0,
            "pouch_foc": 0,
            "ltr_total": 0,
            "pouch_total": 0
          },
          {
            "id": 459,
            "variant_name": "Gold 6 lt",
            "product_id": 191,
            "product_class_id": 42,
            "ltr_wo_scheme": 0,
            "ltr_scheme": 0,
            "ltr_bonus": 0,
            "ltr_employee": 0,
            "ltr_foc": 0,
            "pouch_wo_scheme": 0,
            "pouch_scheme": 0,
            "pouch_bonus": 0,
            "pouch_employee": 0,
            "pouch_foc": 0,
            "ltr_total": 0,
            "pouch_total": 0
          }
        ],
        "total": {
          "ltr_wo_scheme": 23556.15,
          "ltr_scheme": 66,
          "ltr_bonus": 0,
          "ltr_employee": 0,
          "ltr_foc": 0,
          "ltr_total": 23622.15,
          "pouch_wo_scheme": 54885,
          "pouch_scheme": 132,
          "pouch_bonus": 0,
          "pouch_employee": 0,
          "pouch_foc": 0,
          "pouch_total": 55017
        }
      }
    ],
    "products": [
      {
        "product_name": "Gold",
        "unit": "L",
        "total_quantity": 1995
      }
    ],
    "zones": [
      {
        "town_id": 394,
        "town_name": "Town C",
        "values": [
          800.05,
          5
        ]
      }
    ],
    "zone_totals": [
      23622.15
    ]
  }
}
```

## GET /reports/summary

Headline totals for a period: orders, amount, items, average order value, unique customers, collections, a status breakdown and the top 10 customers. Counts are strings (Postgres bigint). Invalid dates fall back to the defaults instead of 400.

Access: API key `read` scope; staff need Summary Report (26) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `date_from` | string | no | YYYY-MM-DD. Default: the 1st of the current IST month |
| `date_to` | string | no | YYYY-MM-DD. Default: today in IST |
| `production_unit_id` | number | no | Plant filter; a plant outside your scope is 403 |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/reports/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": {
    "total_orders": "708",
    "total_amount": 15125473.750000019,
    "total_items": "4482",
    "avg_order_value": "21363.66",
    "unique_customers": "84",
    "total_collection": "0",
    "status_breakdown": [
      {
        "order_status": 3,
        "status_label": "approved",
        "count": "708",
        "amount": 15125473.750000015,
        "total_items": "4482"
      }
    ],
    "top_users": [
      {
        "user_name": "Sample User V",
        "order_count": "10",
        "total_amount": 2040054.4599999997
      }
    ]
  }
}
```

## GET /reports/sku-contribution

Per distributor, the share (%) of each variant in their own volume. /reports/distributor-contribution is the transpose: each distributor's share of a variant's total.

Access: API key `read` scope; staff need SKU Contribution Report (55) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `date_from` | string | no | Start day, YYYY-MM-DD only (dd/mm/yyyy is rejected with 400). Aliases from_date, start_date, date. Default: today in IST |
| `date_to` | string | no | End day (inclusive), same format. Aliases to_date, end_date. Default: the start day |
| `distributor_id` | number | no | One distributor (alias user_id) |

**Example request**

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

**Example response**

```json
{
  "response_code": 200,
  "data": {
    "date_from": "2024-06-01",
    "date_to": "2024-06-10",
    "milk_variants": [
      {
        "id": 458,
        "variant_name": "Gold 500ML",
        "item_sku_code": "SKU-005",
        "sap_code": "MAT-005",
        "variant_size": "0.5",
        "no_of_pouch": 24,
        "product_class_id": 42,
        "production_unit_id": 18
      },
      {
        "id": 459,
        "variant_name": "Gold 6 lt",
        "item_sku_code": "SKU-006",
        "sap_code": "MAT-006",
        "variant_size": "6",
        "no_of_pouch": 2,
        "product_class_id": 42,
        "production_unit_id": 18
      }
    ],
    "other_variants": [
      {
        "id": 470,
        "variant_name": "Paneer 200gm",
        "item_sku_code": "SKU-007",
        "sap_code": "MAT-007",
        "variant_size": "0.2",
        "no_of_pouch": 1,
        "product_class_id": 44,
        "production_unit_id": 18
      },
      {
        "id": 471,
        "variant_name": "Paneer 500gm",
        "item_sku_code": "SKU-008",
        "sap_code": "MAT-008",
        "variant_size": "0.5",
        "no_of_pouch": 1,
        "product_class_id": 44,
        "production_unit_id": 18
      }
    ],
    "rows": [
      {
        "user_id": 41516,
        "emp_sap_id": "CUST-005",
        "name": "Sample User M",
        "store_name": "Demo Store A",
        "town_name": "Town E",
        "milk": [
          0,
          0
        ],
        "other": [
          0,
          0
        ],
        "total_milk": 8.86,
        "total": 21.25
      },
      {
        "user_id": 41522,
        "emp_sap_id": "CUST-006",
        "name": "Sample User N",
        "store_name": "Demo Store B",
        "town_name": "Town F",
        "milk": [
          0,
          0
        ],
        "other": [
          0,
          0
        ],
        "total_milk": 0,
        "total": 6.55
      }
    ],
    "totals": {
      "milk": [
        0,
        0
      ],
      "other": [
        0,
        0
      ],
      "total_milk": 1300.06,
      "total": 3699.84
    }
  }
}
```

## GET /reports/tagging

Outlets tagged by field staff, with who tagged them and when (tagged_date_ist). The date filter applies only when date_from or date_to is sent.

Access: API key `read` scope; staff need Tagging Report (50) — list.

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

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `search` | string | no | Store name contains |
| `tagged_by` | number | no | Employee id (alias emp_id) |
| `town_id` | number | no | Town |
| `date_from` | string | no | YYYY-MM-DD |
| `date_to` | string | no | YYYY-MM-DD |
| `page` | number | no | Default 1 |
| `limit` | number | no | Default 50, max 100 (larger values are clamped) |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/reports/tagging?limit=1" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": [
    {
      "id": 51869,
      "store_name": "Demo Store B",
      "role_name": "Retailer",
      "first_name": "Sample",
      "middle_name": "",
      "last_name": "User",
      "primary_contact_number": "9876500001",
      "reporting_to_name": "Sample User H",
      "tagged_by": 49246,
      "tagged_date": "2024-06-12T06:19:25.000Z",
      "latitude": "20.0",
      "longitude": "78.0",
      "status": 1,
      "town_name": "Town D",
      "tagged_by_name": "Sample User I",
      "outstanding_amount": null,
      "contact_person": "Sample User J",
      "tagged_date_ist": "2024-06-12"
    }
  ],
  "total": 9918,
  "pagination": {
    "total": 9918,
    "page": 1,
    "limit": 50,
    "total_pages": 199
  }
}
```

## GET /reports/visits

Customer visits from the imported visit history (source: imported) and the sales app (source: sales_app). summary counts visits, distinct employees and distinct outlets over the whole range, not just the page; meta.total equals pagination.total. Oldest first, ordered by visited_at, source and id. GET /reports/visits/{id}/details returns the product lines of one visit.

Access: API key `read` scope; staff need Visit Report (54) — list.

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

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `date_from` | string | no | Start day, YYYY-MM-DD only (dd/mm/yyyy is rejected with 400). Aliases from_date, start_date, date. Default: today in IST |
| `date_to` | string | no | End day (inclusive), same format. Aliases to_date, end_date. Default: the start day |
| `employee_id` | number | no | Employee (alias filter_employee) |
| `outlet_id` | number | no | Outlet (alias filter_store_id); excludes sales-app visits |
| `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/reports/visits?date_from=2024-05-01&date_to=2024-05-31" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": [
    {
      "source": "imported",
      "id": 1572,
      "outlet_id": 50943,
      "employee_id": 45294,
      "visited_at": "2024-05-09T07:49:30.000Z",
      "outlet_name": "Demo Store A",
      "distributor_name": "Sample User A",
      "employee_name": "Sample User B",
      "outcome": null,
      "order_value": null,
      "detail_count": 1
    }
  ],
  "meta": {
    "date_from": "2024-05-01",
    "date_to": "2024-05-31",
    "total": 11
  },
  "summary": {
    "visits": 11,
    "employees": 4,
    "outlets": 11
  },
  "pagination": {
    "total": 11,
    "page": 2,
    "limit": 2,
    "total_pages": 6
  }
}
```

## GET /reports/ho-entry

Head-office employee purchase sheet: variants with employee price, enabled employees, quantities per employee, totals and FOC. PUT /reports/ho-entry saves it (admins).

Access: API key `read` scope; workspace administrators only.

**Example request**

```bash
curl https://api.spirestock.com/api/v1/reports/ho-entry \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": {
    "variants": [
      {
        "id": 470,
        "variant_name": "Paneer 200gm",
        "item_sku_code": "SKU-007",
        "sap_code": "MAT-007",
        "variant_size": "0.2",
        "no_of_pouch": 1,
        "product_class_id": 44,
        "production_unit_id": 18,
        "sp_employee": 63
      },
      {
        "id": 471,
        "variant_name": "Paneer 500gm",
        "item_sku_code": "SKU-008",
        "sap_code": "MAT-008",
        "variant_size": "0.5",
        "no_of_pouch": 1,
        "product_class_id": 44,
        "production_unit_id": 18,
        "sp_employee": 147.35
      }
    ],
    "first_group_count": 8,
    "employees": [],
    "updated_at": null,
    "rows": [],
    "prices": [
      63
    ],
    "total_price": 29829.7,
    "total_quantity": [
      0
    ],
    "total_amount": 0,
    "foc": [
      0
    ],
    "total_foc": 0
  }
}
```

## GET /reports/packing-station

Per class and variant for one day: pouches, crates and litres to pack.

Access: API key `read` scope; staff need Packing Station Report (28) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `date` | string | no | Day, YYYY-MM-DD only (dd/mm/yyyy is rejected with 400). Default: today in IST |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/reports/packing-station?date=2024-06-10" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": {
    "date": "2024-06-10",
    "milk_class_id": 42,
    "classes": [
      {
        "id": 42,
        "product_class": "Milk",
        "variants": [
          {
            "id": 458,
            "variant_name": "Gold 500ML",
            "no_of_pouch": 24,
            "total_quantity": 0,
            "total_crates": 0,
            "total_ltr": 0
          },
          {
            "id": 459,
            "variant_name": "Gold 6 lt",
            "no_of_pouch": 2,
            "total_quantity": 0,
            "total_crates": 0,
            "total_ltr": 0
          }
        ],
        "total": {
          "total_quantity": 55017,
          "total_crates": 2250,
          "total_ltr": 23622.15
        }
      }
    ]
  }
}
```

## GET /reports/visits/filter-options

The employees (both sources) and outlets (imported visits only; sales-app visits carry a name, not an outlet id) that have visits in the date range, for the visit report's filters. Employees sorted by name; outlets by name, capped at 1,000. Not paged.

Access: API key `read` scope; staff need Visit Report (54) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `date_from` | string | no | Start day, YYYY-MM-DD only. Default: today in IST |
| `date_to` | string | no | End day (inclusive). Default: the start day |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/reports/visits/filter-options?date_from=2024-05-01&date_to=2024-05-31" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "data": {
    "employees": [
      {
        "id": 51218,
        "name": "Sample User A"
      },
      {
        "id": 49246,
        "name": "Sample User B"
      }
    ],
    "outlets": [
      {
        "id": 51523,
        "name": "Sample User D"
      },
      {
        "id": 51728,
        "name": "Sample User E"
      }
    ]
  }
}
```
