curl -X POST https://api.stateset.com/v1/return \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"order_id": "ORD-789456",
"customer_email": "customer@example.com",
"reason_code": "defective",
"type": "replacement",
"items": [
{
"sku": "SHOE-RED-10",
"quantity": 1,
"reason": "defective",
"condition": "B"
}
],
"customer_notes": "Sole is separating from the shoe"
}'
curl -X POST https://api.stateset.com/v1/return \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-return-key-123" \
-d '{
"order_id": "ORD-789456",
"customer_email": "customer@example.com",
"reason_code": "wrong_item",
"type": "refund",
"items": [
{
"sku": "SHIRT-BLUE-L",
"quantity": 2,
"reason": "wrong_item",
"condition": "A"
},
{
"sku": "PANTS-BLACK-32",
"quantity": 1,
"reason": "not_as_described",
"condition": "A"
}
],
"shipping_address": {
"street1": "123 Main Street",
"street2": "Apt 4B",
"city": "New York",
"state": "NY",
"zip": "10001",
"country": "US"
},
"zendesk_ticket_id": "TICKET-98765",
"metadata": {
"source": "web_portal",
"priority": "high"
}
}'
mutation InsertNewReturn(
$return_x: returns_insert_input!
) {
insert_returns (
objects: [$return_x]
) {
returning {
id
order_id
serial_number
description
status
reported_condition
tracking_number
zendesk_number
action_needed
rma
country
}
}
}`;
const returns = await stateset.returns.create({
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
});
returns = stateset.returns.create({
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
})
returns = stateset.returns.create({
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
})
returns, err := stateset.Returns.Create(
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
)
Returns returns = stateset.returns.create({
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
})
$returns = $stateset->returns->create({
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
})
var returns = stateset.Returns.Create(
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
);
{
"id": "RET-0901f083-aa1c-43c5-af5c",
"rma": "RMA-2024-1014",
"order_id": "ORD-789456",
"customer_email": "customer@example.com",
"status": "NEW",
"type": "replacement",
"reason_code": "defective",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"workflow_id": "wf-return-0901f083",
"items": [
{
"id": "RLI-123",
"sku": "SHOE-RED-10",
"quantity": 1,
"reason": "defective",
"condition": "B",
"product_name": "Red Running Shoe Size 10",
"refund_amount": 89.99
}
],
"shipping": {
"carrier": "fedex",
"tracking_number": "7799832198765",
"label_url": "https://api.stateset.com/labels/RET-0901f083.pdf",
"label_created_at": "2024-01-15T10:30:15Z"
},
"totals": {
"subtotal": 89.99,
"tax_refund": 7.20,
"shipping_refund": 0.00,
"total_refund": 97.19
},
"timeline": [
{
"event": "return_created",
"timestamp": "2024-01-15T10:30:00Z",
"description": "Return request created"
},
{
"event": "label_generated",
"timestamp": "2024-01-15T10:30:15Z",
"description": "Shipping label generated and emailed"
}
]
}
{
"error": {
"code": "INVALID_ORDER",
"message": "Order ORD-789456 not found or not eligible for return",
"details": {
"order_status": "returned",
"days_since_purchase": 45,
"return_window": 30
}
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"errors": [
{
"field": "items[0].quantity",
"message": "Quantity cannot exceed original order quantity",
"original_quantity": 1,
"requested_quantity": 2
},
{
"field": "reason_code",
"message": "Invalid reason code. Must be one of: defective, not_satisfied, wrong_item, arrived_late, damaged_in_transit, other"
}
]
}
}
Create Return
Create a new return record with automatic RMA generation and workflow initiation
POST
/
v1
/
return
curl -X POST https://api.stateset.com/v1/return \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"order_id": "ORD-789456",
"customer_email": "customer@example.com",
"reason_code": "defective",
"type": "replacement",
"items": [
{
"sku": "SHOE-RED-10",
"quantity": 1,
"reason": "defective",
"condition": "B"
}
],
"customer_notes": "Sole is separating from the shoe"
}'
curl -X POST https://api.stateset.com/v1/return \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-return-key-123" \
-d '{
"order_id": "ORD-789456",
"customer_email": "customer@example.com",
"reason_code": "wrong_item",
"type": "refund",
"items": [
{
"sku": "SHIRT-BLUE-L",
"quantity": 2,
"reason": "wrong_item",
"condition": "A"
},
{
"sku": "PANTS-BLACK-32",
"quantity": 1,
"reason": "not_as_described",
"condition": "A"
}
],
"shipping_address": {
"street1": "123 Main Street",
"street2": "Apt 4B",
"city": "New York",
"state": "NY",
"zip": "10001",
"country": "US"
},
"zendesk_ticket_id": "TICKET-98765",
"metadata": {
"source": "web_portal",
"priority": "high"
}
}'
mutation InsertNewReturn(
$return_x: returns_insert_input!
) {
insert_returns (
objects: [$return_x]
) {
returning {
id
order_id
serial_number
description
status
reported_condition
tracking_number
zendesk_number
action_needed
rma
country
}
}
}`;
const returns = await stateset.returns.create({
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
});
returns = stateset.returns.create({
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
})
returns = stateset.returns.create({
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
})
returns, err := stateset.Returns.Create(
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
)
Returns returns = stateset.returns.create({
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
})
$returns = $stateset->returns->create({
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
})
var returns = stateset.Returns.Create(
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
);
{
"id": "RET-0901f083-aa1c-43c5-af5c",
"rma": "RMA-2024-1014",
"order_id": "ORD-789456",
"customer_email": "customer@example.com",
"status": "NEW",
"type": "replacement",
"reason_code": "defective",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"workflow_id": "wf-return-0901f083",
"items": [
{
"id": "RLI-123",
"sku": "SHOE-RED-10",
"quantity": 1,
"reason": "defective",
"condition": "B",
"product_name": "Red Running Shoe Size 10",
"refund_amount": 89.99
}
],
"shipping": {
"carrier": "fedex",
"tracking_number": "7799832198765",
"label_url": "https://api.stateset.com/labels/RET-0901f083.pdf",
"label_created_at": "2024-01-15T10:30:15Z"
},
"totals": {
"subtotal": 89.99,
"tax_refund": 7.20,
"shipping_refund": 0.00,
"total_refund": 97.19
},
"timeline": [
{
"event": "return_created",
"timestamp": "2024-01-15T10:30:00Z",
"description": "Return request created"
},
{
"event": "label_generated",
"timestamp": "2024-01-15T10:30:15Z",
"description": "Shipping label generated and emailed"
}
]
}
{
"error": {
"code": "INVALID_ORDER",
"message": "Order ORD-789456 not found or not eligible for return",
"details": {
"order_status": "returned",
"days_since_purchase": 45,
"return_window": 30
}
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"errors": [
{
"field": "items[0].quantity",
"message": "Quantity cannot exceed original order quantity",
"original_quantity": 1,
"requested_quantity": 2
},
{
"field": "reason_code",
"message": "Invalid reason code. Must be one of: defective, not_satisfied, wrong_item, arrived_late, damaged_in_transit, other"
}
]
}
}
This endpoint creates a new return and automatically triggers the returns management workflow, including label generation and customer notifications.
Authentication
This endpoint requires a valid API key withreturns:write permissions.
Authorization: Bearer YOUR_API_KEY
Request Body
string
required
The unique identifier of the order being returned. Must be a valid existing order.
array
required
Array of items being returned from the order.
string
required
Email address of the customer. Used for sending return labels and notifications.
string
required
Primary reason for the return. Options:
defective, not_satisfied, wrong_item, arrived_late, damaged_in_transit, otherstring
default:"replacement"
Type of return. Options:
replacement, refund, store_creditstring
Additional notes or comments from the customer about the return.
object
Customer’s address for pickup (if different from order address).
string
Associated support ticket ID for tracking.
object
Additional custom metadata to store with the return.
Response
string
The ID provided in the data tab may be used to identify the return
string
The order ID provided in the data tab may be used to identify the order
string
The serial number provided in the data tab may be used to identify the serial number
string
The description provided in the data tab may be used to identify the description
string
The status provided in the data tab may be used to identify the status
string
The reported condition provided in the data tab may be used to identify the reported condition
string
The tracking number provided in the data tab may be used to identify the tracking number
string
The zendesk number provided in the data tab may be used to identify the zendesk number
string
The action needed provided in the data tab may be used to identify the action needed
string
The rma provided in the data tab may be used to identify the rma
string
The country provided in the data tab may be used to identify the country
curl -X POST https://api.stateset.com/v1/return \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"order_id": "ORD-789456",
"customer_email": "customer@example.com",
"reason_code": "defective",
"type": "replacement",
"items": [
{
"sku": "SHOE-RED-10",
"quantity": 1,
"reason": "defective",
"condition": "B"
}
],
"customer_notes": "Sole is separating from the shoe"
}'
curl -X POST https://api.stateset.com/v1/return \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-return-key-123" \
-d '{
"order_id": "ORD-789456",
"customer_email": "customer@example.com",
"reason_code": "wrong_item",
"type": "refund",
"items": [
{
"sku": "SHIRT-BLUE-L",
"quantity": 2,
"reason": "wrong_item",
"condition": "A"
},
{
"sku": "PANTS-BLACK-32",
"quantity": 1,
"reason": "not_as_described",
"condition": "A"
}
],
"shipping_address": {
"street1": "123 Main Street",
"street2": "Apt 4B",
"city": "New York",
"state": "NY",
"zip": "10001",
"country": "US"
},
"zendesk_ticket_id": "TICKET-98765",
"metadata": {
"source": "web_portal",
"priority": "high"
}
}'
mutation InsertNewReturn(
$return_x: returns_insert_input!
) {
insert_returns (
objects: [$return_x]
) {
returning {
id
order_id
serial_number
description
status
reported_condition
tracking_number
zendesk_number
action_needed
rma
country
}
}
}`;
const returns = await stateset.returns.create({
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
});
returns = stateset.returns.create({
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
})
returns = stateset.returns.create({
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
})
returns, err := stateset.Returns.Create(
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
)
Returns returns = stateset.returns.create({
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
})
$returns = $stateset->returns->create({
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
})
var returns = stateset.Returns.Create(
'id': '0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
'order_id': 'O-12332312',
'serial_number': 'st123976879tm',
'description:' 'Return for different type',
'status': 'NEW'
'reported_condition': 'A',
'tracking_number': '132908231098120921',
'zendesk_number': '123313',
'action_needed': 'Replacement'
'rma': 'R-123312',
'country': 'US'
);
{
"id": "RET-0901f083-aa1c-43c5-af5c",
"rma": "RMA-2024-1014",
"order_id": "ORD-789456",
"customer_email": "customer@example.com",
"status": "NEW",
"type": "replacement",
"reason_code": "defective",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"workflow_id": "wf-return-0901f083",
"items": [
{
"id": "RLI-123",
"sku": "SHOE-RED-10",
"quantity": 1,
"reason": "defective",
"condition": "B",
"product_name": "Red Running Shoe Size 10",
"refund_amount": 89.99
}
],
"shipping": {
"carrier": "fedex",
"tracking_number": "7799832198765",
"label_url": "https://api.stateset.com/labels/RET-0901f083.pdf",
"label_created_at": "2024-01-15T10:30:15Z"
},
"totals": {
"subtotal": 89.99,
"tax_refund": 7.20,
"shipping_refund": 0.00,
"total_refund": 97.19
},
"timeline": [
{
"event": "return_created",
"timestamp": "2024-01-15T10:30:00Z",
"description": "Return request created"
},
{
"event": "label_generated",
"timestamp": "2024-01-15T10:30:15Z",
"description": "Shipping label generated and emailed"
}
]
}
{
"error": {
"code": "INVALID_ORDER",
"message": "Order ORD-789456 not found or not eligible for return",
"details": {
"order_status": "returned",
"days_since_purchase": 45,
"return_window": 30
}
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"errors": [
{
"field": "items[0].quantity",
"message": "Quantity cannot exceed original order quantity",
"original_quantity": 1,
"requested_quantity": 2
},
{
"field": "reason_code",
"message": "Invalid reason code. Must be one of: defective, not_satisfied, wrong_item, arrived_late, damaged_in_transit, other"
}
]
}
}
⌘I