---
title: "Lists the organization's purchase orders, oldest first, one page at a time."
method: GET
path: "/api/v1/purchase-orders"
tags: ["PurchaseOrders"]
---

# Lists the organization's purchase orders, oldest first, one page at a time.

`GET /api/v1/purchase-orders`

## Request

- Base URL: `https://app.flexonthejob.com`
- URL: `https://app.flexonthejob.com/api/v1/purchase-orders`
- Auth: HTTP bearer

Requires `ViewPurchaseOrders`. Deleted orders are never returned. Pagination: pass the
previous response's `nextCursor` as `after`; `limit` defaults to 50 and is
capped at 200. All filters combine with AND. Example:
`GET /api/v1/purchase-orders?status=Delivered&vendorId=7` lists what is waiting to be
received from vendor 7. Response carries a weak `ETag`; resend it as
`If-None-Match` to get 304 when nothing changed.
Also available as CSV (`Accept: text/csv` or `?format=csv`); paging cursor in `X-Next-Cursor`.

## Query parameters

- `status` string
- `vendorId` integer
- `updatedSince` string, date-time
- `after` string
- `limit` integer
- `format` 'csv'

## Response `200`

A page of purchase orders and the cursor for the next page (null on the last page).

- PagedResponseOfPurchaseOrderSummaryDto: One page of a cursor-paginated /api/v1 collection (API_AND_MCP.md: `?after=<syncId>&limit=`).
  - `items` PurchaseOrderSummaryDto[]: Items of this page in ascending creation order.
    - `id` integer: Numeric id used in `/api/v1/purchase-orders/{id}`. Unique within this organization. Example: `412`.
    - `syncId` string, uuid: Stable cross-device identifier (GUID) — also the pagination cursor value. Example: `3c9d1a2b-7e4f-4b6a-8c1d-5e6f7a8b9c0d`.
    - `orderNumber` string: The organization's purchase-order number. Example: `PO-ACME-20260915-01`.
    - `externalOrderNumber` string, nullable: The vendor's own order or confirmation number; null when not recorded. Example: `SO-88213`.
    - `status` string: Order status name, derived by the app from the order's shipments and received quantities. One of `Draft` (no shipment yet), `Ordered`, `Shipped`, `PartialShipped`, `Delivered` (at the receiving location, nothing received yet), `PartialReceived`, `Received` (every unit received and every shipment delivered), `Cancelled`.
    - `vendorId` integer, nullable: Id of the vendor record; null for a one-off vendor typed on the order.
    - `vendorName` string, nullable: Vendor name (the vendor record's name, else the one-off name on the order). Example: `Acme Supply`. Null when neither is set.
    - `orderDate` string, date-time: Order date as entered in the app: the organization's local calendar date, `yyyy-MM-ddT00:00:00` with no UTC offset (the `date-time` format here is a local date, not an RFC 3339 instant; do not convert it between time zones). Example: `2026-09-15T00:00:00`.
    - `expectedDeliveryDate` string, date-time, nullable: Expected delivery date as entered in the app, same local calendar-date format as `orderDate` (no UTC offset). Example: `2026-09-22T00:00:00`. Null when unknown.
    - `receivedDate` string, date-time, nullable: When the order became fully `Received`, ISO-8601 UTC; null until then.
    - `totalCost` number, double, nullable: Order total in `currency` as recorded on the order; null when not calculated. Example: `1249.50`.
    - `currency` string: ISO-4217 currency code of the prices on the order. Example: `USD`.
    - `receivingLocationId` integer: Id of the location stock is received at by default (see `/api/v1/locations`). Example: `10`.
    - `receivingLocationName` string, nullable: Name of `receivingLocationId`. Example: `Main Warehouse`.
    - `lineCount` integer: Number of lines on the order. Example: `3`.
    - `quantityOrdered` integer: Units ordered across all lines. Example: `40`.
    - `quantityReceived` integer: Units received across all lines. Example: `25`.
    - `createdAt` string, date-time: Creation time, ISO-8601 UTC. Example: `2026-09-15T14:05:00Z`.
    - `updatedAt` string, date-time, nullable: Last modification time (including a receipt), ISO-8601 UTC; null when never modified since creation.
  - `nextCursor` string, nullable: SyncId of the last item; pass it back as `?after=` to fetch the next page. `null` when this is the last page.

## Other responses

- `304`: Unchanged since the `If-None-Match` ETag.
- `400`: Unknown `status` or unusable `after` cursor (field listed in `errors`).
- `401`: Unauthorized
- `403`: Forbidden
- `429`: Too Many Requests

---

[API](https://skmtc.dev/flexonthejob/apis/flex-api.md) · [All operations](https://skmtc.dev/flexonthejob/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flexonthejob/apis/flex-api/revisions/19c8f4d27acf?raw)