List Purchase Orders

GET

/api/v1/purchase-orders

GET

/api/v1/purchase-orders

$ curl https://api.getply.com/api/v1/purchase-orders \
>      -H "API_KEY: <apiKey>"

1 {
2   "data": [
3     {
4       "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
5       "itemCount": 1,
6       "assignedUserIds": [
7         "e1f2a3b4-c5d6-7890-efab-901234567890"
8       ],
9       "orderNumber": "PO-1042",
10       "status": "DRAFT",
11       "type": "STANDARD",
12       "totalCost": 1250,
13       "subtotal": 1250,
14       "note": "Please ship to back warehouse entrance.",
15       "supplier": {
16         "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
17         "name": "Acme Supply Co."
18       },
19       "location": {
20         "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
21         "name": "Main Warehouse"
22       },
23       "dueDate": "2026-04-15",
24       "receivedAt": null,
25       "createdAt": "2026-03-20T14:30:00Z",
26       "updatedAt": "2026-03-20T14:30:00Z"
27     }
28   ],
29   "pagination": {
30     "page": 0,
31     "size": 20,
32     "totalElements": 1,
33     "totalPages": 1
34   }
35 }

Returns a paginated list of purchase orders for the authenticated business. Supports filtering by status, supplier, location, and creation date range.

Requires scope: purchase_orders: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 purchase order status.

supplierIdUUIDOptional

Filter by supplier ID.

locationIdUUIDOptional

Filter by destination location ID.

createdAfterdateOptional

Return only orders created on or after this date (ISO 8601, e.g. 2026-01-01).

createdBeforedateOptional

Return only orders created on or before this date (ISO 8601, e.g. 2026-03-31).

sortstringOptional

Sort by field,direction (Spring Pageable format; direction asc or desc, default asc). Allowed fields: id, orderNumber, status, type, totalCost, subtotal, note, dueDate, receivedAt, 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