Skip to main content
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"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.stateset.com/llms.txt

Use this file to discover all available pages before exploring further.

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"
    }
  ]
}