# Record a return of an order line (idempotent by return ID and line)

```http
POST /v1/returns
```

Source: https://docs.tryyoursize.com/api/reference/operations/createoutcomereturn/

**Key scopes:** `returns:write`. A secret key (`sk_`) has every scope; a restricted key (`rk_`) needs the scopes listed.

Secret key, or a restricted key with `returns:write` (e.g. a returns platform). The order must have been sent first (404 otherwise). Reasons are normalised to TryYourSize's taxonomy.

## Authentication

Secret key (`sk_…`) or restricted key (`rk_…`) from your server: `Authorization: Bearer sk_…`.

## Request body

`application/json`: `OutcomeReturnInput`

A return of (part of) an order line. Idempotent by (line, id). Free-text notes are not accepted.

- `id` (`string`, required, max length 200): Your return (or RMA) ID.
- `order_id` (`string`, required, max length 200)
- `line_id` (`string`, required, max length 200)
- `quantity` (`integer`, required)
- `reason` (`string`, optional, max length 60): size_too_small, size_too_large, fit_other, style, quality, damaged_or_wrong, changed_mind, other; Shopify's ReturnReason codes (SIZE_TOO_SMALL…) and common returns-platform words are mapped. Empty: unspecified.
- `exchange` (`boolean`, optional): The item was exchanged rather than refunded.
- `exchange_size` (`string`, optional, max length 40): The size sent in exchange (implies exchange).
- `returned_at` (`string (date-time)`, required)

## Responses

### 200

Updated (`OutcomeReturnResult`)

- `created` (`boolean`, required)
- `reason` (`string`, required): The reason as normalised to TryYourSize's taxonomy.

### 201

Created (`OutcomeReturnResult`)

- `created` (`boolean`, required)
- `reason` (`string`, required): The reason as normalised to TryYourSize's taxonomy.

### 400

Invalid request (`Error`)

### 401

Missing or invalid credentials (`Error`)

### 403

Not allowed (`Error`)

### 404

Not found (`Error`)

## Example

```bash
curl -X POST https://api.tryyoursize.com/v1/returns \
  -H "Authorization: Bearer $TRYYOURSIZE_SECRET_KEY" \
  -H "TYS-Version: 2026-10-25" \
  -H "Content-Type: application/json" \
  -d @body.json
```

## In the SDKs

- Node.js: [`tys.returns.create()`](https://docs.tryyoursize.com/reference/node/returns-create.md)
- Python: [`tys.returns.create()`](https://docs.tryyoursize.com/reference/python/returns-create.md)