# Retrieve a purchase return

Operation ID: `getPurchaseReturn`

Group: Inventory › Purchase Returns

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

`GET /inventory/purchase-returns/{id}`

Read-only: Reads and returns; changes nothing.

Retrieves a purchase return, with its 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`. |
| `id` | path | string | yes | The unique identifier of the purchase return you want to retrieve. Format: UUID. Example: `"6a1f30c9-4d82-4b57-9e60-83c25f0a71b4"`. |

## Response

`200` Success

Under `data` (getPurchaseReturnOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The unique identifier for the purchase return. Format: UUID. Example: `"6a1f30c9-4d82-4b57-9e60-83c25f0a71b4"`. |
| `documentNumber` | string | no | The purchase return number, for example 'PRTR-1043'. Example: `"PRTR-1043"`. |
| `documentStatus` | string | yes | The status of the purchase return. Possible values: 'DRAFT', 'APPROVED', 'PREPARED', 'SHIPPED', 'COMMITTED', 'VENDOR_ACKNOWLEDGED', 'CREDITED', 'COMPLETED', 'CANCELLED'. Example: `"COMMITTED"`. |
| `documentDate` | date | yes | The date of the purchase return. Format: YYYY-MM-DD. Example: `"2026-08-20"`. |
| `deliveryDate` | date | no | The delivery date of the purchase return. Format: YYYY-MM-DD. |
| `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'. Example: `"NORMAL"`. |
| `entityId` | string | yes | The unique identifier of the legal entity the purchase return belongs to. Format: UUID. See `id` on GET base/entities (entities). Example: `"1a9c4e70-38b5-4d26-9f01-7c2e5b8a6d43"`. |
| `entityName` | string | no | The name of the legal entity the purchase return belongs to. Example: `"Acme Netherlands B.V."`. |
| `businessPartnerId` | string | yes | The unique identifier of the vendor the goods go back to. Format: UUID. See `id` on GET accounting/vendors/:id (getVendor). Example: `"b62e4f17-0c93-4a58-8d21-5f70e3b9a4c6"`. |
| `businessPartnerName` | string | no | The name of the vendor the goods go back to. Example: `"Van Dijk Components B.V."`. |
| `referenceNumber` | string | no | The reference number of the purchase return. Example: `"RMA-4471"`. |
| `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). |
| `currency` | string | no | The currency of the purchase return's amounts. Format: ISO 4217, for example 'EUR'. Example: `"EUR"`. |
| `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. Example: `"96.00"`. |
| `notes` | string | no | Notes on the purchase return. Example: `"Damaged in transit"`. |
| `createdDate` | date-time | no | The date and time the purchase return was created, in UTC. Format: YYYY-MM-DDTHH:mm:ss.sssZ. Example: `"2026-08-20T09:20:00.000Z"`. |
| `lastModifiedDate` | date-time | no | The date and time the purchase return last changed, in UTC. Format: YYYY-MM-DDTHH:mm:ss.sssZ. Example: `"2026-08-20T11:05:00.000Z"`. |
| `lines` | array<object> | yes | The lines of the purchase return. Example: `[{"id":"8c14a6f2-3b70-4d59-9e02-6f5a1d38b47c","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","unitId":"3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45","unitCode":"EA","quantity":"30.00","inventoryQuantity":"30.00","unitPrice":"3.20","functionalUnitPrice":"3.20","functionalLineTotal":"96.00","sourceDocumentLineId":"a3e7c915-62d4-4f08-b1a9-7d5c24e8f063","sourceDocumentLineType":"PurchaseOrderLine","notes":"Cracked casings"}]`. |
| `lines[].id` | string | yes | The unique identifier for the line. Format: UUID. Use it in `updateLines` and `deleteLines`. |
| `lines[].itemId` | string | no | The unique identifier of the item being returned. Format: UUID. See `id` on GET inventory/items/:id (getItem). |
| `lines[].itemCode` | string | no | The code of the item being returned. |
| `lines[].itemName` | string | no | The name of the item being returned. |
| `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). |
| `lines[].locationCode` | string | no | The code of the warehouse that the stock on this line leaves from. |
| `lines[].locationName` | string | no | The name of the warehouse that the stock on this line leaves from. |
| `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). |
| `lines[].unitCode` | string | no | The code of the unit of measure for the line's quantity. |
| `lines[].quantity` | decimal | no | The quantity being returned, in the line's unit of measure. |
| `lines[].inventoryQuantity` | decimal | no | The quantity being returned, in the item's stocking unit. |
| `lines[].openQuantity` | decimal | no | The quantity of the line still outstanding, in the line's unit of measure. |
| `lines[].unitPrice` | decimal | no | The price of one unit, in the purchase return's currency. |
| `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'. |
| `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'. |
| `lines[].status` | string | no | The status of the line. It is 'PENDING' until the purchase return is shipped, and 'SHIPPED' after. |
| `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). |
| `lines[].sourceDocumentLineType` | string | no | The type of line that `sourceDocumentLineId` points to. Possible values: 'InvPurchaseDeliveryLine' (a receipt line), 'PurchaseOrderLine' (a purchase order line). |
| `lines[].notes` | string | no | Notes on the line. |
| `lines[].batches` | array<object> | no | The batches being returned. |
| `lines[].batches[].batchNumberId` | string | no | The unique identifier of the batch being returned. Format: UUID. See `id` on GET inventory/batch-numbers/:id (getBatchNumber). |
| `lines[].batches[].batchNumber` | string | yes | The batch number of the batch being returned. |
| `lines[].batches[].expirationDate` | date | no | The date the batch expires. Format: YYYY-MM-DD. See `expirationDate` on GET inventory/batch-numbers/:id (getBatchNumber). |
| `lines[].batches[].quantity` | decimal | yes | The quantity of the batch being returned, in the item's stocking unit. |
| `lines[].batches[].inventoryQuantity` | decimal | no | The quantity of the batch being returned, in the item's stocking unit. |
| `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`. |
| `lines[].serials` | array<object> | no | The serialized units being returned, one entry for each unit. |
| `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). |
| `lines[].serials[].serialNumber` | string | yes | The serial number of the unit being returned. |
| `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. |
| `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. |
| `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). |
| `lines[].binLocations[].binLocationCode` | string | no | The code of the bin the stock is taken from. |
| `lines[].binLocations[].quantity` | decimal | yes | The quantity taken from the bin, in the item's stocking unit. |
| `lines[].binLocations[].batchNumber` | string | no | The batch number of the batch this bin quantity is for. |
| `lines[].binLocations[].serialNumber` | string | no | The serial number of the unit this bin quantity is for. |
| `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. Example: `[{"receiptLineId":"6b02f4d8-91c3-4e57-a8f6-3c1d9e70b254","quantity":"20.00","unitCost":"3.20","totalCost":"64.00"},{"receiptLineId":"d81a5c37-0f6e-4b92-9c24-e5f7a3b18d06","quantity":"10.00","unitCost":"3.20","totalCost":"32.00"}]`. |
| `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). |
| `applications[].quantity` | decimal | yes | The quantity taken from the receipt line, in the purchase return line's unit of measure. |
| `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. |
| `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. |

```json
{
  "data": {
    "id": "6a1f30c9-4d82-4b57-9e60-83c25f0a71b4",
    "documentNumber": "PRTR-1043",
    "documentStatus": "COMMITTED",
    "documentDate": "2026-08-20",
    "deliveryDate": "2026-01-15",
    "returnType": "NORMAL",
    "entityId": "1a9c4e70-38b5-4d26-9f01-7c2e5b8a6d43",
    "entityName": "Acme Netherlands B.V.",
    "businessPartnerId": "b62e4f17-0c93-4a58-8d21-5f70e3b9a4c6",
    "businessPartnerName": "Van Dijk Components B.V.",
    "referenceNumber": "RMA-4471",
    "originalReceiptId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "currency": "EUR",
    "totalAmount": "96.00",
    "notes": "Damaged in transit",
    "createdDate": "2026-08-20T09:20:00.000Z",
    "lastModifiedDate": "2026-08-20T11:05:00.000Z",
    "lines": [
      {
        "id": "8c14a6f2-3b70-4d59-9e02-6f5a1d38b47c",
        "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",
        "unitId": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45",
        "unitCode": "EA",
        "quantity": "30.00",
        "inventoryQuantity": "30.00",
        "unitPrice": "3.20",
        "functionalUnitPrice": "3.20",
        "functionalLineTotal": "96.00",
        "sourceDocumentLineId": "a3e7c915-62d4-4f08-b1a9-7d5c24e8f063",
        "sourceDocumentLineType": "PurchaseOrderLine",
        "notes": "Cracked casings"
      }
    ],
    "applications": [
      {
        "receiptLineId": "6b02f4d8-91c3-4e57-a8f6-3c1d9e70b254",
        "quantity": "20.00",
        "unitCost": "3.20",
        "totalCost": "64.00"
      },
      {
        "receiptLineId": "d81a5c37-0f6e-4b92-9c24-e5f7a3b18d06",
        "quantity": "10.00",
        "unitCost": "3.20",
        "totalCost": "32.00"
      }
    ]
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}
```

## Errors

| Code | Status |
| --- | --- |
| `NOT_FOUND` | 400 |

## Statuses

- `400` — Invalid request or business failure. Codes: NOT_FOUND
- `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