PUT
Edit a purchase line
Company space For: Buyer, Manager · Permission: purchases.update, purchase_items.update Conditions
  • The purchase must be in draft or rejected status.
  • quantity, when sent, must be an integer of at least 1.
  • stockable_id and stockable_unit_id must be sent together; the unit must exist in the organization, belong to the item, be active, belong to a product variant and not be archived.
  • The unit cannot be the unit of another line of the same purchase.
  • unit_cost and vat_rate are refused when the purchase uses a single total cost (cost strategy total); under the unit strategy a sent unit_cost replaces the stored one.
  • When the resulting purchase has VAT greater than zero, vat_is_recoverable must have been set; otherwise the call is refused with a validation error.
What else happens
  • Changing quantity also resets remaining to the new quantity.
  • Recalculates the purchase totals (cost_total, vat_total, invoice_total, cost_leftover) and the unit_cost_ttc of every line.
  • No stock movement or accounting entry is created.
Part of Create and approve purchases.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

purchase
string
required

Identifier of the purchase that owns the line.

item
string
required

Identifier of the purchase line to change.

Query Parameters

response
enum<string>
default:none

Response mode. Default none; none answers 204 No Content.

Available options:
none,
resource
fields
string

Comma-separated JSON keys of the root resource (id is always rendered). Available: id, purchase_id, stockable_id, stockable_unit_id, quantity, remaining, unit_cost, vat_rate, vat_total, unit_cost_ttc, cost_total, cost_total_ttc, created_at, updated_at.

include
string

Comma-separated include paths, each optionally followed by its fields in parentheses: units(id,sku),units.uomUnit(id,name). Max depth 6, max 40 paths. Available: stockable, stockable.vat_rate, stockable.taxes, stockable.units, stockableUnit, stockableUnit.uomUnit, stockableUnit.prices, stockableUnit.stockable.

Body

application/json
stockable_id
string

New item (product variant) of the line; 27 characters. Required together with stockable_unit_id.

Required string length: 27
stockable_unit_id
string

New item unit of the line; 27 characters. Required together with stockable_id and must not be the unit of another line of the purchase.

Required string length: 27
quantity
integer

New quantity, an integer of at least 1. Resets remaining to this quantity.

Required range: x >= 1
unit_cost
number

New cost of one unit before VAT, in major units, greater than 0. Refused when the purchase has a single total cost.

vat_rate
number

New VAT rate in percent, from 0 to 100 with up to four decimals. Refused when the purchase has a single total cost; when omitted under the unit strategy the stored rate is kept.

Required range: 0 <= x <= 100

Response

Resource (only with response=resource).

id

Identifier of the purchase line (27-character KSUID).

purchase_id

Identifier of the purchase the line belongs to.

stockable_id

Identifier of the item (product variant) bought.

stockable_unit_id

Identifier of the item unit (unit of measure) bought; unique within a purchase.

stockable
object

The item bought. Present only when requested with include=stockable.

stockable_unit
object

The unit of the line. Present only when requested with include=stockableUnit.

quantity
integer

Quantity bought, in the line's unit.

remaining
integer

Quantity not yet received. Starts equal to quantity and is reset to quantity when the line is edited.

unit_cost
number

Cost of one unit before VAT. 0 under the total cost strategy, where costs are not entered per line. In major units (the stored minor-unit amount divided by 10 to the power currency_exponent).

vat_rate

VAT rate in percent with four decimals (for example "18.0000"); null under the total cost strategy.

vat_total
number | null

VAT of the line (unit cost times quantity times rate, rounded half up). Null under the total cost strategy. In major units (the stored minor-unit amount divided by 10 to the power currency_exponent).

unit_cost_ttc
number

Cost of one unit including VAT; under the total strategy the invoice total divided by the total quantity (integer division). In major units (the stored minor-unit amount divided by 10 to the power currency_exponent).

cost_total
number | null

Cost of the line before VAT (unit cost times quantity). Null under the total cost strategy. In major units (the stored minor-unit amount divided by 10 to the power currency_exponent).

cost_total_ttc
number

Cost of the line including VAT. In major units (the stored minor-unit amount divided by 10 to the power currency_exponent).

created_at

Date and time the record was created (ISO 8601, UTC).

updated_at

Date and time the record was last changed (ISO 8601, UTC).