# Search purchase returns

Operation ID: `searchPurchaseReturns`

Group: Inventory › Purchase Returns

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

`POST /inventory/purchase-returns/search`

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

Searches purchase returns, with their lines and applications.

## 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`: searchPurchaseReturnsInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | yes | The filters to apply. A purchase return must match every filter you send. Send an empty object to return all purchase returns. Example: `{"businessPartnerId":"b62e4f17-0c93-4a58-8d21-5f70e3b9a4c6","documentStatus":"COMMITTED","fromDate":"2026-08-01"}`. |
| `filters.documentNumber` | string | no | Limits results to the purchase return with this document number. The match is exact. |
| `filters.documentStatus` | string | no | Limits results to purchase returns with this status. The match is exact. Accepted values: 'DRAFT', 'APPROVED', 'PREPARED', 'SHIPPED', 'COMMITTED', 'VENDOR_ACKNOWLEDGED', 'CREDITED', 'COMPLETED', 'CANCELLED'. |
| `filters.returnType` | string | no | Limits results to purchase returns of this type. Accepted values: 'NORMAL', 'UNCREDITED_REPLACEMENT', 'UNINVOICED_CANCELLATION'. |
| `filters.entityId` | string | no | Limits results to purchase returns for the legal entity with this unique identifier. Format: UUID. See `id` on GET base/entities (entities). |
| `filters.businessPartnerId` | string | no | Limits results to purchase returns for the vendor with this unique identifier. Format: UUID. See `id` on GET accounting/vendors/:id (getVendor). |
| `filters.locationId` | string | no | Limits results to purchase returns with at least one line for the warehouse with this unique identifier. Format: UUID. See `id` on GET inventory/warehouses/:id (getWarehouse). |
| `filters.itemId` | string | no | Limits results to purchase returns with at least one line for the item with this unique identifier. Format: UUID. See `id` on GET inventory/items/:id (getItem). |
| `filters.referenceNumber` | string | no | Limits results to purchase returns with this reference. The match is exact. |
| `filters.fromDate` | date | no | Limits results to purchase returns whose `documentDate` is on or after this date. Format: YYYY-MM-DD. |
| `filters.toDate` | date | no | Limits results to purchase returns whose `documentDate` is on or before this date. Format: YYYY-MM-DD. |
| `filters.modifiedSince` | date-time | no | Limits results to purchase returns 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. 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 purchase returns per page, from 1 to 200. Defaults to 50. A value above 200 is treated as 200, not rejected. |

```json
{
  "filters": {
    "businessPartnerId": "b62e4f17-0c93-4a58-8d21-5f70e3b9a4c6",
    "documentStatus": "COMMITTED",
    "fromDate": "2026-08-01"
  },
  "page": {
    "size": 50
  }
}
```

## Response

`200` Success

