Returns

A return represents a request to send items back from the customer to the merchant. Returns follow an approval workflow: a return is requested (by the customer or merchant), approved or rejected by the merchant, items are received with condition tracking, and the return is closed.

Returns and refunds are separate but linkable. A return tracks the physical flow (items coming back); a refund tracks the financial flow (money going back). Either can exist independently — a goodwill refund needs no return, and a replacement return needs no refund.

Base URL: https://api.hydrajs.dev

Endpoints

Admin endpoints (secret key)

Method	Path	Auth	Description
GET	/v1/returns	Secret	List all returns
GET	/v1/returns/{id}	Secret	Get a return
POST	/v1/orders/{id}/returns	Secret	Create a return
POST	/v1/returns/{id}/approve	Secret	Approve a return
POST	/v1/returns/{id}/receive	Secret	Mark items received
POST	/v1/returns/{id}/close	Secret	Close a return
POST	/v1/returns/{id}/reject	Secret	Reject a return
POST	/v1/returns/{id}/cancel	Secret	Cancel a return
GET	/v1/orders/{id}/returns	Secret	List returns for an order

Customer self-service endpoints

Method	Path	Auth	Description
POST	/v1/me/orders/{id}/returns	Customer	Request a return
GET	/v1/me/returns	Customer	List own returns
POST	/v1/me/returns/{id}/cancel	Customer	Cancel own pending return

See Customer Self-Service for authentication details.

---

List returns

GET /v1/returns

Returns a cursor-paginated list of return requests. Supports filtering by order, customer, and status.

Query parameters

Parameter	Type	Description
limit	integer	Results per page (1–100, default 20)
cursor	string	Pagination cursor from a previous response
order_id	string	Filter by order ID
customer_id	string	Filter by customer ID
status	string	Filter: requested, approved, received, closed, rejected, cancelled
sort	string	Sort field: created_at (default), updated_at
order	string	Sort direction: asc, desc (default)

Request

curl "https://api.hydrajs.dev/v1/returns?status=requested&limit=10" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
  "data": [
    {
      "id": "rtn_abc123def456ghi789",
      "order_id": "ord_abc123def456ghi789",
      "customer_id": "cus_abc123def456ghi789",
      "status": "requested",
      "reason": "wrong_item",
      "reason_note": "Ordered size M but received size L",
      "initiated_by": "customer",
      "location_id": "loc_abc123def456ghi789",
      "staff_note": null,
      "approved_at": null,
      "received_at": null,
      "closed_at": null,
      "rejected_at": null,
      "cancelled_at": null,
      "metadata": {},
      "created_at": "2026-09-03T14:30:00.000Z",
      "updated_at": "2026-09-03T14:30:00.000Z"
    }
  ],
  "pagination": {
    "cursor": "eyJ0IjoiMjAyNi...",
    "has_more": false,
    "total": 1
  }
}

---

Get a return

GET /v1/returns/{id}

Returns a single return by ID. Use ?expand=line_items to include per-item return details with condition and restock info.

Path parameters

Parameter	Type	Description
id	string	Return ID (prefix: rtn_)

Query parameters

Parameter	Type	Description
expand	string	Comma-separated: line_items
fields	string	Comma-separated field names for sparse response

Request

curl "https://api.hydrajs.dev/v1/returns/rtn_abc123def456ghi789?expand=line_items" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
  "data": {
    "id": "rtn_abc123def456ghi789",
    "order_id": "ord_abc123def456ghi789",
    "customer_id": "cus_abc123def456ghi789",
    "status": "requested",
    "reason": "wrong_item",
    "reason_note": "Ordered size M but received size L",
    "initiated_by": "customer",
    "location_id": "loc_abc123def456ghi789",
    "staff_note": null,
    "approved_at": null,
    "received_at": null,
    "closed_at": null,
    "rejected_at": null,
    "cancelled_at": null,
    "metadata": {},
    "line_items": [
      {
        "id": "rli_abc123def456ghi789",
        "order_line_item_id": "li_abc123def456ghi789",
        "quantity": 1,
        "condition": null,
        "restock": true,
        "restocked": false,
        "restocked_quantity": 0,
        "created_at": "2026-09-03T14:30:00.000Z",
        "updated_at": "2026-09-03T14:30:00.000Z"
      }
    ],
    "created_at": "2026-09-03T14:30:00.000Z",
    "updated_at": "2026-09-03T14:30:00.000Z"
  }
}

