List purchase returns

Operation ID: purchaseReturns

Group: Inventory › Purchase Returns

Open in the interactive reference

GET /inventory/purchase-returns

Read-only: Reads and returns; changes nothing.

Lists purchase returns, with their header fields only. To get the lines of the purchase returns, or to filter by item or warehouse, use POST inventory/purchase-returns/search.

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.

Query surface

Response

200 Success

Under data, an array of purchaseReturnsRow:

Field Type Required Filter Sort Description
id string no Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn), Pattern (like) yes The unique identifier for the purchase return. Format: UUID.
documentNumber string | null no Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn), Pattern (like) yes The purchase return number, for example 'PRTR-1043'.
documentStatus string no Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn), Pattern (like) yes The status of the purchase return. Possible values: 'DRAFT', 'APPROVED', 'PREPARED', 'SHIPPED', 'COMMITTED', 'VENDOR_ACKNOWLEDGED', 'CREDITED', 'COMPLETED', 'CANCELLED'.
documentDate date no Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn) yes The date of the purchase return. Format: YYYY-MM-DD.
deliveryDate date | null no Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn) yes The delivery date of the purchase return. Format: YYYY-MM-DD.
returnType string | null no Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn), Pattern (like) 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'.
entityId string no Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn), Pattern (like) no The unique identifier of the legal entity the purchase return belongs to. Format: UUID. See id on GET base/entities (entities).
entityName string | null no no no The name of the legal entity the purchase return belongs to.
businessPartnerId string no no no The unique identifier of the vendor the goods go back to. Format: UUID. See id on GET accounting/vendors/:id (getVendor).
businessPartnerName string | null no no no The name of the vendor the goods go back to.
referenceNumber string | null no no no The reference number of the purchase return.
currency string | null no no no The currency of the purchase return's amounts. Format: ISO 4217, for example 'EUR'.
totalAmount decimal | null no no yes 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.
lineCount number | null no no no The number of lines on the purchase return.
notes string | null no no no Notes on the purchase return.
createdDate date-time | null no no yes The date and time the purchase return was created, in UTC. Format: YYYY-MM-DDTHH:mm:ss.sssZ.
lastModifiedDate date-time | null no Exact (eq, ne), Range (gt, gte, lt, lte, between), Any of (in, notIn) yes The date and time the purchase return last changed, in UTC. Format: YYYY-MM-DDTHH:mm:ss.sssZ. 
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "documentNumber": "<documentNumber>",
      "documentStatus": "<documentStatus>",
      "documentDate": "2026-01-15",
      "deliveryDate": "2026-01-15",
      "returnType": "<returnType>",
      "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "entityName": "<entityName>",
      "businessPartnerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "businessPartnerName": "<businessPartnerName>",
      "referenceNumber": "<referenceNumber>",
      "currency": "<currency>",
      "totalAmount": "19.99",
      "lineCount": 0,
      "notes": "<notes>",
      "createdDate": "2026-01-15T09:30:00.000Z",
      "lastModifiedDate": "2026-01-15T09:30:00.000Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "<nextCursor>"
  }
}

Statuses