Retrieve a batch number

Operation ID: getBatchNumber

Group: Inventory › Batch Numbers

Open in the interactive reference

GET /inventory/batch-numbers/{id}

Read-only: Reads and returns; changes nothing.

Retrieves a batch number, with its costs.

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.
id path string yes The unique identifier of the batch number you want to retrieve. Format: UUID.

Response

200 Success

Under data (getBatchNumberOutput):

Field Type Required Description
id string yes The unique identifier for the batch number. Format: UUID. Example: "7a4e91c3-2b58-4d06-9f31-c85e207a4b19".
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. Example: "LOT-2026-0448".
manufacturerBatchNumber string no The manufacturer's batch number. Example: "MFG-8842-C".
itemId string 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 no The code of the item in itemId. Example: "WIDGET-01".
itemName string no The name of the item in itemId.
locationId string 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 no The code of the warehouse in locationId. Example: "WH-02".
locationName string no The name of the warehouse in locationId.
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. Example: "400".
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. Example: "260".
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. Example: "12.5".
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. Example: "12".
currency string no The currency of cost and originalCost. Format: ISO 4217, for example 'USD'. Example: "GBP".
expirationDate date no The date the batch expires. Format: YYYY-MM-DD. Example: "2027-03-31".
manufactureDate date no The date the manufacturer made the batch. Format: YYYY-MM-DD.
bestBeforeDate date no The best-before date of the batch. Format: YYYY-MM-DD.
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.
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'. Example: "ACTIVE".
temperatureBreach boolean no Whether the batch has been outside its storage temperature range. Example: false.
qcStatus string no The quality-control status of the batch, as free text.
active boolean no Whether the batch is active. Example: true.
createdDate date-time no The date and time the batch record was created, in UTC. Format: YYYY-MM-DDTHH:mm:ss.sssZ.
lastModifiedDate date-time no 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": "MFG-8842-C",
    "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",
    "cost": "12.5",
    "originalCost": "12",
    "currency": "GBP",
    "expirationDate": "2027-03-31",
    "manufactureDate": "2026-01-15",
    "bestBeforeDate": "2026-01-15",
    "entryDate": "2026-01-15",
    "batchStatus": "ACTIVE",
    "temperatureBreach": false,
    "qcStatus": "<qcStatus>",
    "active": true,
    "createdDate": "2026-01-15T09:30:00.000Z",
    "lastModifiedDate": "2026-08-18T09:14:22.517Z"
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Errors

Code Status
NOT_FOUND 400

Statuses