Create a purchase order

Required API key scope: purchasing:write

Creates a new purchase order in draft status. You must identify the vendor using either vendor_id (the natural B2B convention, preferred) or account_id (legacy alias — both refer to the same vendor account UUID). If both are supplied, account_id takes precedence. At least one is required.

JSON body examples:

Shape A (preferred — vendor_id):

{
  "vendor_id": "df56267d-7890-41a2-a62c-ee8955aab150",
  "notes": "Q3 stock order"
}

Shape B (alias — account_id):

{
  "account_id": "df56267d-7890-41a2-a62c-ee8955aab150",
  "notes": "Q3 stock order"
}

POST /purchase-orders

Create a purchase order

cURL

curl --request POST \
  --url https://api.arcuserp.com/v1/purchase-orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "vendor_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "location_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "payment_term_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "expected_date": "2023-12-25",
  "notes": "<string>",
  "items": [
    {
      "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "quantity": 123,
      "unit_cost": 123
    }
  ]
}
'

201

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "object": "purchase_order",
  "entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "po_number": "<string>",
  "vendor_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "location_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "draft",
  "po_date": "2023-11-07T05:31:56Z",
  "expected_date": "2023-11-07T05:31:56Z",
  "subtotal": 123,
  "tax_total": 123,
  "shipping_total": 123,
  "po_total": 123,
  "currency": "USD",
  "notes": "<string>",
  "internal_notes": "<string>",
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "approved_total": 123,
  "approval_stale": true,
  "header_editability": {},
  "billed_total": 123,
  "unbilled_balance": 123
}

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.

Body

application/json

Either vendor_id or account_id is required (both refer to the same vendor account UUID). vendor_id is the preferred B2B convention; account_id is the legacy internal alias. If both are present, account_id wins.

vendor_id · string<uuid>

UUID of the vendor account (preferred field name -- matches B2B convention used throughout the purchasing API). Alias for account_id.

account_id · string<uuid>

UUID of the vendor account (legacy internal alias for vendor_id). Accepted for backward compatibility. If both vendor_id and account_id are provided, account_id takes precedence.

location_id · string<uuid>

payment_term_id · string<uuid>

expected_date · string<date>

notes · string

items · object[]

Show child attributes

Response

201

application/json

Created 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.

Show child attributes

billed_total · number · read-only

How much of this purchase order's commitment a vendor bill has already taken over: the sum of total over every linked bill in open, partial, paid or written_off. 0 when no bill has been raised, never null.

unbilled_balance · number · read-only

What the purchase order STILL commits the buyer to: max(order_total - billed_total, 0), cents-quantized. Read this rather than balance_due, which on a purchase order is the ORIGINAL COMMITMENT the header was raised for and is never decremented when a bill is raised (the payable is the bill). Clamped at zero because a vendor may add freight on the bill and over-bill the order.