---
search:
  tags:
    - Orders
    - POST
seo:
  description: >-
    Beta — this endpoint is unstable; its request and response shapes may…
    Reference for the POST /orders/{orderId}/return-requests endpoint in the
    Sibi API.
sidebar:
  label: Start a return (Beta)
  badge: POST
title: Start a return (Beta)
type: openapi-operation
---
**Beta** — this endpoint is unstable; its request and response shapes may change.

Opens a return request for one or more lines of an order. A `201` means the request was opened — not that any line is approved yet. Every requested line starts `Pending`.

**Learning the outcome:** Sibi staff approve or deny each line independently (one request can end with some lines approved and others denied). Learn the result by subscribing to the `order.returnrequest.item-approved` and `order.returnrequest.item-denied` webhook events — see [Order Return Requests events](https://docs.sibipro.com/events/order.return-requests) — or by re-reading the order with `GET /orders/{orderId}`, whose `returnRequests` array carries each line’s current `status`.

A line that is not eligible, is not on the order, appears more than once, or exceeds the returnable quantity is rejected with a `400`. The `400` lists every failing line in `details[]` — each carrying its own `code` from the set below — and no return request is created unless all lines pass.

| Code | Meaning |
| --- | --- |
| `RETURN_INVALID_CONDITION` | The `condition` is not one of the accepted values |
| `RETURN_INVALID_QUANTITY` | The `quantity` is not a positive whole number |
| `RETURN_DUPLICATE_LINE` | The same order line appears more than once in the request |
| `RETURN_LINE_NOT_ON_ORDER` | The `sku` does not match any line on the order |
| `RETURN_AMBIGUOUS_SKU` | The `sku` matches more than one line on the order, so it cannot identify a single line to return |
| `RETURN_ITEM_NOT_ELIGIBLE` | Policy or current state does not allow returning this line — see the line’s `reasonCode` (e.g. `ALREADY_REQUESTED` when a return request already exists for it, `RETURN_WINDOW_EXPIRED`, `ALREADY_RETURNED`) |
| `RETURN_QUANTITY_EXCEEDED` | The requested quantity exceeds what remains returnable on the line |

`POST /orders/{orderId}/return-requests`

**Request body** (`application/json`)

- `items` (ReturnRequestItemInput[], required) — The lines to return. At least one; each must reference a distinct order line.

Request body example:

```json
{
  "items": [
    {
      "sku": "GDF510PSRSS",
      "quantity": 1,
      "condition": "UNOPENED",
      "requestReason": "Ordered the wrong size"
    }
  ]
}
```

**Responses**

- `201` — The return request was opened. Every line starts Pending.
- `400` — Bad request - Invalid input data. See the operation description for the possible error codes.
- `401` — Unauthorized - Missing or invalid authentication
- `403` — Forbidden - the token was minted for the other environment, is not a Public REST API token, does not carry the scope this operation requires, or targeted the test environment (the Returns API is production-only)
- `404` — Not found - no order with the given id is visible to the caller, or its return data could not be resolved
- `500` — Internal server error

Response example, 201:

```json
{
  "orderId": "SIBI-12345678",
  "createdAt": "string",
  "updatedAt": "string",
  "items": [
    {
      "sku": "GDF510PSRSS",
      "quantity": 0,
      "condition": "UNOPENED",
      "requestReason": "string",
      "status": "Pending",
      "denialReason": "string"
    }
  ]
}
```

Response example, 400 · validationError:

```json
{
  "code": "VALIDATION_ERROR",
  "message": "Invalid input parameters"
}
```

Response example, 400 · itemNotEligible:

```json
{
  "code": "RETURN_ITEM_NOT_ELIGIBLE",
  "message": "This item is not eligible for return."
}
```

Response example, 401:

```json
{
  "code": "UNAUTHORIZED",
  "message": "Missing or invalid authentication token"
}
```

Response example, 403 · environmentMismatch:

```json
{
  "code": "TOKEN_ENVIRONMENT_MISMATCH",
  "message": "A test token was used against the production API. Test tokens only work against the Sibi test environment; use a production token here."
}
```

Response example, 403 · restTokenRequired:

```json
{
  "code": "REST_TOKEN_REQUIRED",
  "message": "This endpoint only accepts Public REST API tokens. Create one at https://developer.sibipro.com."
}
```

Response example, 403 · insufficientScope:

```json
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "The presented token is missing the `create:returns` scope, which this endpoint requires. Create a token with the scopes you need at https://developer.sibipro.com."
}
```

Response example, 403 · notAvailableInTest:

```json
{
  "code": "NOT_AVAILABLE_IN_TEST",
  "message": "The Returns API is not available in the test environment."
}
```

Response example, 404:

```json
{
  "code": "ORDER_NOT_FOUND",
  "message": "Unable to find order with id: SIBI-12345678"
}
```

Response example, 500:

```json
{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred"
}
```