# Search batch numbers

Operation ID: `searchBatchNumbers`

Group: Inventory › Batch Numbers

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/searchBatchNumbers)

`POST /inventory/batch-numbers/search`

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Searches batch numbers, with their costs. For a shelf-life check, send `expiringBefore` with `inStock` true to find the batches still in stock that expire by a date.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | string · v1 | yes | The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`. |

## Request body

Required, `application/json`: searchBatchNumbersInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | yes | The filters to apply. A batch must match every filter you send. Send an empty object to return all batches. Example: `{"expiringBefore":"2027-12-31","inStock":true}`. |
| `filters.batchNumber` | string | no | Limits results to batches with this batch number. The match is exact. |
| `filters.manufacturerBatchNumber` | string | no | Limits results to batches with this manufacturer's batch number. The match is exact. |
| `filters.itemId` | string | no | Limits results to batches for the item with this unique identifier. Format: UUID. See `id` on GET inventory/items/:id (getItem). |
| `filters.locationId` | string | no | Limits results to batches in the warehouse with this unique identifier. Format: UUID. See `id` on GET inventory/warehouses/:id (getWarehouse). |
| `filters.batchStatus` | string | no | Limits results to batches with this status. Accepted values: 'ACTIVE', 'QUARANTINED', 'EXPIRED', 'DISPOSED'. |
| `filters.temperatureBreach` | boolean | no | Limits results to batches with a temperature breach when true, and to batches without one when false. |
| `filters.qcStatus` | string | no | Limits results to batches with this quality-control status. The match is exact. |
| `filters.active` | boolean | no | Limits results to active batches when true, and to inactive batches when false. |
| `filters.inStock` | boolean | no | Limits results to batches with stock when true, and to batches with no stock when false. |
| `filters.expiringBefore` | date | no | Limits results to batches expiring on or before this date. Format: YYYY-MM-DD. |
| `filters.expiringAfter` | date | no | Limits results to batches expiring on or after this date. Format: YYYY-MM-DD. |
| `filters.modifiedSince` | date-time | no | Limits results to batches changed on or after this time. Format: YYYY-MM-DDTHH:mm:ss.sssZ. |
| `page` | object | no | The page to return and its size. Omit to get the first page at the default size. |
| `page.cursor` | string | no | The cursor from the previous response's `pagination.nextCursor`. Send it exactly as you received it. Omit on the first request. |
| `page.size` | number | no | The number of batches per page, from 1 to 200. Defaults to 50. A value above 200 is treated as 200, not rejected. |

```json
{
  "filters": {
    "expiringBefore": "2027-12-31",
    "inStock": true
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}
```

## Response

`200` Success

Under `data` (searchBatchNumbersOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array<object> | yes | The matching batches in this response. When more batches match than fit in one response, use `pagination` to get the rest. Empty when nothing matches. Example: `[{"id":"7a4e91c3-2b58-4d06-9f31-c85e207a4b19","batchNumber":"LOT-2026-0448","manufacturerBatchNumber":"MFG-8842-C","itemId":"517a93e4-cbb4-4571-9e3d-2343e56cfd84","itemCode":"WIDGET-01","locationId":"f5272ae0-0f0b-47d2-b78a-2158fec2cc32","locationCode":"WH-02","quantity":"400","inStock":"260","cost":"12.5","originalCost":"12","currency":"GBP","expirationDate":"2027-03-31","batchStatus":"ACTIVE","temperatureBreach":false,"active":true,"lastModifiedDate":"2026-08-18T09:14:22.517Z"}]`. |
| `items[].id` | string | yes | The unique identifier for the batch number. Format: UUID. |
| `items[].batchNumber` | string | no | The batch number, such as a lot number printed on the goods. It is entered on the receipt, inventory increase, or other document that first recorded the batch's stock. The same batch number can be used for other items and in other warehouses, so it identifies a batch only together with the item and the warehouse. |
| `items[].manufacturerBatchNumber` | string | no | The manufacturer's batch number. |
| `items[].itemId` | string | no | The unique identifier of the item this batch belongs to. Format: UUID. See `id` on GET inventory/items/:id (getItem). |
| `items[].itemCode` | string | no | The code of the item in `itemId`. |
| `items[].itemName` | string | no | The name of the item in `itemId`. |
| `items[].locationId` | string | no | The unique identifier of the warehouse the batch is in. Format: UUID. See `id` on GET inventory/warehouses/:id (getWarehouse). |
| `items[].locationCode` | string | no | The code of the warehouse in `locationId`. |
| `items[].locationName` | string | no | The name of the warehouse in `locationId`. |
| `items[].quantity` | decimal | no | The total quantity received into the batch, in the item's stocking unit. When a receipt, inventory increase, or inventory count creates the batch, it is 0 until the document that brings in the stock is committed. For a batch created by a production order, it does not show the quantity received, so use `inStock` instead. Unlike `inStock`, it does not change when stock leaves the batch or comes back on a sales return. Only canceling a receipt, inventory increase, or warehouse transfer that brought stock into the batch lowers it. |
| `items[].inStock` | decimal | no | The quantity of the batch currently in stock, in the item's stocking unit. It counts all of the batch's stock, whatever its `batchStatus`, so quarantined, expired, and disposed stock are included. To take stock out, create and commit a document that moves it out, such as an inventory decrease. |
| `items[].cost` | decimal | no | The cost of one unit of the batch. When more stock comes into the batch, the cost becomes the average of the existing and new stock, weighted by quantity. |
| `items[].originalCost` | decimal | no | The cost of one unit of the batch when the stock was first received. Landed costs added later, such as freight or customs duty, raise it, and other revaluations can raise or lower it. When the batch is refilled after running out, it is reset to the new stock's cost. |
| `items[].currency` | string | no | The currency of `cost` and `originalCost`. Format: ISO 4217, for example 'USD'. |
| `items[].expirationDate` | date | no | The date the batch expires. Format: YYYY-MM-DD. |
| `items[].manufactureDate` | date | no | The date the manufacturer made the batch. Format: YYYY-MM-DD. |
| `items[].bestBeforeDate` | date | no | The best-before date of the batch. Format: YYYY-MM-DD. |
| `items[].entryDate` | date | no | The date the batch's age is counted from. Format: YYYY-MM-DD. When a receipt or inventory increase creates the batch, it is the date entered for the batch on that document, or the document's date when none was entered. When a warehouse transfer creates the batch, it is the `entryDate` of the batch in the sending warehouse. Each later receipt or inventory increase for the batch sets a new date. The age of all the batch's stock is then counted from the new date, including stock received earlier. A warehouse transfer that adds stock to an existing batch does not change the date. |
| `items[].batchStatus` | string | no | The status of the batch. Changing the status does not change the batch's `quantity`, `inStock`, or `cost`. Possible values: 'ACTIVE', 'QUARANTINED', 'EXPIRED', 'DISPOSED'. |
| `items[].temperatureBreach` | boolean | no | Whether the batch has been outside its storage temperature range. |
| `items[].qcStatus` | string | no | The quality-control status of the batch, as free text. |
| `items[].active` | boolean | no | Whether the batch is active. |
| `items[].createdDate` | date-time | no | The date and time the batch record was created, in UTC. Format: YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lastModifiedDate` | date-time | no | The date and time the batch record last changed, in UTC. Format: YYYY-MM-DDTHH:mm:ss.sssZ. |
| `pagination` | object | yes | Whether there are more results than are in this response, and the cursor you use to get the next ones. Example: `{"hasMore":false}`. |
| `pagination.nextCursor` | string | no | The cursor that marks where this response stopped. To get the next results, send it as `page.cursor` in your next request. Absent when there are no more results. |
| `pagination.hasMore` | boolean | no | Whether there are more results than are in this response. |

```json
{
  "data": {
    "items": [
      {
        "id": "7a4e91c3-2b58-4d06-9f31-c85e207a4b19",
        "batchNumber": "LOT-2026-0448",
        "manufacturerBatchNumber": "MFG-8842-C",
        "itemId": "517a93e4-cbb4-4571-9e3d-2343e56cfd84",
        "itemCode": "WIDGET-01",
        "locationId": "f5272ae0-0f0b-47d2-b78a-2158fec2cc32",
        "locationCode": "WH-02",
        "quantity": "400",
        "inStock": "260",
        "cost": "12.5",
        "originalCost": "12",
        "currency": "GBP",
        "expirationDate": "2027-03-31",
        "batchStatus": "ACTIVE",
        "temperatureBreach": false,
        "active": true,
        "lastModifiedDate": "2026-08-18T09:14:22.517Z"
      }
    ],
    "pagination": {
      "hasMore": false
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}
```

## Statuses

- `400` — Invalid request or business failure
- `401` — The request carries no valid access token.
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests from this client address. The response has no body and no `Retry-After` header.
- `500` — Internal server error