POST
Add item to purchase return
Company space For: Buyer, Stock keeper · Permission: purchase_return_items.create, purchase_returns.update Conditions
  • Both purchase_return_items.create and purchase_returns.update are needed.
  • The supplier return must still be a draft.
  • purchase_item_id is required, must belong to the purchase of the return, and cannot already be on this return.
  • The unit must belong to the same item and measurement category as the purchase item and be active; it defaults to the purchase item’s own unit.
  • The quantity cannot exceed what was received and accepted (damaged quantities excluded) and not already taken by another return of the same purchase, draft or confirmed; when the return is attached to a reception, only that reception’s lines count.
  • For a stock-tracked item, stock_sources are required; for an untracked item they are refused. Each source names either an asset or a group, may not repeat, must be eligible for the company, and must hold enough stock that came from this purchase. Source quantities must add up to the item quantity.
  • When the return expects a replacement, the quantity must convert exactly into whole units of the purchase unit.
What else happens
  • Adds the line with its cost_total computed from the received quantities. 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).

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