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

# Create Return

> Create a new return record with automatic RMA generation and workflow initiation

<Note>
  This endpoint creates a new return and automatically triggers the returns management workflow, including label generation and customer notifications.
</Note>

## Authentication

This endpoint requires a valid API key with `returns:write` permissions.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Request Body

<ParamField body="order_id" type="string" required>
  The unique identifier of the order being returned. Must be a valid existing order.
</ParamField>

<ParamField body="items" type="array" required>
  Array of items being returned from the order.

  <Expandable title="Item object properties">
    <ParamField body="sku" type="string" required>
      Product SKU being returned
    </ParamField>

    <ParamField body="quantity" type="integer" required>
      Number of units being returned
    </ParamField>

    <ParamField body="reason" type="string" required>
      Return reason. Options: `defective`, `not_as_described`, `wrong_item`, `damaged`, `other`
    </ParamField>

    <ParamField body="condition" type="string">
      Item condition. Options: `A` (like new), `B` (good), `C` (fair), `D` (poor)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="customer_email" type="string" required>
  Email address of the customer. Used for sending return labels and notifications.
</ParamField>

<ParamField body="reason_code" type="string" required>
  Primary reason for the return. Options: `defective`, `not_satisfied`, `wrong_item`, `arrived_late`, `damaged_in_transit`, `other`
</ParamField>

<ParamField body="type" type="string" default="replacement">
  Type of return. Options: `replacement`, `refund`, `store_credit`
</ParamField>

<ParamField body="customer_notes" type="string">
  Additional notes or comments from the customer about the return.
</ParamField>

<ParamField body="shipping_address" type="object">
  Customer's address for pickup (if different from order address).

  <Expandable title="Address properties">
    <ParamField body="street1" type="string" required>
      Street address line 1
    </ParamField>

    <ParamField body="street2" type="string">
      Street address line 2
    </ParamField>

    <ParamField body="city" type="string" required>
      City name
    </ParamField>

    <ParamField body="state" type="string" required>
      State/Province code (e.g., "CA", "NY")
    </ParamField>

    <ParamField body="zip" type="string" required>
      Postal/ZIP code
    </ParamField>

    <ParamField body="country" type="string" required>
      ISO 3166-1 alpha-2 country code (e.g., "US", "CA")
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="zendesk_ticket_id" type="string">
  Associated support ticket ID for tracking.
</ParamField>

<ParamField body="metadata" type="object">
  Additional custom metadata to store with the return.
</ParamField>

### Response

<ResponseField name="id" type="string">
  The ID provided in the data tab may be used to identify the return
</ResponseField>

<ResponseField name="order_id" type="string">
  The order ID provided in the data tab may be used to identify the order
</ResponseField>

<ResponseField name="serial_number" type="string">
  The serial number provided in the data tab may be used to identify the serial number
</ResponseField>

<ResponseField name="description" type="string">
  The description provided in the data tab may be used to identify the description
</ResponseField>

<ResponseField name="status" type="string">
  The status provided in the data tab may be used to identify the status
</ResponseField>

<ResponseField name="reported_condition" type="string">
  The reported condition provided in the data tab may be used to identify the reported condition
</ResponseField>

<ResponseField name="tracking_number" type="string">
  The tracking number provided in the data tab may be used to identify the tracking number
</ResponseField>

<ResponseField name="zendesk_number" type="string">
  The zendesk number provided in the data tab may be used to identify the zendesk number
</ResponseField>

<ResponseField name="action_needed" type="string">
  The action needed provided in the data tab may be used to identify the action needed
</ResponseField>

<ResponseField name="rma" type="string">
  The rma provided in the data tab may be used to identify the rma
</ResponseField>

<ResponseField name="country" type="string">
  The country provided in the data tab may be used to identify the country
</ResponseField>

<RequestExample>
  ```bash Basic Return theme={null}
  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"
    }'
  ```

  ```bash Complete Return with Address theme={null}
  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"
      }
    }'
  ```

  ```graphQL GraphQL theme={null}
  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
            }
          }
        }`;
  ```

  ```js Node.js theme={null}
  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'
  });
  ```

  ```python Python theme={null}
  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'
  })
  ```

  ```ruby Ruby theme={null}
  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'
  })
  ```

  ```go Go theme={null}
  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'
  )
  ```

  ```java Java theme={null}
  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'
  })
  ```

  ```php PHP theme={null}
  $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'
  })
  ```

  ```csharp C# theme={null}
  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'
  );
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response (201) theme={null}
  {
    "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"
      }
    ]
  }
  ```

  ```json Error Response (400) theme={null}
  {
    "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
      }
    }
  }
  ```

  ```json Error Response (422) theme={null}
  {
    "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"
        }
      ]
    }
  }
  ```
</ResponseExample>