Skip to main content
POST
/
returns
Create Return Request
curl --request POST \
  --url https://api.zinc.com/returns \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reason": "return.request_label",
  "notes": "<string>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "open",
  "reason": "return.request_label",
  "notes": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}
Submit a return request for a completed order. Return requests are reviewed and processed asynchronously.

​
Request

Required fields:
  • order_id - UUID of the order to return
  • reason - Reason for the return (see below)
Optional fields:
  • notes - Additional context for the return request (max 2000 characters)

​
Return Reasons

ReasonDescription
return.request_labelRequest a return shipping label
nondelivery.not_deliveredOrder was not delivered
nondelivery.damagedOrder arrived damaged
nondelivery.empty_boxPackage arrived empty
tracking.request_updateRequest a tracking update
cancel.forced_cancellationForce cancellation of the order
otherOther reason (provide details in notes)
When using the other reason, include a detailed explanation in the notes field to help expedite processing.

​
Response

A successful request returns a return request object with:
  • id - Unique return request identifier (UUID)
  • order_id - The associated order ID
  • status - Current status (initially open)
  • reason - The submitted reason
  • notes - Any notes provided
  • created_at - Timestamp of request creation
  • updated_at - Last update timestamp

Authorizations

​
Authorization
string
header
required

Zinc API key (Bearer zn_...)

Headers

​
authorization
string | null

Body

application/json
​
order_id
string<uuid>
required
​
reason
enum<string>
required
Available options:
return.request_label,
nondelivery.not_delivered,
nondelivery.damaged,
nondelivery.empty_box,
tracking.request_update,
cancel.forced_cancellation,
other
​
notes
string | null
Maximum string length: 2000

Response

Successful Response

​
id
string<uuid>
required
​
order_id
string<uuid>
required
​
status
enum<string>
required
Available options:
open,
in_progress,
approved,
denied,
completed
​
reason
enum<string>
required
Available options:
return.request_label,
nondelivery.not_delivered,
nondelivery.damaged,
nondelivery.empty_box,
tracking.request_update,
cancel.forced_cancellation,
other
​
notes
string | null
required
​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required