---
title: "Retrieve a paginated list of purchase orders"
method: GET
path: "/purchase-orders"
tags: ["purchaseOrders"]
---

# Retrieve a paginated list of purchase orders

`GET /purchase-orders`

Returns a paginated list of purchase orders, filterable by company, location, vendor, status, and date range.

## Query parameters

- `ottimate_company_id` integer
- `ottimate_location_id` integer
- `erp_vendor_id` string
- `status` 'pending' | 'open' | 'received' | 'closed' | 'flagged' | 'archived' | 'deleted'
- `date_from` string, date
- `date_to` string, date
- `expand` string
- `external_id` string
- `page` integer
- `limit` integer

## Headers

- `Authorization` string, required
- `X-Api-Key` string, required
- `X-API-Version` string

## Response `200`

Successful response with paginated purchase order list

- PurchaseOrdersGetPurchaseOrdersRootResponse200
  - `version` string
  - `count` integer
  - `page` integer
  - `limit` integer
  - `purchase_orders` PurchaseOrderSummary[]
    - `id` string, required
    - `external_id` string — External unique identifier for idempotent operations
    - `po_number` string — PO number (client-provided, mandatory)
    - `status` 'pending' | 'open' | 'received' | 'closed' | 'flagged' | 'archived' | 'deleted', required
    - `ottimate_location_id` integer
    - `ottimate_company_id` integer
    - `date` string, date
    - `erp_vendor_id` string — External vendor identifier from ERP system
    - `erp_vendor_name` string — Vendor name from ERP system
    - `total_amount` number, double
    - `created_date` string, date-time
    - `created_date_utc` string, date-time, nullable — UTC equivalent of created_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z".
    - `last_modified_date` string, date-time
    - `last_modified_date_utc` string, date-time, nullable — UTC equivalent of last_modified_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z".
    - `custom_fields` PurchaseOrderSummaryCustomFields — Custom fields configured for this company's purchase orders

## Other responses

- `400` — Bad request - Invalid parameters or request format
- `401` — Unauthorized - Authentication required or invalid credentials
- `403` — Forbidden - Access denied or insufficient permissions

## Changes

- **2026-08-27** `ba91ff4c6969` — 4 breaking, 6 info
  - removed the enum value `approved` from the `query` request parameter `status`
  - removed the enum value `pending_review` from the `query` request parameter `status`
  - removed the enum value `rejected` from the `query` request parameter `status`
  - the `purchase_orders/items/id` response's property type/format changed from `string`/`uuid` to `string`/`` for status `200`
  - …6 more
- **2026-08-19** `c0b5cf6c7a72` — 1 info
  - added the non-success response with the status `403`
- **2026-08-17** `c231509a03cf` — 4 breaking, 4 info
  - for the `query` request parameter `limit`, default value `20` was added
  - for the `query` request parameter `page`, default value `1` was added
  - the `message` response's property type/format changed from `string`/`` to ``/`` for status `400`
  - the `message` response's property type/format changed from `string`/`` to ``/`` for status `401`
  - …4 more
- **2026-08-13** `1f089f3e34d9` — 6 breaking
  - the response property `code` became optional for the status `400`
  - the response property `code` became optional for the status `401`
  - the response property `message` became optional for the status `400`
  - the response property `message` became optional for the status `401`
  - …2 more

[Change history](https://skmtc.dev/ottimate/apis/api-reference/changes/purchase-orders/get.md)

---

[API](https://skmtc.dev/ottimate/apis/api-reference.md) · [All operations](https://skmtc.dev/ottimate/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ottimate/api-reference/revisions/ba91ff4c6969/schema)