Returns

Create return

Ask for an order to be returned to you.

POST/v1/returns

Bearer tokenIdempotency-KeyReturns JSONSuccess 201

This raises a return request with your shipping company, which then arranges the return and applies any return charge. An order can have one return. An order that has not been collected yet cannot be returned: cancel it instead.

Request

Headers

Field	Type	Description
`Authorization`required	`string`	The access token from Get token, as "Bearer <token>".
`Content-Type`required	`string`	Always application/json when a body is sent.
`Idempotency-Key`optional	`string`	Optional. Your own unique value for this action (up to 200 characters). Sending the same call again with the same value returns the first result and does nothing a second time.

Request body

Field	Type	Description
`orderId`required	`string`	The id of the order to return.
`reasonCodeId`optional	`string`	A return reason id, if your shipping company gave you its list.
`notes`optional	`string`	Why the order is being returned, up to 500 characters.

Example request

curl -X POST "https://api.swiftazu.com/v1/returns" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c2f6f0a-3f55-4f0e-9a51-2a1e3b6c9d10" \
  -d '{
  "orderId": "dffcd25d-6eb3-4b90-868c-6deca160ad74",
  "notes": "Wrong size delivered"
}'

Response

Example response · 201

{
  "id": "b980e9e3-eb45-432c-ad72-2fb1a9946213",
  "orderId": "SWZORDYFSADMR",
  "awbNumber": "DEMONQDJ3W6UDWML",
  "status": "initiated",
  "initiatedBy": "Application 100001 (Store sync)",
  "createdAt": "2026-10-02T02:30:52.395Z"
}

Errors

HTTP	Code	Meaning
404	`order_not_found`	No order of yours has this id or air waybill number.
409	`return_exists`	This order already has a return. The answer carries its returnId.
400	`order_not_collected`	The order has not been collected yet. Cancel it instead.
400	`order_not_returnable`	The order is in a status that cannot be returned.
400	`unknown_reason`	No return reason has this id.
400	`invalid_idempotency_key`	The Idempotency-Key header is empty or longer than 200 characters.
409	`idempotency_in_progress`	A call with this key is still running. Retry shortly.
409	`idempotency_key_reused`	This key was already used for a different call.

Every call can also return the shared errors listed on the Overview page. Overview