POST
Create a purchase delivery
Company space For: Buyer, Stock keeper · Permission: purchase_deliveries.create Conditions
  • The purchase must have the status pending; any other status is refused with 409 (a pending purchase is one whose supplier invoice is recognized).
  • purchase_id and additional_cost_strategy are required; additional_cost_strategy is average or prorata.
  • reference, when sent, must not already be used by another reception of the company (pickups and deliveries share the same references).
  • cash_register_id, when sent, must be a cash register of the company that has a cash account.
  • items, when sent, must hold at least one line and each line follows the delivery/pickup line rules (see the line endpoints); item_id values must be distinct inside the request.
  • Each costs entry needs a key (up to 250 characters) and a value of 0 or more, in major units with at most the currency’s decimals.
  • recoverable_vat_total and vat_total are refused: supplier invoice tax belongs to the purchase, not to the reception.
  • asset_id must be an existing, active location asset available to the current company and not restricted for the current member; otherwise the call is refused with 422.
  • item_id must be a line of the purchase this reception belongs to; a line of another purchase is refused with 422.
  • The purchase unit of the line must still be active.
  • quantity must be greater than 0 and may not exceed the quantity still to receive on that purchase line. Quantities of other draft receptions are not reserved, so the same remainder can be planned twice and is only enforced again at confirmation.
  • A purchase line can appear only once per reception (item_id is unique inside the reception; deleted lines are really removed, so they no longer count).
  • damaged_quantity is counted in the damage unit (the purchase unit when damage_stockable_unit_id is omitted) and must be between 0 and the received quantity expressed in that unit; the received quantity must convert exactly into that unit.
  • damage_stockable_unit_id, when sent, must be an active unit of the same product and the same unit category as the purchase line.
  • damage_reason, damage_cost_treatment and damage_stockable_unit_id are refused when damaged_quantity is 0; damage_reason and damage_cost_treatment are required when damaged_quantity is above 0.
  • damage_cost_treatment “absorbed_by_remaining_stock” is refused when every received unit is damaged, because no accepted stock would remain to absorb the cost.
  • cost_total cannot be sent; it is computed by the server.
  • delivery_rate_id, when sent, must be an active delivery rate of the same supplier as the purchase.
  • delivery_fee and delivery_fee_label are refused when delivery_rate_id is sent: a delivery uses either a predefined rate or a custom fee. Sending neither means a free delivery. delivery_fee is in major units, 0 or more.
  • delivery_fee_paid_by_company defaults to true when omitted.
  • Nested lines accept asset_id, item_id, quantity, damaged_quantity, damage_reason and damage_cost_treatment; damage_stockable_unit_id is also accepted.
What else happens
  • Creates the delivery in the draft status with received_at empty and purchase_cost_leftover at 0.
  • Copies the chosen delivery rate’s amount and label into the delivery as a snapshot; later changes to the rate do not change it.
  • Creates the nested items and costs when they are sent. Nothing is added to stock and the purchase is not changed.
Part of Receive purchased goods.

Authorizations

Authorization
string
header
required

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

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, type, purchase_id, cash_register_id, reference, status, additional_cost_strategy, delivery_rate_id, delivery_fee, delivery_fee_label, delivery_fee_paid_by_company, purchase_cost_leftover, received_at, expected_at, notes, 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: items, items.item, items.damageStockableUnit, costs.

Response

Resource (only with response=resource).

id

Identifier of the reception (27-character KSUID).

type

Kind of reception: "delivery" here. Set by the server from the route.

purchase_id

Identifier of the purchase this reception brings goods for. Set at creation and not changeable.

cash_register_id

Cash register recorded on the reception, or null. It must belong to the current company and organization and have a cash account. It is only stored.

reference

Optional free reference, unique among the company's receptions (pickups and deliveries together). Null when none.

status

State of the reception: draft (being prepared), in_transit (deliveries only: the supplier's truck is on its way, still editable) or confirmed (goods received, stock added). Set by the server.

additional_cost_strategy

How the extra costs are spread over the lines at confirmation: average (equally) or prorata (in proportion to each line's base cost).

delivery_rate_id

Identifier of the supplier's predefined delivery rate the fee was copied from, or null for a custom fee or a free delivery.

delivery_fee
number | null

Delivery fee in major units, copied from the rate or entered as a custom fee. Null when the delivery is free. It is added to the landed cost spread over the lines at confirmation.

delivery_fee_label

Label of the delivery fee (copied from the rate, or custom), or null.

delivery_fee_paid_by_company
boolean

true (default) when the company pays the fee itself; false when the fee is owed to the supplier and added to the purchase's payable once the delivery is confirmed.

purchase_cost_leftover
number

Rounding leftover of the purchase's cost that was added to this reception's lines at confirmation, in major units. 0 until the reception is confirmed.

received_at

Date and time of confirmation (ISO 8601). Null until the reception is confirmed.

expected_at

Date the goods are expected (YYYY-MM-DD), or null.

notes

Free notes, or null.

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

items
array

Lines of the reception. Present only when requested with include=items.

costs
array

Extra costs of the reception. Present only when requested with include=costs.