Search batch transactions

Operation ID: searchBatchTransactions

Group: Inventory › Batch Transactions

Open in the interactive reference

POST /inventory/batch-transactions/search

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

Searches batch transactions. Results are in the order the batch transactions were created, not in order of transactionDate.

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: searchBatchTransactionsInput.

Field Type Required Description
filters object yes The filters to apply. A batch transaction must match every filter you send. Send an empty object to return all batch transactions. Example: {"batchNumber":"LOT-2026-08-14"}.
filters.batchNumberId string no Limits results to batch transactions for the batch with this unique identifier. Format: UUID. When you also send batchNumber, batchNumber is used instead. See id on GET inventory/batch-numbers/:id (getBatchNumber).
filters.batchNumber string no Limits results to batch transactions for batches with this batch number. The match is exact. The same batch number can be used for other items and in other warehouses, so the results can include more than one batch. When you also send batchNumberId, this filter is used instead. Example: 'LOT-2026-08-14'.
filters.itemId string no Limits results to batch transactions for the item with this unique identifier. Format: UUID. See id on GET inventory/items/:id (getItem).
filters.locationId string no Limits results to batch transactions for the warehouse with this unique identifier. Format: UUID. See id on GET inventory/warehouses/:id (getWarehouse).
filters.fromDate date no Limits results to batch transactions with a transactionDate on or after this date. Format: YYYY-MM-DD.
filters.toDate date no Limits results to batch transactions with a transactionDate on or before this date. Format: YYYY-MM-DD.
filters.modifiedSince date-time no Limits results to batch transactions whose lastModifiedDate is 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. Example: {"size":50}.
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 batch transactions per page, from 1 to 200. Defaults to 50. A value above 200 is treated as 200, not rejected. 
{
  "filters": {
    "batchNumber": "LOT-2026-08-14"
  },
  "page": {
    "size": 50
  }
}

Response

200 Success

Under data (searchBatchTransactionsOutput):

Field Type Required Description
items array<object> yes The matching batch transactions in this response. When more batch transactions match than fit in one response, use pagination to get the rest. Empty when nothing matches. Example: [{"id":"6d2b8e17-4f90-4c53-a821-0e7d3b95c46f","batchNumberId":"9c31f5a8-6b02-4e79-b354-8d1a67e0f2b9","batchNumber":"LOT-2026-08-14","expirationDate":"2027-08-14","transactionId":"3a7c1f95-04eb-4d62-8917-5c0e2b8d4a63","itemId":"5f21c8b0-9d34-4a76-8e12-04b93c7de5a8","itemCode":"WIDGET-01","itemName":"Standard widget","locationId":"e1d84c07-5b39-4a26-9f70-2c8b613ad495","locationCode":"WH-01","locationName":"Rotterdam Distribution Centre","transactionDate":"2026-08-03","inQuantity":"500.00","cost":"3.75","valueDelta":"1875.00","currency":"EUR","sourceDocumentLineType":"InvPurchaseDeliveryLine","lastModifiedDate":"2026-08-03T11:15:00.000Z"}].
items[].id string yes The unique identifier for the batch transaction. Format: UUID.
items[].batchNumberId string yes The unique identifier of the batch this transaction is for. Format: UUID. See id on GET inventory/batch-numbers/:id (getBatchNumber).
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. Example: 'LOT-2026-08-14'.
items[].expirationDate date no The date the batch expires. It shows the batch's current value, not the value at the time of the batch transaction. Format: YYYY-MM-DD.
items[].transactionId string no The unique identifier of the inventory transaction this batch transaction belongs to. Format: UUID. See id on GET inventory/inventory-transactions/:id (getInventoryTransaction).
items[].itemId string no The unique identifier of the item. 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. 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[].unitId string no The unique identifier of the unit of measure the batch transaction was recorded in. Format: UUID. See id on GET inventory/unit-of-measures/:id (getUnitOfMeasure).
items[].unitCode string no The code of the unit of measure in unitId.
items[].transactionDate date no The date of the inventory transaction this batch transaction belongs to. Format: YYYY-MM-DD.
items[].inQuantity decimal no The quantity of the batch that came into stock, in the item's stocking unit. It is 0 on an inventory revaluation, which changes the batch's cost without moving stock. Absent when stock went out.
items[].outQuantity decimal no The quantity of the batch that went out of stock, in the item's stocking unit. Absent when stock came in or on an inventory revaluation.
items[].unitInQuantity decimal no The quantity that came into stock, in the unit of measure named by unitId. It can differ from inQuantity, which is in the item's stocking unit.
items[].unitOutQuantity decimal no The quantity that went out of stock, in the unit of measure named by unitId. It can differ from outQuantity, which is in the item's stocking unit.
items[].cost decimal no The unit cost of the batch, in the currency named by currency. When stock comes in, it is the unit cost of the stock received. When stock goes out, it is the batch's unit cost at that time. On an inventory revaluation, it is the batch's new unit cost.
items[].valueDelta decimal no The change in the total value of the batch's stock from this transaction, in the currency named by currency. A negative value is a decrease.
items[].currency string no The currency that cost and valueDelta are in. Format: ISO 4217, for example 'USD'.
items[].sourceDocumentLineType any no The type of document line the inventory transaction came from. One of: "IMInventorySalesOrderLine", "IMInventorySalesDeliveryLine", "IMSalesOrderLine", "IMInventoryPurchaseReturnLine", "IMInventorySalesReturnLine", "IMWarehouseTransferLine", "IMInventoryDecreaseLine", "IMInventoryIncreaseLine", "IMInventoryRevaluationLine", "IMInventoryTransferLine", "IMInventoryAdjustmentLine", "IMInventoryCountLine", "IMInventoryPutAwayTask", "IMInventoryPurchaseReturnReversal", "PurchaseOrderLine", "IMLandedCostAllocationLine", "SalesOrderProductItem", "IMWarehouseTransferOrderLine", "VendorBillItemBase", "InvPurchaseDeliveryLine".
items[].lastModifiedDate date-time no The date and time the batch transaction last changed, in UTC. Format: YYYY-MM-DDTHH:mm:ss.sssZ. Changes to the batch itself, such as its expirationDate, do not update this field.
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 yes Whether there are more results than are in this response. 
{
  "data": {
    "items": [
      {
        "id": "6d2b8e17-4f90-4c53-a821-0e7d3b95c46f",
        "batchNumberId": "9c31f5a8-6b02-4e79-b354-8d1a67e0f2b9",
        "batchNumber": "LOT-2026-08-14",
        "expirationDate": "2027-08-14",
        "transactionId": "3a7c1f95-04eb-4d62-8917-5c0e2b8d4a63",
        "itemId": "5f21c8b0-9d34-4a76-8e12-04b93c7de5a8",
        "itemCode": "WIDGET-01",
        "itemName": "Standard widget",
        "locationId": "e1d84c07-5b39-4a26-9f70-2c8b613ad495",
        "locationCode": "WH-01",
        "locationName": "Rotterdam Distribution Centre",
        "transactionDate": "2026-08-03",
        "inQuantity": "500.00",
        "cost": "3.75",
        "valueDelta": "1875.00",
        "currency": "EUR",
        "sourceDocumentLineType": "InvPurchaseDeliveryLine",
        "lastModifiedDate": "2026-08-03T11:15:00.000Z"
      }
    ],
    "pagination": {
      "hasMore": false
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Statuses