Package returns

Request returning a warehouse package (or selected items) to the Chinese seller when goods are damaged, wrong, or otherwise not shippable outbound.

Availability: Sandbox / Gateway MOCK is live (hio_test_*). Live warehouse execution and wallet debit are not wired yet.

Requires warehouse fulfillment.

Method	Path	Scope	Purpose
POST	`/v1/fulfillment/returns`	`shipment:create`	Create Return Request
GET	`/v1/fulfillment/returns`	`warehouse:read`	List Return Requests
GET	`/v1/fulfillment/returns/{return_id}`	`warehouse:read`	Get Return Request
POST	`/v1/fulfillment/returns/{return_id}/confirm`	`shipment:create`	Confirm Return Request
POST	`/v1/fulfillment/returns/{return_id}/cancel`	`shipment:create`	Cancel Return Request

IDs use ret_*. Statuses: PENDING · RETURNED · CANCELLED.

Lifecycle {#lifecycle}

Create Return Request

Creates a request to return a warehouse package or selected items to the seller. HioBuy will calculate the applicable handling and domestic return shipping fees before the return is processed.

Required: package_id, reason (code), items[] (name, quantity > 0), seller_return address. Optional: remark (required when reason=OTHER).

Clients must not submit fees. Mock returns fee.total (e.g. 18.00 CNY) with confirmed: false.

Confirm Return Request

Confirms the current return fee and authorizes HioBuy to process the return to the seller.

{
  "fee_amount": 18,
  "currency": "CNY"
}

fee_amount must match current fee.total or the API returns RETURN_FEE_CHANGED. Repeat confirm is idempotent (no double charge).

Cancel

Only while PENDING. Completed returns → RETURN_ALREADY_RETURNED.

List filters

status, package_id, tracking_number, reason, created_from / created_to, page / page_size.

Sandbox

ID	Notes
`ret_pending_001`	Confirm with `fee_amount: 18`
`ret_pending_002`	Fee is `20`; confirm `18` → `RETURN_FEE_CHANGED`
`ret_returned_001`	Has domestic `return_tracking`
`ret_cancelled_001`	Already cancelled
`sb_ret_not_found`	404
`sb_ret_fee_not_ready` / `sb_ret_insufficient`	Fee / balance edge cases

Errors

RETURN_NOT_FOUND, RETURN_NOT_CONFIRMABLE, RETURN_NOT_CANCELLABLE, RETURN_ALREADY_RETURNED, RETURN_ALREADY_CANCELLED, RETURN_FEE_NOT_READY, RETURN_FEE_CHANGED, INSUFFICIENT_BALANCE, PACKAGE_NOT_FOUND, PACKAGE_NOT_RETURNABLE, INBOUND_NOT_FOUND, INBOUND_PACKAGE_MISMATCH, INVALID_RETURN_REASON, INVALID_RETURN_ADDRESS, RETURN_VALIDATION_FAILED.

Webhooks (reserved)

return.created · return.action_required · return.returned · return.cancelled — catalog reserved; delivery not implemented in this phase.

Get Support

Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days

Email support