# Cancel an item (/docs/api-reference/order-items/cancel)

`POST /v1/order-items/{id}/cancel`

Cancels an order item and refunds what was paid for it, less any cancellation penalty.

Available when the item's `actions.cancellation` is `available`; while a refund is running it shows
`inProgress`, and `manualReview` means support must handle it. A rejected item is refunded in full
automatically and reported by `order-item.refunded`; the `fulfillmentFailed` reason then returns
that refund. The `fulfillmentFailed` reason is accepted only for a rejected item; a
cancellation that is not valid for the item returns `400` with code `10001`. A delivered item of a
kind that cannot take back a delivery (airtime, utility, gift cards, eSIMs) can never be cancelled and
returns `422` with code `18000` (`CANCELLATION_NOT_SUPPORTED`). Otherwise a cancellation that
is not allowed now, for example while the item is still being delivered, returns `409` with code
`18001` (`CANCELLATION_NOT_AVAILABLE`), and `details[0].reason` repeats
`actions.cancellation.availability` (`IN_PROGRESS`, `MANUAL_REVIEW` or `NOT_AVAILABLE`).
The same `409` with `IN_PROGRESS` answers a cancel that meets a refund, a delivery or a change of
the same order still running; send it again shortly. The amount is recalculated at this point, so it can
differ from an earlier cancellation preview. A refund started by OpenRoam support returns the same
`409` with `MANUAL_REVIEW`. An item of another partner, or an unknown id, returns `404` with
code `10004`.
            
Returns the `orderItemId`, the refund `amount`, the `method` it is returned to and its
`status`. A balance payment is refunded to the wallet that paid it. Refund progress is also reported
by the `order-item.refunded` webhook.
            
Requires an `Idempotency-Key` header (a UUID). Repeating a completed request with the same key and body
returns `200` with the refund that request started, as it reads now, and refunds nothing again. One
still running returns `409` with code `12002` (`IDEMPOTENCY_KEY_IN_PROGRESS`) and a
`Retry-After` header, and a different body with the same key `409` with code `12001`. A
request that ended in an error can be sent again with the same key and body.

## Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | Order item id (`items[].id` from the order response). |
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |

## Request body

- `application/json`: `OrderItemCancelRequest`
- `text/json`: `OrderItemCancelRequest`
- `application/*+json`: `OrderItemCancelRequest`

## Responses

### 200

OK

- `text/plain`: `OrderItemCancelResult`
- `application/json`: `OrderItemCancelResult`
- `text/json`: `OrderItemCancelResult`

### 400

Invalid partner request or model validation failure.

- `application/json`: `ErrorResponse`

### 404

Not Found

- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`

### 409

The idempotency key: a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; or it was used for a different request (12001). A finished request sent again with the same key and body returns 200 with the result of the first call, rebuilt from the record that call created as it reads now: nothing runs again, and a status that has moved on since shows its current value.

- `application/json`: `ErrorResponse`

### 422

Unprocessable Content

- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`

### 429

Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.

- `application/json`: `ErrorResponse`

### 503

Idempotency state is temporarily unavailable; retry the same request and key.

- `application/json`: `ErrorResponse`

The full schemas are in the OpenAPI specification at /openapi.json.