Skip to main content

Update PO Line

PATCH 
/api/purchase-order-lines/:purchase_order_line

Update a single purchase order line. Designed for the PO grid's inline-edit interactions (tax rate, quantity, unit cost, discount, description, FOC toggle, nominal code).

Required scope: purchase-orders:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Authentication: Requires Bearer token.

Concurrency: Shares the per-PO Redis lock used by PATCH /api/purchase-orders/:purchase_order so concurrent edits on the same purchase order serialize rather than collide. The endpoint will wait up to 10 seconds for the lock; if it cannot acquire it, returns 409.

Request body (all fields optional — only sent fields are touched):

  • quantity (numeric, min 0, < 10000000): new ordered quantity. Validated against received_quantity and invoice_total — cannot drop below either.
  • amount (numeric, min 0, < 10000000): unit cost.
  • description (nullable string, max 255): free-text override for the product name on this line.
  • tax_rate_id (nullable integer, exists in tax_rates): set or clear the tax rate. When cleared, tax_allocation is reset to 0.
  • discount (nullable numeric, 0–100): percentage discount. Stored as discount_rate (e.g. 25 → 0.25).
  • nominal_code_id (nullable integer, exists in nominal_codes).
  • is_free_of_charge (boolean): toggle the FOC flag.
  • free_of_charge_reason (nullable enum, required when is_free_of_charge=true): the reason the line is free of charge.
  • country_of_origin (nullable ISO 3166-1 alpha-2): line-level country of origin for the customs duty estimate; overrides the product's country of origin. Null falls back to the product.
  • claims_preference (boolean): claim a preferential (trade-agreement) duty rate for this line when one exists for its code and origin.

Changing country_of_origin or claims_preference marks the line's duty estimate stale so it is recalculated.

Side effects:

  • Recomputes tax_allocation whenever the tax rate or any subtotal input (quantity/amount/discount) changes.
  • Recomputes the parent PO's total_cost and total_quantity.
  • Refreshes the PO's receipt_status when the quantity changes.
  • When the quantity is reduced, excess awaiting-receipt inventory allocations on this line are reverted so the next coverage sync can rebalance them.

Returns the refreshed purchase order line object.

Requires permission: purchase_orders.update

Request​

Responses​

OK

Response Headers
    Content-Type