Search purchase returns

Operation ID: searchPurchaseReturns

Group: Inventory › Purchase Returns

Open in the interactive reference

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