Create Return - StateSet API Docs

POST

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.

Show Item object properties

sku

string

required

Product SKU being returned

quantity

integer

required

Number of units being returned

reason

string

required

Return reason. Options: defective, not_as_described, wrong_item, damaged, other

condition

string

Item condition. Options: A (like new), B (good), C (fair), D (poor)

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).

Show Address properties

street1

string

required

Street address line 1

street2

string

Street address line 2

city

string

required

City name

state

string

required

State/Province code (e.g., “CA”, “NY”)

zip

string

required

Postal/ZIP code

country

string

required

ISO 3166-1 alpha-2 country code (e.g., “US”, “CA”)

zendesk_ticket_id

string

Associated support ticket ID for tracking.

metadata

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

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

Retrieve Return Update 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"
    }
  ]
}

StateSet One

​Authentication

​Request Body

​Response

Authentication

Request Body

Response