PUT
Change a purchase return item
Company space For: Buyer, Stock keeper · Permission: purchase_return_items.update, purchase_returns.update Conditions
  • Both purchase_return_items.update and purchase_returns.update are needed.
  • The supplier return must still be a draft.
  • purchase_item_id cannot be changed: it is refused.
  • Omitted fields keep their current value, so changing the quantity without sending stock_sources re-checks the existing sources against the new quantity and refuses a mismatch.
  • The quantity, unit and stock sources follow the same checks as when adding an item, counting the other returns of the purchase but not this line.
What else happens
  • Recomputes the cost_total of the line. Stock does not move until the return is confirmed.
Part of Return goods to suppliers.

Authorizations

Authorization
string
header
required

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

Path Parameters

purchase_return
string
required

Identifier of the purchase return (27-character KSUID string).

item
string
required

Identifier of the supplier return item (27-character KSUID string).

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, return_id, purchase_item_id, stockable_unit_id, stock_sources, quantity, cost_total, stock_cost_total, 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: purchaseItem, purchaseItem.stockable, purchaseItem.stockableUnit, stockableUnit, stockableUnit.uomUnit, stockableUnit.prices, stockableUnit.stockable.

Body

application/json
purchase_item_id
string
required

Identifier of the purchase line to return (27-character KSUID string). Required when adding a line; it must belong to the return's purchase and appear only once on the return. Not accepted when changing a line.

quantity
integer
required

Quantity to return, in the chosen unit, above zero. Required when adding a line. It cannot exceed what was received, accepted and not already returned.

stockable_unit_id
string | null

Unit the quantity is expressed in. Must be an active unit of the same item and measurement category. Defaults to the unit of the purchase line when adding; when changing, omitting it keeps the current unit.

stock_sources
object[] | null

Stock the goods are taken from. Required for a stock-tracked item and refused for an untracked one. The quantities must add up to quantity. When changing a line, omitting it keeps the current sources.

Response

Resource (only with response=resource).

id

Identifier of the return line (27-character KSUID string).

return_id

Identifier of the supplier return the line belongs to.

purchase_item_id

Identifier of the purchase line being returned.

stockable_unit_id

Identifier of the unit the quantity is expressed in; defaults to the unit of the purchase line.

purchase_item
object

The purchase line. Present only when requested with include=purchaseItem.

stockable_unit
object

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

stock_sources
any[]

Where the goods are taken from: a list of {quantity, asset_id} or {quantity, group_id}. Empty for a line that is not stock-tracked.

quantity
integer

Quantity returned, in the line's unit.

cost_total
number

Commercial value of the returned quantity in major units (the minor-unit amount divided by 10 to the power currency_exponent), computed first-in-first-out from the received quantities. This is the amount that reduces the purchase balance when the return has a credit note.

stock_cost_total
number | null

Inventory cost of the stock that left when the return was confirmed in major units (the minor-unit amount divided by 10 to the power currency_exponent); null until confirmation and for lines that are not stock-tracked.

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