Under `data` (searchPurchaseReturnsOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array<object> | yes | The matching purchase returns in this response, with their lines. When more purchase returns match than fit in one response, use `pagination` to get the rest. Empty when nothing matches. Example: `[{"id":"6a1f30c9-4d82-4b57-9e60-83c25f0a71b4","documentNumber":"PRTR-1043","documentStatus":"COMMITTED","documentDate":"2026-08-20","returnType":"NORMAL","entityId":"1a9c4e70-38b5-4d26-9f01-7c2e5b8a6d43","businessPartnerId":"b62e4f17-0c93-4a58-8d21-5f70e3b9a4c6","currency":"EUR","totalAmount":"96.00","lines":[{"id":"8c14a6f2-3b70-4d59-9e02-6f5a1d38b47c","itemId":"5f21c8b0-9d34-4a76-8e12-04b93c7de5a8","quantity":"30.00"}]}]`. |
| `items[].id` | string | yes | The unique identifier for the purchase return. Format: UUID. |
| `items[].documentNumber` | string | no | The purchase return number, for example 'PRTR-1043'. |
| `items[].documentStatus` | string | yes | The status of the purchase return. Possible values: 'DRAFT', 'APPROVED', 'PREPARED', 'SHIPPED', 'COMMITTED', 'VENDOR_ACKNOWLEDGED', 'CREDITED', 'COMPLETED', 'CANCELLED'. |
| `items[].documentDate` | date | yes | The date of the purchase return. Format: YYYY-MM-DD. |
| `items[].deliveryDate` | date | no | The delivery date of the purchase return. Format: YYYY-MM-DD. |
| `items[].returnType` | string | no | The type of the purchase return. 'NORMAL' means the vendor is expected to credit the goods. 'UNCREDITED_REPLACEMENT' means the vendor sends replacement goods, and the quantity can be received again on the purchase order line. 'UNINVOICED_CANCELLATION' means the quantity is canceled from the purchase order before it is invoiced. Possible values: 'NORMAL', 'UNCREDITED_REPLACEMENT', 'UNINVOICED_CANCELLATION'. |
| `items[].entityId` | string | yes | The unique identifier of the legal entity the purchase return belongs to. Format: UUID. See `id` on GET base/entities (entities). |
| `items[].entityName` | string | no | The name of the legal entity the purchase return belongs to. |
| `items[].businessPartnerId` | string | yes | The unique identifier of the vendor the goods go back to. Format: UUID. See `id` on GET accounting/vendors/:id (getVendor). |
| `items[].businessPartnerName` | string | no | The name of the vendor the goods go back to. |
| `items[].referenceNumber` | string | no | The reference number of the purchase return. |
| `items[].originalReceiptId` | string | no | The unique identifier of the receipt the purchase return was created against. Format: UUID. See `id` on GET inventory/receipts/:id (getReceipt). |
| `items[].currency` | string | no | The currency of the purchase return's amounts. Format: ISO 4217. |
| `items[].totalAmount` | decimal | no | The total value of the purchase return, in its currency. It is the sum, over all lines, of each line's `unitPrice` multiplied by its `quantity`. Absent until the purchase return is shipped. |
| `items[].notes` | string | no | Notes on the purchase return. |
| `items[].createdDate` | date-time | no | The date and time the purchase return was created, in UTC. Format: YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lastModifiedDate` | date-time | no | The date and time the purchase return last changed, in UTC. Format: YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lines` | array<object> | yes | The lines of the purchase return. |
| `items[].lines[].id` | string | yes | The unique identifier for the line. Format: UUID. Use it in `updateLines` and `deleteLines`. |
| `items[].lines[].itemId` | string | no | The unique identifier of the item being returned. Format: UUID. See `id` on GET inventory/items/:id (getItem). |
| `items[].lines[].itemCode` | string | no | The code of the item being returned. |
| `items[].lines[].itemName` | string | no | The name of the item being returned. |
| `items[].lines[].locationId` | string | no | The unique identifier of the warehouse that the stock on this line leaves from. Format: UUID. See `id` on GET inventory/warehouses/:id (getWarehouse). |
| `items[].lines[].locationCode` | string | no | The code of the warehouse that the stock on this line leaves from. |
| `items[].lines[].locationName` | string | no | The name of the warehouse that the stock on this line leaves from. |
| `items[].lines[].unitId` | string | no | The unique identifier of the unit of measure for the line's quantity. Format: UUID. See `id` on GET inventory/unit-of-measures/:id (getUnitOfMeasure). |
| `items[].lines[].unitCode` | string | no | The code of the unit of measure for the line's quantity. |
| `items[].lines[].quantity` | decimal | no | The quantity being returned, in the line's unit of measure. |
| `items[].lines[].inventoryQuantity` | decimal | no | The quantity being returned, in the item's stocking unit. |
| `items[].lines[].openQuantity` | decimal | no | The quantity of the line still outstanding, in the line's unit of measure. |
| `items[].lines[].unitPrice` | decimal | no | The price of one unit, in the purchase return's currency. |
| `items[].lines[].functionalUnitPrice` | decimal | no | The price of one unit, in the legal entity's functional currency. It is `functionalLineTotal` divided by `quantity`. Absent until the purchase return is shipped, and on lines whose `sourceDocumentLineType` is not 'PurchaseOrderLine'. |
| `items[].lines[].functionalLineTotal` | decimal | no | The total of the line, in the legal entity's functional currency. It is calculated from the receipts the quantity was taken from, at their original prices. Absent until the purchase return is shipped, and on lines whose `sourceDocumentLineType` is not 'PurchaseOrderLine'. |
| `items[].lines[].status` | string | no | The status of the line. It is 'PENDING' until the purchase return is shipped, and 'SHIPPED' after. |
| `items[].lines[].sourceDocumentLineId` | string | no | The unique identifier of the receipt line or purchase order line that this line returns goods from. Format: UUID. `sourceDocumentLineType` says whether it is a receipt line or a purchase order line. See `lines[].id` on GET inventory/receipts/:id (getReceipt) or GET accounting/purchase-orders/:id (getPurchaseOrder). |
| `items[].lines[].sourceDocumentLineType` | string | no | The type of line that `sourceDocumentLineId` points to. Possible values: 'InvPurchaseDeliveryLine' (a receipt line), 'PurchaseOrderLine' (a purchase order line). |
| `items[].lines[].notes` | string | no | Notes on the line. |
| `items[].lines[].batches` | array<object> | no | The batches being returned. |
| `items[].lines[].batches[].batchNumberId` | string | no | The unique identifier of the batch being returned. Format: UUID. See `id` on GET inventory/batch-numbers/:id (getBatchNumber). |
| `items[].lines[].batches[].batchNumber` | string | yes | The batch number of the batch being returned. |
| `items[].lines[].batches[].expirationDate` | date | no | The date the batch expires. Format: YYYY-MM-DD. See `expirationDate` on GET inventory/batch-numbers/:id (getBatchNumber). |
| `items[].lines[].batches[].quantity` | decimal | yes | The quantity of the batch being returned, in the item's stocking unit. |
| `items[].lines[].batches[].inventoryQuantity` | decimal | no | The quantity of the batch being returned, in the item's stocking unit. |
| `items[].lines[].batches[].unitCost` | decimal | no | The purchase return line's `unitPrice` when the batch was added to that line, in the purchase return's currency. It is per unit of the line's unit of measure, not per stocking unit like `quantity`. |
| `items[].lines[].serials` | array<object> | no | The serialized units being returned, one entry for each unit. |
| `items[].lines[].serials[].serialNumberId` | string | no | The unique identifier of the serialized unit being returned. Format: UUID. See `id` on GET inventory/serial-numbers/:id (getSerialNumber). |
| `items[].lines[].serials[].serialNumber` | string | yes | The serial number of the unit being returned. |
| `items[].lines[].serials[].unitCost` | decimal | no | The cost of the serialized unit, in the purchase return's currency. It is the purchase return line's `unitPrice` when the serialized unit was added to that line. |
| `items[].lines[].binLocations` | array<object> | no | The bins the stock on this purchase return line is taken from, with the quantity taken from each bin. An entry with a `batchNumber` or `serialNumber` is for that batch or serialized unit. An entry with neither is for part of the line's quantity, not a particular batch or serialized unit. |
| `items[].lines[].binLocations[].binLocationId` | string | yes | The unique identifier of the bin the stock is taken from. Format: UUID. See `id` on GET inventory/bins/:id (getBin). |
| `items[].lines[].binLocations[].binLocationCode` | string | no | The code of the bin the stock is taken from. |
| `items[].lines[].binLocations[].quantity` | decimal | yes | The quantity taken from the bin, in the item's stocking unit. |
| `items[].lines[].binLocations[].batchNumber` | string | no | The batch number of the batch this bin quantity is for. |
| `items[].lines[].binLocations[].serialNumber` | string | no | The serial number of the unit this bin quantity is for. |
| `items[].applications` | array<object> | no | The receipt lines that the returned quantity was taken from, for purchase return lines that return goods from a purchase order line. A purchase order line can be received on several receipts, so shipping records which receipt lines the quantity came from. Absent until the purchase return is shipped, and when no purchase return line returns goods from a purchase order line. |
| `items[].applications[].receiptLineId` | string | yes | The unique identifier of the receipt line the quantity was taken from. Format: UUID. See `lines[].id` on GET inventory/receipts/:id (getReceipt). |
| `items[].applications[].quantity` | decimal | yes | The quantity taken from the receipt line, in the purchase return line's unit of measure. |
| `items[].applications[].unitCost` | decimal | no | The cost of one unit of the quantity taken from the receipt line, in the purchase return line's unit of measure, as taken off the inventory's value (relieved) when the purchase return was shipped. It is `totalCost` divided by `quantity`, not rounded. |
| `items[].applications[].totalCost` | decimal | no | The cost of the whole quantity taken from the receipt line, as taken off the inventory's value (relieved) when the purchase return was shipped. |
| `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. |

```json
{
  "data": {
    "items": [
      {
        "id": "6a1f30c9-4d82-4b57-9e60-83c25f0a71b4",
        "documentNumber": "PRTR-1043",
        "documentStatus": "COMMITTED",
        "documentDate": "2026-08-20",
        "returnType": "NORMAL",
        "entityId": "1a9c4e70-38b5-4d26-9f01-7c2e5b8a6d43",
        "businessPartnerId": "b62e4f17-0c93-4a58-8d21-5f70e3b9a4c6",
        "currency": "EUR",
        "totalAmount": "96.00",
        "lines": [
          {
            "id": "8c14a6f2-3b70-4d59-9e02-6f5a1d38b47c",
            "itemId": "5f21c8b0-9d34-4a76-8e12-04b93c7de5a8",
            "quantity": "30.00"
          }
        ]
      }
    ],
    "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