# Returns the receipts that match the given filters.

`POST /inventory/receipts/search`

Group: Inventory › Receipts · Operation ID: `searchReceipts`

Returns the receipts that match the given filters, each with its full lines and their batch, serial and bin detail, the same fields GET inventory/receipts/:id returns. This is the only endpoint that returns the lines, and the only one that filters by vendor, reference number, item or warehouse. Every criterion is exact or a range, and criteria combine with AND. Send an empty filters object to return every receipt.

[Open in the interactive reference](https://docs.api.lensing.ai/?op=searchReceipts)

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | `"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`: searchReceiptsInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | yes | The filters to apply. A receipt must match every filter you send. Send an empty object to return all receipts. |
| `filters.documentNumber` | string | no | Limits results to the receipt with this receipt number. The match is exact. |
| `filters.documentStatus` | string | no | Limits results to receipts with this status. The match is exact. |
| `filters.entityId` | string | no | Limits results to receipts for this legal entity. |
| `filters.businessPartnerId` | string | no | Limits results to receipts from this vendor. |
| `filters.locationId` | string | no | Limits results to receipts that have a line for this warehouse. |
| `filters.itemId` | string | no | Limits results to receipts that have a line for this item. |
| `filters.referenceNumber` | string | no | Limits results to receipts with this vendor reference. The match is exact. |
| `filters.fromDate` | string (date) | no | Limits results to receipts dated on or after this date. Format YYYY-MM-DD. |
| `filters.toDate` | string (date) | no | Limits results to receipts dated on or before this date. Format YYYY-MM-DD. |
| `filters.modifiedSince` | string (date-time) | no | Limits results to receipts changed on or after this time. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `page` | object | no | The pagination controls. Omit for the first page. |
| `page.cursor` | string | no | The cursor from the previous response's pagination.nextCursor. Omit for the first page. |
| `page.size` | number | no | The number of receipts per page. Defaults to 50. A value above 200 is treated as 200, not rejected. |

Example:

```json
{
  "filters": {
    "documentStatus": "DRAFT"
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}
```

## Response

`200` Success

Under `data` (searchReceiptsOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes | The receipts on this page, oldest first, each with its lines. An empty array when nothing matches. |
| `items[].id` | string | yes | The unique identifier for the receipt. |
| `items[].documentNumber` | string | no | The receipt number, for example 'GR-2291'. Assigned when the receipt is created. |
| `items[].documentStatus` | string | yes | The status of the receipt. It is DRAFT when the receipt is created through this API and COMMITTED once you commit it with POST inventory/receipts/:id/commit. The receiving and invoicing processes set the other statuses. |
| `items[].documentDate` | string (date) | yes | The date of the receipt. Format YYYY-MM-DD. |
| `items[].deliveryDate` | string (date) | no | The date the goods arrived or are expected. Format YYYY-MM-DD. |
| `items[].entityId` | string | yes | The legal entity the receipt belongs to. |
| `items[].entityName` | string | no | The name of that legal entity. |
| `items[].businessPartnerId` | string | yes | The vendor the goods came from. |
| `items[].businessPartnerName` | string | no | The name of that vendor. |
| `items[].referenceNumber` | string | no | The vendor's own reference, typically their delivery note number. |
| `items[].currency` | string | no | The currency of the receipt's amounts. Format ISO 4217, for example 'EUR'. This is the vendor's currency, which need not be the entity's functional currency. See functionalUnitPrice on the line for the functional-currency amounts. |
| `items[].totalAmount` | string (decimal) | no | The total value of the receipt, in the receipt's currency. |
| `items[].notes` | string | no | Free text on the receipt. |
| `items[].createdDate` | string (date-time) | no | The date and time the receipt was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lastModifiedDate` | string (date-time) | no | The date and time the receipt last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lines` | array of object | yes | The lines of the receipt, oldest first. A receipt always has at least one line. |
| `items[].lines[].id` | string | yes | The unique identifier for the line. Use it in updateLines and deleteLines. |
| `items[].lines[].lineType` | string | no | The type of the line. Possible values: 'Inventory', 'Service', 'Expense'. Only an Inventory line moves stock. A Service or Expense line records something bought that does not enter a warehouse and has a description instead of an item. |
| `items[].lines[].itemId` | string | no | The item received. Absent on a Service or Expense line. |
| `items[].lines[].itemCode` | string | no | The short code of that item. |
| `items[].lines[].itemName` | string | no | The name of that item. |
| `items[].lines[].serviceDescription` | string | no | What a Service or Expense line is for. Absent on an Inventory line. |
| `items[].lines[].locationId` | string | no | The warehouse the goods went into. Absent on a Service or Expense line. |
| `items[].lines[].locationCode` | string | no | The short code of that warehouse. |
| `items[].lines[].locationName` | string | no | The name of that warehouse. |
| `items[].lines[].unitId` | string | no | The unit the quantity is counted in. |
| `items[].lines[].unitCode` | string | no | The short code of that unit. |
| `items[].lines[].quantity` | string (decimal) | no | The quantity received, in the line's unit. |
| `items[].lines[].inventoryQuantity` | string (decimal) | no | The same quantity in the item's stocking unit. |
| `items[].lines[].receivedQuantity` | string (decimal) | no | The quantity actually received, where the receiving process records it separately. |
| `items[].lines[].openQuantity` | string (decimal) | no | The quantity still to be invoiced. |
| `items[].lines[].returnedQuantity` | string (decimal) | no | The quantity that has gone back on a purchase return. |
| `items[].lines[].unitPrice` | string (decimal) | no | The price of one unit, in the receipt's currency. |
| `items[].lines[].lineTotal` | string (decimal) | no | The total for the line, in the receipt's currency. |
| `items[].lines[].functionalUnitPrice` | string (decimal) | no | The unit price in the entity's functional currency. Present when the receipt is in another currency. |
| `items[].lines[].functionalLineTotal` | string (decimal) | no | The line total in the entity's functional currency. |
| `items[].lines[].expenseAccountId` | string | no | The GL account a Service or Expense line is charged to. Absent on an Inventory line. |
| `items[].lines[].expenseAccountNumber` | string | no | The number of that account. |
| `items[].lines[].expenseAccountName` | string | no | The name of that account. |
| `items[].lines[].status` | string | no | Where the line is in the receiving process. This is free text, with no fixed set of values. |
| `items[].lines[].sourceDocumentLineId` | string | no | The purchase order line this line was received against. It is a numeric id in string form, not a UUID. Purchase order lines are not individually addressable, so there is no endpoint that takes it. |
| `items[].lines[].sourceDocumentLineType` | string, one of `"IMInventorySalesOrderLine"`, `"IMInventorySalesDeliveryLine"`, `"IMSalesOrderLine"`, `"IMInventoryPurchaseReturnLine"`, `"IMInventorySalesReturnLine"`, `"IMWarehouseTransferLine"`, `"IMInventoryDecreaseLine"`, `"IMInventoryIncreaseLine"`, `"IMInventoryRevaluationLine"`, `"IMInventoryTransferLine"`, `"IMInventoryAdjustmentLine"`, `"IMInventoryCountLine"`, `"IMInventoryPutAwayTask"`, `"IMInventoryPurchaseReturnReversal"`, `"PurchaseOrderLine"`, `"IMLandedCostAllocationLine"`, `"SalesOrderProductItem"`, `"IMWarehouseTransferOrderLine"`, `"VendorBillItemBase"`, `"InvPurchaseDeliveryLine"` | no | The kind of source document line this receipt line was created from. |
| `items[].lines[].notes` | string | no | Free text on the line. |
| `items[].lines[].batches` | array of object | no | The batches received on this line, for a batch-tracked item. Absent when the item is not batch-tracked. |
| `items[].lines[].batches[].batchNumberId` | string | no | The unique identifier for the batch record this entry created or matched. |
| `items[].lines[].batches[].batchNumber` | string | yes | The batch number as printed. |
| `items[].lines[].batches[].expirationDate` | string (date) | no | The expiration date of the batch. Format YYYY-MM-DD. |
| `items[].lines[].batches[].quantity` | string (decimal) | yes | The quantity of this batch received, in the line's unit. |
| `items[].lines[].batches[].inventoryQuantity` | string (decimal) | no | The same quantity in the item's stocking unit. |
| `items[].lines[].batches[].openQuantity` | string (decimal) | no | The quantity of this batch still to be invoiced. |
| `items[].lines[].batches[].returnedQuantity` | string (decimal) | no | The quantity of this batch that has gone back to the vendor. |
| `items[].lines[].batches[].unitCost` | string (decimal) | no | The cost of one unit of this batch, in the receipt's currency. |
| `items[].lines[].serials` | array of object | no | The serialized units received, one entry per unit. Absent when the item is not serialized. |
| `items[].lines[].serials[].serialNumberId` | string | no | The unique identifier for the serial record this entry created or matched. |
| `items[].lines[].serials[].serialNumber` | string | yes | The serial number as stamped on the unit. |
| `items[].lines[].serials[].openQuantity` | string (decimal) | no | The quantity of this unit still to be invoiced. |
| `items[].lines[].serials[].returnedQuantity` | string (decimal) | no | The quantity of this unit that has gone back to the vendor. |
| `items[].lines[].serials[].unitCost` | string (decimal) | no | The cost of this unit, in the receipt's currency. |
| `items[].lines[].binLocations` | array of object | no | The bins the goods went into, in a bin-tracked warehouse. One flat array per line: an entry that names a batchNumber or serialNumber belongs to that batch or unit, and one that names neither belongs to the line. |
| `items[].lines[].binLocations[].binLocationId` | string | yes | The bin the goods went into. |
| `items[].lines[].binLocations[].binLocationCode` | string | no | The short code of that bin. |
| `items[].lines[].binLocations[].quantity` | string (decimal) | yes | The quantity put into this bin, in the line's unit. |
| `items[].lines[].binLocations[].inventoryQuantity` | string (decimal) | no | The same quantity in the item's stocking unit. |
| `items[].lines[].binLocations[].batchNumber` | string | no | The batch this bin entry belongs to, when it belongs to one of the line's batches. |
| `items[].lines[].binLocations[].serialNumber` | string | no | The serialized unit this bin entry belongs to, when it belongs to one of the line's units. |
| `pagination` | object | yes | The pagination cursor for this page. |
| `pagination.nextCursor` | string | no | The cursor for the next page. Pass it as page.cursor. Absent on the last page. |
| `pagination.hasMore` | boolean | yes | True when more receipts remain beyond this page. |

## Statuses

- `400` — Invalid request or business failure
- `401` — Missing or invalid access token
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests
- `500` — Internal server error