Ship Vendor Return
POST/api/vendor-returns/:vendorReturn/ship
Ship the vendor return: the goods physically leave the warehouse. Creates the outbound shipment record, posts the inventory-out movements, and posts the accounting for the return. Status moves from authorized to shipped. A DRAFT return is authorized automatically before shipping, so shipping is allowed from draft or authorized status.
Accounting split, captured per line at ship time:
- un-invoiced units debit the vendor-returns clearing account (reversing the receipt accrual)
- units already invoiced by the supplier debit accounts payable
- write-off lines (is_write_off = true) debit cost of goods sold instead Un-invoiced units are consumed first when splitting. The split is recorded on each line as clearing_quantity and ap_quantity.
Authentication: Requires Bearer token.
Body fields (all optional):
- shipment_date (date, YYYY-MM-DD; defaults to today)
- tracking_number (string, max 255)
- shipping_method_id (integer): ID of a shipping method
- custom_carrier (string, max 255): free-text carrier name when no shipping method applies
- notes (string)
Fails with 422 when the return is already shipped, completed, or void, or when a line's quantity exceeds the remaining returnable quantity for its purchase order line.
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.