---

Create a return

POST /v1/orders/{id}/returns

Creates a merchant-initiated return request for an order. The return is created in requested status. Items must belong to the specified order, and quantities cannot exceed the original order quantity minus items already in non-cancelled returns.

Path parameters

Parameter	Type	Description
id	string	Order ID (prefix: ord_)

Request body

Field	Type	Required	Description
line_items	array	Yes	Items to return (min 1)
line_items[].order_line_item_id	string	Yes	Order line item ID
line_items[].quantity	integer	Yes	Quantity to return (min 1)
reason	string	Yes	defective, wrong_item, not_as_described, changed_mind, damaged_in_shipping, other
reason_note	string	No	Free-text explanation (max 1000 chars)
staff_note	string	No	Internal note (max 2000 chars)
location_id	string	No	Destination location for returned items
metadata	object	No	Arbitrary key-value pairs

Request

curl -X POST "https://api.hydrajs.dev/v1/orders/ord_abc123def456ghi789/returns" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      { "order_line_item_id": "li_abc123def456ghi789", "quantity": 1 }
    ],
    "reason": "wrong_item",
    "reason_note": "Ordered size M but received size L"
  }'

Response 201

Returns the created return object with line_items expanded (same shape as Get a return response).

---

Approve a return

POST /v1/returns/{id}/approve

Approves a pending return request. Only returns in requested status can be approved. Optionally override the return destination location and add a staff note.

Path parameters

Parameter	Type	Description
id	string	Return ID (prefix: rtn_)

Request body

Field	Type	Required	Description
location_id	string	No	Override the return destination location
staff_note	string	No	Internal note (max 2000 chars)

Request

curl -X POST "https://api.hydrajs.dev/v1/returns/rtn_abc123def456ghi789/approve" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "staff_note": "Approved — standard return"
  }'

Response 200

Returns the updated return object with approved_at set and status: "approved".

---

Mark items received

POST /v1/returns/{id}/receive

Marks returned items as physically received. Sets per-item conditions and optionally restocks inventory. Only returns in approved status can be received.

Items in resellable condition are restocked by default. Items marked damaged or unsellable are not restocked unless explicitly overridden with restock: true.

Path parameters

Parameter	Type	Description
id	string	Return ID (prefix: rtn_)

Request body

Field	Type	Required	Description
items	array	No	Per-item conditions (if omitted, all default to resellable/restock)
items[].return_line_item_id	string	Yes	Return line item ID
items[].condition	string	Yes	resellable, damaged, defective, unsellable
items[].restock	boolean	No	Override restock decision
staff_note	string	No	Internal note (max 2000 chars)

Request

curl -X POST "https://api.hydrajs.dev/v1/returns/rtn_abc123def456ghi789/receive" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "return_line_item_id": "rli_abc123def456ghi789",
        "condition": "resellable",
        "restock": true
      }
    ],
    "staff_note": "All items in good condition"
  }'

Response 200

Returns the updated return with received_at set, status: "received", and line items showing condition, restocked, and restocked_quantity.

---

Close a return

POST /v1/returns/{id}/close

Closes a completed return. Only returns in received status can be closed. A return may also be auto-closed when a linked refund covers all return line items.

Path parameters

Parameter	Type	Description
id	string	Return ID (prefix: rtn_)

Request

curl -X POST "https://api.hydrajs.dev/v1/returns/rtn_abc123def456ghi789/close" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

