POST
Create a vendor return
Company space For: Buyer, Stock keeper · Permission: vendor_returns.create Conditions
  • replacement_expected is required and true is refused: replacement tracking is not supported for supplier returns.
  • The reference, when sent, must be unique among the company’s supplier returns. Deleted returns are removed for good, so their references can be reused.
  • When items are sent, there must be at least one; each item must belong to the organization and appear only once.
  • When stockable_unit_id is sent it must be a unit of that item; otherwise the base unit is used.
  • For a stock-tracked item, stock_sources are required; for an untracked one they are refused. Each source names either an asset or a group, may not repeat, must be eligible for the company, and must hold stock tagged with this supplier, beyond what other draft returns of the same supplier already reserve. Source quantities must add up to the item quantity.
What else happens
  • Creates the return in draft status with the items sent. Nothing leaves stock until it 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.

Body

application/json
vendor_id
string
required

Identifier of the supplier the goods go back to (27-character KSUID string). Required when creating; it must be a supplier of the current company. Not accepted when changing a return.

reference
string | null

Free reference of the return. Up to 255 characters, unique among the company's supplier returns.

Maximum string length: 255
replacement_expected
boolean

Whether a replacement is expected. Required when creating. Only false is accepted: replacement tracking is not supported for supplier returns.

items
object[]

Lines of the return. Optional when creating, at least one if sent; not accepted when changing a return (use the items routes).

Minimum array length: 1

Response

VendorReturnResource

id
string
required

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

vendor_id
string
required

Identifier of the supplier the goods go back to.

reference
string | null
required

Free reference of the return, unique among the company's supplier returns.

status
string
required

Lifecycle status: draft while it can still be edited or deleted, confirmed once the goods have left stock.

replacement_expected
boolean
required

Whether a replacement was expected. Always false today: replacement tracking is not supported.

returned_at
string<date-time> | null
required

Date and time the return was confirmed (ISO 8601); null while it is a draft.

created_at
string<date-time>
required

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

updated_at
string<date-time>
required

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

items
VendorReturnItemResource · object[]

Lines of the return, when loaded (they are on the show, create, update and confirm answers and on each item of the list).