# Update an item (/docs/api-reference/order-items/update)

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

Updates a delivered order item, without a charge.

Changes what the item's kind lets a partner change after the purchase, in one call. An update never charges
or refunds anything: a change with a price, such as a hotel or flight change, is an amendment
(`POST /order-items/{id}/amendments/quote`). At launch only gift cards can be updated: `inputs`
takes a new `recipientEmail` and `giftMessage`, and the gift email is sent again, to the new address
with the new message. A card bought without a recipient needs `recipientEmail`. Every other kind of item
returns `422` with code `18004` (`UPDATE_NOT_SUPPORTED`).
            
Available when the item's `actions.update` is `available`; otherwise the update returns `409`
with code `18005` (`UPDATE_NOT_AVAILABLE`), and `details[0].reason` repeats
`actions.update.availability` (`IN_PROGRESS` or `NOT_AVAILABLE`). The same `409` is
returned when the item stops being available during the call, for example after a cancel.
            
A member of `inputs` left out or sent as `null` keeps its current value, and at least one member
must be present. An invalid member returns `400` with code `10001` at `inputs.<member>`,
with the same reasons as the order's `inputs`, and a member the item's kind does not define returns
`400` with code `10001` and reason `UNSUPPORTED_FIELD`. An item of another partner, or an
unknown id, returns `404` with code `10004`. A malformed body (not valid JSON, `inputs`
missing, `null` or not an object, or a top-level member other than `inputs`) returns `400`
with code `10001` before the item is read. The checks on the item then run in this order: `404`,
`422`, `409`, then `400` for the members of `inputs`.
            
Returns the item exactly as `GET /order-items/{id}` returns it. No webhook is sent for an update.
            
Requires an `Idempotency-Key` header (a UUID). Repeating a completed request with the same key and body
returns `200` with the item as `GET /order-items/{id}` returns it now, and changes nothing again
(no gift email is sent 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. Updating the same item again needs a new key.

## 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`: `OrderItemUpdateRequest`
- `text/json`: `OrderItemUpdateRequest`
- `application/*+json`: `OrderItemUpdateRequest`

## Responses

### 200

OK

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

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