POST
Create a purchase return
Company space For: Buyer, Stock keeper · Permission: purchase_returns.create Conditions
  • Either purchase_id or purchase_reception_id must be sent, never both.
  • When a reception is given, it must be confirmed, and the return is attached to that reception’s purchase.
  • The purchase must be pending or completed; a return cannot be created for a purchase in any other status.
  • replacement_expected and has_credit_note are both required and cannot both be true: a supplier credit note cannot be combined with an expected replacement.
  • A VAT amount above zero is refused unless has_credit_note is true.
  • 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, and each purchase_item_id must appear only once.
  • Each item must belong to the chosen purchase, its unit must belong to the same item and measurement category and be active, and its 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, never both, may not repeat, must be eligible for the company, and must hold enough stock that came from this purchase (and this reception when given). Source quantities must add up to the item quantity.
  • When a replacement is expected, each item quantity must convert exactly into whole units of the purchase unit.
What else happens
  • Creates the return in draft status together with the items sent. Nothing leaves stock and the purchase balance is not changed 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.

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, purchase_reception_id, vendor_id, reference, status, vat_total, replacement_expected, has_credit_note, vat_is_recoverable, returned_at, 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.purchaseItem, items.stockableUnit.

Response

Resource (only with response=resource).

id

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

purchase_id

Identifier of the purchase the goods are returned to.

purchase_reception_id

Identifier of the reception the return is attached to; null when the return was created for the whole purchase.

vendor_id

Identifier of the supplier, copied from the purchase.

reference

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

status

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

vat_total
number

VAT on the supplier credit note in major units (the minor-unit amount divided by 10 to the power currency_exponent). 0 when there is no credit note.

replacement_expected
boolean

True when the supplier is expected to send replacement goods; confirming then reopens the returned quantities for receiving.

has_credit_note
boolean

True when the supplier issues a credit note for the returned goods; confirming then reduces the amount owed on the purchase. Cannot be true together with replacement_expected.

vat_is_recoverable
boolean

Whether the VAT of the purchase is recoverable, read from the purchase at rendering time; false when the purchase never set it.

returned_at

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

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 return. Present only when requested with include=items.