Manage product returns and refunds
The Returns API enables you to create and manage product returns, process refunds, and track reverse logistics for your fulfillment operations.
Create Return
Customer initiates return
Shipment Received
Product arrives at warehouse
Inspection
Quality check performed
Refund Processed
Refund issued to customer
https://app.3plship.com/api/v1/returnsCreates a new return request for an order. Returns can be created for full orders or individual items.
{
"order_id": "ord_abc123",
"reason": "defective",
"items": [
{
"sku": "PROD-001",
"quantity": 1,
"condition": "damaged",
"notes": "Product arrived with broken seal"
}
],
"return_shipping": {
"carrier": "usps",
"tracking_number": "9400111899562712345678",
"label_url": "https://..."
},
"refund_amount": 49.99,
"refund_shipping": true,
"restocking_fee": 0.00,
"customer_email": "customer@example.com"
}{
"success": true,
"data": {
"id": "ret_xyz789",
"order_id": "ord_abc123",
"status": "initiated",
"reason": "defective",
"items": [
{
"sku": "PROD-001",
"quantity": 1,
"condition": "damaged",
"notes": "Product arrived with broken seal"
}
],
"return_shipping": {
"carrier": "usps",
"tracking_number": "9400111899562712345678",
"tracking_url": "https://tools.usps.com/go/...",
"status": "in_transit"
},
"refund_amount": 49.99,
"refund_shipping": true,
"restocking_fee": 0.00,
"refund_status": "pending",
"customer_email": "customer@example.com",
"created_at": "2025-01-15T14:30:00.000Z",
"updated_at": "2025-01-15T14:30:00.000Z"
},
"meta": {
"request_id": "req_12345",
"timestamp": "2025-01-15T14:30:00.000Z"
}
}defectiveProduct is defective or damaged
wrong_itemWrong product was shipped
not_as_describedProduct doesn't match description
customer_remorseCustomer changed their mind
expiredProduct expired or near expiration
otherOther reason (include notes)
curl -X POST https://app.3plship.com/api/v1/returns \
-H "Authorization: Bearer zl_live_..." \
-H "Content-Type: application/json" \
-d '{
"order_id": "ord_abc123",
"reason": "defective",
"items": [{
"sku": "PROD-001",
"quantity": 1,
"condition": "damaged"
}],
"refund_amount": 49.99
}'const response = await fetch('https://app.3plship.com/api/v1/returns', {
method: 'POST',
headers: {
'Authorization': 'Bearer zl_live_...',
'Content-Type': 'application/json'
},
body: JSON.stringify({
order_id: 'ord_abc123',
reason: 'defective',
items: [{
sku: 'PROD-001',
quantity: 1,
condition: 'damaged'
}],
refund_amount: 49.99
})
});
const { success, data } = await response.json();
console.log(data);import requests
response = requests.post(
'https://app.3plship.com/api/v1/returns',
headers={
'Authorization': 'Bearer zl_live_...',
'Content-Type': 'application/json'
},
json={
'order_id': 'ord_abc123',
'reason': 'defective',
'items': [{
'sku': 'PROD-001',
'quantity': 1,
'condition': 'damaged'
}],
'refund_amount': 49.99
}
)
return_data = response.json()
print(return_data['data'])https://app.3plship.com/api/v1/returnsRetrieves a paginated list of all returns with optional filtering by status, date range, or order.
| Parameter | Type | Description |
|---|---|---|
| status | string | Filter by return status (initiated, received, inspected, completed) |
| order_id | string | Filter by specific order ID |
| page | integer | Page number (starts at 1, default: 1) |
| limit | integer | Number of results per page (default: 50, max: 100) |
curl -X GET "https://app.3plship.com/api/v1/returns?status=initiated&page=1&limit=50" \
-H "Authorization: Bearer zl_live_..."const response = await fetch('https://app.3plship.com/api/v1/returns?status=initiated&page=1&limit=50', {
headers: {
'Authorization': 'Bearer zl_live_...'
}
});
const { success, data, meta } = await response.json();
console.log(data); // Array of returns
console.log(meta.pagination); // Pagination infohttps://app.3plship.com/api/v1/returns/:id/refundProcesses a refund for an approved return. This endpoint should be called after the return has been received and inspected.
Refunds are typically processed within 5-7 business days. The refund will be issued to the original payment method used for the order.