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

# Returns

> The return object — every field, which ones are nullable, and the casing inconsistency to watch for.

# The return object

A return tracks merchandise coming back to a merchant. It carries the RMA, the reason, the condition
of the goods, and the refund amounts, with a line item per SKU returned.

<Warning>
  **Almost every field is nullable.** A freshly created return typically has `rma`, `order_id`,
  `customerEmail`, `status`, and `created_date` populated and *everything else* `null` — including
  `amount`, `total_refunded`, `condition`, and `reason_category`. They fill in as the return is
  processed.

  Write your integration to expect nulls on every optional field rather than only on the ones that look
  optional. This is the single most common source of breakage against this object.
</Warning>

## Casing

The object mixes two conventions, and the API sends them exactly as written:

| Field           | Note          |
| --------------- | ------------- |
| `customerEmail` | **camelCase** |
| `enteredBy`     | **camelCase** |
| everything else | `snake_case`  |

<Note>
  Do not normalise these when serialising a request, and do not assume a snake\_case equivalent exists.
  `customer_email` is not a field.
</Note>

## Return

| Name                 | Type      | Description                                              |
| -------------------- | --------- | -------------------------------------------------------- |
| `id`                 | Integer   | Unique identifier for the return                         |
| `rma`                | String    | Return Merchandise Authorization number, e.g. `#1014-R5` |
| `status`             | String    | Current state, as a short code — see [Status](#status)   |
| `created_date`       | Date/Time | When the return record was created                       |
| `order_id`           | Integer   | The order being returned against                         |
| `order_date`         | Date/Time | When that order was originally placed                    |
| `customer_id`        | Integer   | The customer returning the goods                         |
| `customerEmail`      | String    | Customer email (**camelCase**)                           |
| `enteredBy`          | String    | Who created the record (**camelCase**)                   |
| `requested_date`     | Date/Time | When the customer requested the return                   |
| `shipped_date`       | Date/Time | When the goods were shipped back                         |
| `tracking_number`    | String    | Inbound tracking number                                  |
| `reason_category`    | String    | Why it is coming back — see [Reasons](#reasons)          |
| `reported_condition` | String    | Condition **as the customer described it**               |
| `condition`          | String    | Condition **as assessed on receipt**                     |
| `description`        | String    | Free-text detail                                         |
| `serial_number`      | String    | Serial number of the returned item                       |
| `amount`             | Decimal   | Monetary amount associated with the return               |
| `total_refunded`     | Decimal   | Total refunded, including tax                            |
| `tax_refunded`       | Decimal   | The tax portion of the refund                            |
| `flat_rate_shipping` | Boolean   | Whether return shipping is charged at a flat rate        |
| `action_needed`      | Boolean   | Whether the return is waiting on a human                 |
| `return_line_items`  | Array     | The items — see below                                    |

<Tip>
  `reported_condition` and `condition` are deliberately separate. The first is the customer's claim,
  the second is what your team found. A discrepancy between them is exactly the signal worth reporting
  on — and collapsing them into one field destroys it.
</Tip>

## Return line item

| Name                 | Type    | Description                         |
| -------------------- | ------- | ----------------------------------- |
| `id`                 | Integer | Unique identifier for the line item |
| `return_id`          | Integer | The parent return                   |
| `sku`                | String  | SKU of the returned item            |
| `name`               | String  | Item name or description            |
| `price`              | Decimal | Unit price                          |
| `amount`             | Decimal | Amount for this line                |
| `condition`          | String  | Condition of this specific item     |
| `serial_number`      | String  | Serial number for this item         |
| `tax_refunded`       | Decimal | Tax refunded on this line           |
| `flat_rate_shipping` | Boolean | Flat-rate shipping on this line     |

<Note>
  A return can have an **empty** `return_line_items` array. A return created from a customer request
  before the goods arrive has no lines yet — do not treat an empty array as an error.
</Note>

## Status

`status` is a short code, not a word. `RCV` means received:

```json theme={null}
"status": "RCV"
```

Branch on the exact code string. Do not attempt to parse it as a readable label or to match on a
prefix.

## Reasons

`reason_category` groups the many ways a return can arise. The distinctions that matter operationally:

| Group                           | Covers                                                            |
| ------------------------------- | ----------------------------------------------------------------- |
| **Fault of the goods**          | Damaged, defective                                                |
| **Fault of the fulfilment**     | Wrong item sent, item missing from the shipment, not as described |
| **Never arrived**               | Not delivered, not received, not received on time                 |
| **Customer changed their mind** | No longer needed, unwanted, not what was expected                 |

<Tip>
  These four groups behave differently and it is worth mapping them explicitly. A damaged-goods return
  is a supplier or carrier claim; a never-arrived return is a carrier investigation and may not involve
  returned goods at all; a changed-mind return is the only group where a restocking fee is normally
  defensible. Treating all twelve reason strings as one flat list loses that.
</Tip>

## Example

A newly created return, showing how sparse the real payload is:

```json theme={null}
{
  "rma": "#1014-R5",
  "status": "RCV",
  "created_date": "2023-06-28T19:34:59.189838+00:00",
  "order_id": "524213310335630636",
  "customerEmail": "customer@example.com",
  "amount": null,
  "action_needed": null,
  "condition": null,
  "customer_id": null,
  "description": null,
  "enteredBy": null,
  "flat_rate_shipping": null,
  "order_date": null,
  "reason_category": null,
  "reported_condition": null,
  "requested_date": null,
  "serial_number": null,
  "shipped_date": null,
  "tax_refunded": null,
  "total_refunded": null,
  "tracking_number": null,
  "return_line_items": []
}
```

## Related

* [Get a return](/api-reference/return/get)
* [List returns](/api-reference/return/list)
* [Create a return](/api-reference/return/create)
* [Warranties](/api-reference/warranty/list) — for claims against a product rather than a purchase