Retrieve a purchase return

Operation ID: getPurchaseReturn

Group: Inventory › Purchase Returns

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.

{
  "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