List Returns | Ply | API Documentation

{
  "data": [
    {
      "id": "d6e7f8a9-b0c1-2345-defa-678901234567",
      "status": "DRAFT",
      "itemCount": 1,
      "assignedUserIds": [],
      "returnNumber": "RET-1001",
      "purchaseOrder": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "PO-2045"
      },
      "location": {
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "name": "Main Warehouse"
      },
      "trackingNumber": null,
      "note": "3 pipes arrived damaged.",
      "totalMaterialsCost": 75,
      "totalFees": 0,
      "finalPrice": 75,
      "returnDate": "2026-03-25",
      "createdAt": "2026-03-20T10:00:00",
      "updatedAt": "2026-03-20T10:00:00"
    }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1
  }
}

Returns a paginated list of returns for the authenticated business. Optionally filter by status or purchase order.

Requires scope: returns:read

Authentication

API_KEYstring

API Key authentication via header

Query parameters

pageintegerOptional

Zero-based page index. Defaults to 0.

sizeintegerOptional

Items per page. Defaults to 20, maximum 100.

statusenumOptional

Filter by return status.

Allowed values:

purchaseOrderIdUUIDOptional

Filter by purchase order ID.

sortstringOptional

Sort by field,direction (Spring Pageable format; direction asc or desc, default asc). Allowed fields: id, returnNumber, status, trackingNumber, note, returnDate, createdAt, updatedAt. Default order (when no sort is supplied): createdAt,desc.

Response

This endpoint returns an object.

datalist of objects

paginationobject

Pagination metadata returned on all list endpoints.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

429

Rate Limit Error