Skip to main content
GET
Retrieve a purchase order

Authorizations

Authorization
string
header
required

API key issued per entity via Settings > Developers > API Keys. Each key carries scopes (e.g. orders:read, products:write). Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity
via Settings > Developers > API Keys.

Path Parameters

id
string
required

Purchase order UUID or PO number (e.g. PO-001234). Polymorphic lookup: if the value is not a UUID it is resolved to a UUID via orders.order_number where document_type=purchase_order within the entity scope. (NEW-GAP-API-V1-POLYMORPHIC-LOOKUP-CROSS-RESOURCE 2026-05-20)

Query Parameters

expand[]
enum<string>[]
Available options:
line_items,
line_items.product,
vendor,
receipts,
bills

Response

Purchase order

A purchase order issued to a vendor.

id
string<uuid>
object
enum<string>
Available options:
purchase_order
entity_id
string<uuid>
read-only
po_number
string
read-only
vendor_id
string<uuid>
location_id
string<uuid> | null
status
enum<string>
read-only
Available options:
draft,
approved,
sent,
partially_received,
received,
closed,
cancelled
po_date
string<date-time>
expected_date
string<date-time> | null
subtotal
number
tax_total
number
shipping_total
number
po_total
number
currency
string
default:USD
notes
string | null
internal_notes
string | null
metadata
object | null
created_at
string<date-time>
read-only
updated_at
string<date-time>
read-only
approved_total
number | null
read-only

The order total as it stood when an approver approved this purchase order -- the basis they actually saw. NULL on every approval predating 2026-08-17 (no backfill) and NULL means "basis unknown", which is treated as fail-safe.

approval_stale
boolean
read-only

DERIVED, not stored. True when the order is approved AND its total has since risen above approved_total. The purchase order still receives normally; this is a non-blocking prompt to re-approve.

header_editability
object
read-only

Per-field verdicts for the header fields, from the same predicate the write handlers enforce. Keys: notes, internal_notes, due_date, expected_date, location_id, po_tracking_reference. Each is { allowed: boolean, reason: string|null } where reason is a token from the PoLineEditReason vocabulary.