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

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): one of the FreeOfChargeReasonEnum cases.

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

Request​

Responses​

Successful response