List batch numbers
Operation ID: batchNumbers
Group: Inventory › Batch Numbers
Open in the interactive reference
GET /inventory/batch-numbers
Read-only: Reads and returns; changes nothing.
Lists batch numbers, without their costs. For cost, originalCost, and currency, use POST inventory/batch-numbers/search or GET inventory/batch-numbers/:id.
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. |
Query surface
id— filter by eq, ne, gt, gte, lt, lte, in, notIn, between, likebatchNumber— filter by eq, ne, gt, gte, lt, lte, in, notIn, between, likemanufacturerBatchNumber— filter by eq, ne, gt, gte, lt, lte, in, notIn, between, likeitemId— filter by eq, ne, gt, gte, lt, lte, in, notIn, between, likelocationId— filter by eq, ne, gt, gte, lt, lte, in, notIn, between, likeexpirationDate— filter by eq, ne, gt, gte, lt, lte, in, notIn, betweenbatchStatus— filter by eq, ne, gt, gte, lt, lte, in, notIn, between, liketemperatureBreach— filter by eq, ne, gt, gte, lt, lte, in, notIn, betweenqcStatus— filter by eq, ne, gt, gte, lt, lte, in, notIn, between, likeactive— filter by eq, ne, gt, gte, lt, lte, in, notIn, betweenlastModifiedDate— filter by eq, ne, gt, gte, lt, lte, in, notIn, between- Orderable: id, batchNumber, expirationDate, batchStatus, lastModifiedDate
- Selectable: id, batchNumber, manufacturerBatchNumber, itemId, itemCode, itemName, locationId, locationCode, locationName, quantity, inStock, expirationDate, manufactureDate, bestBeforeDate, entryDate, batchStatus, temperatureBreach, qcStatus, active, createdDate, lastModifiedDate
page[size]— Page sizepage[cursor]— Opaque continuation cursor
Response
200 Success
Under data, an array of batchNumbersRow:
| Field | Type | Required | Filter | Sort | Description |
|---|---|---|---|---|---|
id |
string | no | Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn), Pattern (like) |
yes | The unique identifier for the batch number. Format: UUID. Example: "7a4e91c3-2b58-4d06-9f31-c85e207a4b19". |
batchNumber |
string | null | no | Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn), Pattern (like) |
yes | 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. Example: "LOT-2026-0448". |
manufacturerBatchNumber |
string | null | no | Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn), Pattern (like) |
no | The manufacturer's batch number. |
itemId |
string | null | no | Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn), Pattern (like) |
no | The unique identifier of the item this batch belongs to. Format: UUID. See id on GET inventory/items/:id (getItem). Example: "517a93e4-cbb4-4571-9e3d-2343e56cfd84". |
itemCode |
string | null | no | no | no | The code of the item in itemId. Example: "WIDGET-01". |
itemName |
string | null | no | no | no | The name of the item in itemId. |
locationId |
string | null | no | Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn), Pattern (like) |
no | The unique identifier of the warehouse the batch is in. Format: UUID. See id on GET inventory/warehouses/:id (getWarehouse). Example: "f5272ae0-0f0b-47d2-b78a-2158fec2cc32". |
locationCode |
string | null | no | no | no | The code of the warehouse in locationId. Example: "WH-02". |
locationName |
string | null | no | no | no | The name of the warehouse in locationId. |
quantity |
decimal | null | no | no | 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. Example: "400". |
inStock |
decimal | null | no | no | 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. Example: "260". |
expirationDate |
date | null | no | Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn) |
yes | The date the batch expires. Format: YYYY-MM-DD. Example: "2027-03-31". |
manufactureDate |
date | null | no | no | no | The date the manufacturer made the batch. Format: YYYY-MM-DD. |
bestBeforeDate |
date | null | no | no | no | The best-before date of the batch. Format: YYYY-MM-DD. |
entryDate |
date | null | no | no | 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. |
batchStatus |
string | null | no | Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn), Pattern (like) |
yes | The status of the batch. Changing the status does not change the batch's quantity, inStock, or cost. Possible values: 'ACTIVE', 'QUARANTINED', 'EXPIRED', 'DISPOSED'. Example: "ACTIVE". |
temperatureBreach |
boolean | null | no | Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn) |
no | Whether the batch has been outside its storage temperature range. |
qcStatus |
string | null | no | Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn), Pattern (like) |
no | The quality-control status of the batch, as free text. |
active |
boolean | null | no | Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn) |
no | Whether the batch is active. Example: true. |
createdDate |
date-time | null | no | no | no | The date and time the batch record was created, in UTC. Format: YYYY-MM-DDTHH:mm:ss.sssZ. |
lastModifiedDate |
date-time | null | no | Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn) |
yes | The date and time the batch record last changed, in UTC. Format: YYYY-MM-DDTHH:mm:ss.sssZ. Example: "2026-08-18T09:14:22.517Z". |
{
"data": [
{
"id": "7a4e91c3-2b58-4d06-9f31-c85e207a4b19",
"batchNumber": "LOT-2026-0448",
"manufacturerBatchNumber": "<manufacturerBatchNumber>",
"itemId": "517a93e4-cbb4-4571-9e3d-2343e56cfd84",
"itemCode": "WIDGET-01",
"itemName": "<itemName>",
"locationId": "f5272ae0-0f0b-47d2-b78a-2158fec2cc32",
"locationCode": "WH-02",
"locationName": "<locationName>",
"quantity": "400",
"inStock": "260",
"expirationDate": "2027-03-31",
"manufactureDate": "2026-01-15",
"bestBeforeDate": "2026-01-15",
"entryDate": "2026-01-15",
"batchStatus": "ACTIVE",
"temperatureBreach": true,
"qcStatus": "<qcStatus>",
"active": true,
"createdDate": "2026-01-15T09:30:00.000Z",
"lastModifiedDate": "2026-08-18T09:14:22.517Z"
}
],
"pagination": {
"hasMore": true,
"nextCursor": "<nextCursor>"
}
}
Statuses
400— Invalid request or business failure401— The request carries no valid access token.403— Not authorized404— Not found429— Too many requests from this client address. The response has no body and noRetry-Afterheader.500— Internal server error