Update a line item quantity or notes
Updates mutable fields on an order line item: quantity, sell_rate (price override),
discount_amount, discount_percent, tax_rate_id, and notes. Triggers
fullRecalculateOrder to recompute order totals after change. Returns 404 if the
item does not belong to the specified order. Requires orders:write scope.
Editing a line on a CLOSED AR document is blocked: cancelled/voided, posted/fulfilled
(suggested_action: create_return), or billed-and-paid / fully-paid (invoice_status
in paid/overdue or payment_status = paid; suggested_action: revise_order). To
revise a paid order, pass override: true with the orders.revision_override permission;
the edit proceeds, revision_count increments, and the override is audited.
Authorizations
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
Client-generated unique key for idempotent POST/PATCH/DELETE operations. Alias for the Idempotency parameter. Max 255 chars. On retry with the same key, the original response is returned without re-executing the operation. Keys expire after 24 hours.
255Body
x >= 1Override unit price (canonical Arcus field).
Alias of sell_rate (Stripe/Shopify convention). Conflict / invalid handled identically to add. Triggers warnings entries plus order.price_override audit when applied price differs from catalog.
Set true (with the orders.revision_override permission) to revise a paid/billed order. Without it, a paid/billed order returns 422 edit_not_allowed (suggested_action revise_order).
Optional reason recorded in the audit log when override is used.
Response
Updated order item. Response includes unit_price alias. When override detected, response carries warnings array entries.
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.

