Edit a purchase order line item in place
Edits an existing purchase-order line’s quantity, unit_cost, and/or
notes IN PLACE — instead of deleting and re-adding the line. This
preserves the line’s order_item.id continuity (the FK target of any
receipt history), the PO revision_count semantics, the per-line
activity trail, and the 3-way-match baseline.
Editable fields are quantity, unit_cost, and notes only. To change
which product a line is for, delete the line and add a new one
(a product swap is a different line, not an edit).
Eligibility:
- 422
po_pending_approval_edit_lockedif the PO is awaiting approval. - 422
po_status_lockedif the PO iscancelled,fulfilled,archived, orexpired. - 422
qty_below_receivedif the newquantityis below the quantity already received against the line (the body carriesreceived_total,requested_qty, and ahint).
Side effects (THE ONE RULE — same canonical handler as the in-app edit):
adjusts the on_purchase_order cache by the net unreceived-quantity
delta, recomputes the PO header total, bumps revision_count on a sent
PO when a vendor-visible field (quantity or unit_cost) changes,
emits purchase_order.updated + purchase_order_line.updated (and
purchase_order.revised when revised) broadcasts (Rule 13), and writes a
po_line_updated activity entry with the changed fields and prior values
(Rule 20).
purchasing:writeAuthorizations
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.
Headers
Optional idempotency key for safe retries (Stripe-style).
255Path Parameters
The purchase order id.
The PO line item (order_item) id to edit.
Body
New quantity ordered. Must be a positive integer and >= the quantity already received.
x >= 1New unit cost. Mirrored onto the line's sell rate / list price and re-totals the line.
x >= 0Per-line internal note (vendor-internal; does not bump the PO revision).
Response
Line item updated. Returns the updated line plus the new revision_count (null on a draft / unsent PO).
A line item on an order. Sub-resource of Order.
Multi-tenant scoping column (Layer 1 isolation). Set automatically
from the parent orders.entity_id and enforced by Postgres trigger
trg_order_items_entity_parity (P0-ENTITY-ID-CHILD-TABLES, 2026-05-18).
Cross-tenant writes are rejected at the database layer.
Canonical Arcus per-unit price column (matches order_items.sell_rate).
Public-API alias of sell_rate (Stripe/Shopify/QuickBooks convention). Always populated on read; equal to sell_rate. Set per NEW-GAP-API-V1-CALLER-UNIT-PRICE-SILENTLY-OVERRIDDEN 2026-05-17 closure.
Per-unit pricing-rule savings (list_price minus sell_rate, positive magnitude). Already baked into sell_rate (and therefore line_subtotal) per ASC 606 transaction-price pricing; surfaced for the gross-to-net bridge display, never re-subtracted.
Per-line allocated coupon/order-level discount (signed; negative for a discount). Reflected in line_subtotal.
Per-line, per-source adjustment breakdown from order_item_adjustments (the canonical SSOT). Each entry attributes a signed line_amount to a source (pricing_rule | order_adjustment | coupon | manual_line_override | return_refund_adjust | restocking_fee). Empty array for lines with no allocations (and on legacy orders predating the writer). Industry parity: Shopify Admin GraphQL LineItem.discountAllocations[].
For purchase_order document_type lines only: exact product_vendors
row this line is bound to (NEW-GAP-ORDER-ITEMS-PRODUCT-VENDOR-ID-PROVENANCE,
2026-05-14). NULL for legacy PO lines and all non-PO doc types; PDF
falls back to the deterministic default-vendor-part pick.