Returns the updated return with closed_at set and status: "closed".

---

Reject a return

POST /v1/returns/{id}/reject

Rejects a pending return request. Only returns in requested status can be rejected.

Path parameters

Parameter	Type	Description
id	string	Return ID (prefix: rtn_)

Request body

Field	Type	Required	Description
staff_note	string	No	Reason for rejection (max 2000 chars)

Request

curl -X POST "https://api.hydrajs.dev/v1/returns/rtn_abc123def456ghi789/reject" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "staff_note": "Return window has expired"
  }'

Response 200

Returns the updated return with rejected_at set and status: "rejected".

---

Cancel a return

POST /v1/returns/{id}/cancel

Cancels a return before items are received. Returns in requested or approved status can be cancelled. Returns that have already been received cannot be cancelled.

Path parameters

Parameter	Type	Description
id	string	Return ID (prefix: rtn_)

Request

curl -X POST "https://api.hydrajs.dev/v1/returns/rtn_abc123def456ghi789/cancel" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

Returns the updated return with cancelled_at set and status: "cancelled".

---

List returns for an order

GET /v1/orders/{id}/returns

Returns all return requests for a specific order.

Path parameters

Parameter	Type	Description
id	string	Order ID (prefix: ord_)

Request

curl "https://api.hydrajs.dev/v1/orders/ord_abc123def456ghi789/returns" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
  "data": [
    {
      "id": "rtn_abc123def456ghi789",
      "order_id": "ord_abc123def456ghi789",
      "status": "requested",
      "reason": "wrong_item",
      "initiated_by": "customer",
      "created_at": "2026-09-03T14:30:00.000Z",
      "updated_at": "2026-09-03T14:30:00.000Z"
    }
  ]
}

---

Webhooks

Return status changes fire the following webhook events:

Event	Trigger
return.requested	A return request is created
return.approved	A return is approved
return.received	Returned items are received
return.rejected	A return request is rejected
return.cancelled	A return is cancelled
return.closed	A return is closed

See Webhooks for subscription setup.

---

Return statuses

Status	Description
requested	Return request submitted, awaiting merchant review
approved	Merchant approved, customer can ship items back
received	Items physically received, conditions assessed
closed	Return completed (manually or via linked refund)
rejected	Merchant rejected the return request
cancelled	Return cancelled before items were received

requested ──> approved ──> received ──> closed
    │             │
    ├──> rejected  └──> cancelled
    │
    └──> cancelled

---

Item conditions

Set during the receive step to track the physical state of returned items:

Condition	Description	Default restock
resellable	Good condition, can be resold	Yes
damaged	Physical damage	No
defective	Manufacturing defect	No
unsellable	Cannot be resold	No

---

The return object

Field	Type	Description
id	string	Unique ID (prefix: rtn_)
order_id	string	The order items are being returned from
customer_id	string | null	Customer ID (null for guest orders)
status	string	Return status (see above)
reason	string	Return reason (see create endpoint)
reason_note	string | null	Free-text explanation
initiated_by	string	customer or merchant
location_id	string | null	Destination location for returned items
staff_note	string | null	Internal note (not shown to customers)
approved_at	string | null	ISO 8601 timestamp
received_at	string | null	ISO 8601 timestamp
closed_at	string | null	ISO 8601 timestamp
rejected_at	string | null	ISO 8601 timestamp
cancelled_at	string | null	ISO 8601 timestamp
metadata	object	Arbitrary key-value pairs
line_items	array	Return line items (when expanded, see below)
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

Return line item object

Field	Type	Description
id	string	Unique ID (prefix: rli_)
order_line_item_id	string	The order line item being returned
quantity	integer	Number of units being returned
condition	string | null	Item condition (set on receive)
restock	boolean	Whether this item should be restocked
restocked	boolean	Whether restock actually happened
restocked_quantity	integer	How many units were restocked
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp