The returns API models the full RMA lifecycle: a return is created, approved or rejected, the items are shipped back, received, and finally refunded. Each step is a separate endpoint with its own permission scope.
Return states
A return progresses through: pending → approved → shipped → received → refunded. It may also be rejected at any point before shipping.
Paginated list of orders that have at least one return. Requires returns:read scope.
curl "https://api.fenicia.io/orders/returns?status=pending&limit=50" \
-H "Authorization: Bearer fn_live_your_api_key"Get the number of returns in each status. Useful for dashboards. Requires returns:read scope.
curl https://api.fenicia.io/orders/returns/counts \
-H "Authorization: Bearer fn_live_your_api_key"Lists all returns associated with an order. Requires returns:read scope.
curl https://api.fenicia.io/orders/ord_01/returns \
-H "Authorization: Bearer fn_live_your_api_key"Retrieve a single return with full detail. Requires returns:read scope.
curl https://api.fenicia.io/orders/ord_01/returns/ret_01 \
-H "Authorization: Bearer fn_live_your_api_key"Create a new return for an order. Requires returns:create scope.
curl -X POST https://api.fenicia.io/orders/ord_01/returns \
-H "Authorization: Bearer fn_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{"items":[{"sku":"ABC-123","quantity":1}],"reason":"damaged","notes":"Arrived broken"}'Approve a pending return. Requires returns:approve scope.
curl -X POST https://api.fenicia.io/orders/ord_01/returns/ret_01/approve \
-H "Authorization: Bearer fn_live_your_api_key"Reject a pending return. Requires returns:approve scope.
curl -X POST https://api.fenicia.io/orders/ord_01/returns/ret_01/reject \
-H "Authorization: Bearer fn_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{"reason":"outside_return_window","notes":"Purchased 120 days ago"}'Record that the customer shipped the return back. Requires returns:update scope.
curl -X POST https://api.fenicia.io/orders/ord_01/returns/ret_01/ship \
-H "Authorization: Bearer fn_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{"trackingNumber":"1Z999...","carrier":"fedex"}'Record receipt and inspection of returned items. Requires returns:process scope.
curl -X POST https://api.fenicia.io/orders/ord_01/returns/ret_01/receive \
-H "Authorization: Bearer fn_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{"condition":"new","notes":"Unopened box"}'Issue a refund for a received return. Requires returns:process scope.
curl -X POST https://api.fenicia.io/orders/ord_01/returns/ret_01/refund \
-H "Authorization: Bearer fn_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{"amount":499.00,"method":"original_payment"}'Update mutable fields of a return (items, reason, notes). Requires returns:update scope.
curl -X PUT https://api.fenicia.io/orders/ord_01/returns/ret_01 \
-H "Authorization: Bearer fn_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{"notes":"Updated notes"}'Tip
Use GET /orders/returns/counts as the data source for a Returns dashboard tile — it's cheap to poll and gives you all status buckets in a single call.