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"
  }'
{
  "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"
    }
  ]
}
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 with returns:write permissions.
Authorization: Bearer YOUR_API_KEY

Request Body

order_id
string
required
The unique identifier of the order being returned. Must be a valid existing order.
items
array
required
Array of items being returned from the order.
customer_email
string
required
Email address of the customer. Used for sending return labels and notifications.
reason_code
string
required
Primary reason for the return. Options: defective, not_satisfied, wrong_item, arrived_late, damaged_in_transit, other
type
string
default:"replacement"
Type of return. Options: replacement, refund, store_credit
customer_notes
string
Additional notes or comments from the customer about the return.
shipping_address
object
Customer’s address for pickup (if different from order address).
zendesk_ticket_id
string
Associated support ticket ID for tracking.
metadata
object
Additional custom metadata to store with the return.

Response

id
string
The ID provided in the data tab may be used to identify the return
order_id
string
The order ID provided in the data tab may be used to identify the order
serial_number
string
The serial number provided in the data tab may be used to identify the serial number
description
string
The description provided in the data tab may be used to identify the description
status
string
The status provided in the data tab may be used to identify the status
reported_condition
string
The reported condition provided in the data tab may be used to identify the reported condition
tracking_number
string
The tracking number provided in the data tab may be used to identify the tracking number
zendesk_number
string
The zendesk number provided in the data tab may be used to identify the zendesk number
action_needed
string
The action needed provided in the data tab may be used to identify the action needed
rma
string
The rma provided in the data tab may be used to identify the rma
country
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"
  }'
{
  "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"
    }
  ]
}