POST
Add purchase lines
Company space For: Buyer, Manager · Permission: purchases.update, purchase_items.create Conditions
  • The purchase must be in draft or rejected status.
  • The items array is required and must hold at least one line; each line needs stockable_id, stockable_unit_id (27 characters each) and an integer quantity of at least 1.
  • Each stockable_unit_id must be distinct within the request and must not already be a line of the purchase.
  • Each unit must exist in the organization, belong to the given item, be active, belong to a product variant and not be archived.
  • When the purchase prices its lines per unit (cost strategy unit), every line must carry unit_cost; vat_rate is optional and defaults to 0.
  • When the purchase has a single total cost (cost strategy total), unit_cost and vat_rate are refused on every line.
  • 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
  • Inserts the lines with remaining equal to quantity, then recalculates the purchase totals and the per-unit cost of every line.
  • Under the unit strategy cost_total, vat_total and invoice_total are recomputed from the lines; under the total strategy the invoice total is spread over all units and the integer remainder is kept in cost_leftover.
  • 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 to add lines to.

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
items
object[]
required

Lines to add; at least one.

Minimum array length: 1

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