---
title: "Get a reservation"
method: GET
path: "/inventory/reservations/{id}"
tags: ["Inventory"]
---

# Get a reservation

`GET /inventory/reservations/{id}`

## Request

- Base URL: `https://{prefix}.api.sandbox.checkout.com`
- URL: `https://{prefix}.api.sandbox.checkout.com/inventory/reservations/{id}`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `string` scopes: `agentic:inventory`
- TypeScript: <https://skmtc.dev/checkout/apis/checkout-com-api-reference/docs/inventory/reservations/:id/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns a reservation in any state. A reservation with a `held` status past its `expires_at` is reported as `expired`.
The `_links` field returns the operations valid for the reservation's current state.

Requires the `agentic:inventory` scope. A reservation owned by another merchant returns `404`.

## Path parameters

- `id` string, required

## Response `200`

The reservation.

- InventoryReservation: <span style="font-size: 12px; font-weight: 500; color: rgb(0, 0, 0); background-color: rgb(255, 176, 97); border-radius: 4px; padding: 2px 6px" >Beta</span><p></p> A stock hold and its current lifecycle state.
  - `id` string: The reservation identifier, in the `rsv_{base32-encoded GUID}` format.
  - `state` 'held' | 'committed' | 'released' | 'expired': The current state of the hold. A `held` reservation past its `expires_at` is reported as `expired`. Transitions out of `held` are terminal.
  - `owner_type` string: Echo of the owning caller kind.
  - `owner_reference` string: Echo of the owning session or checkout reference.
  - `items` InventoryReservationItem[]: The variants and quantities held by this reservation.
    - `variant_id` string, required: The identifier of the variant to hold. The variant must already exist.
    - `quantity` integer, required: The quantity to hold for this variant.
  - `expires_at` string, date-time: The server-authoritative time at which the hold expires.
  - `created_on` string, date-time: The date and time the reservation was created.
  - `_links` object: Links to the operations valid for the reservation's current state. A `held` reservation exposes `self`, `commit` and `release`; a terminal reservation exposes `self` only.
    - `self` InventoryHalLink: A HAL link describing a related operation on the resource.
      - `href` string: Absolute URI of the linked resource.
      - `actions` string[]: The HTTP methods supported on the linked resource.
      - `types` string[]: The media types supported on the linked resource.
    - `commit` InventoryHalLink: A HAL link describing a related operation on the resource.
      - `href` string: Absolute URI of the linked resource.
      - `actions` string[]: The HTTP methods supported on the linked resource.
      - `types` string[]: The media types supported on the linked resource.
    - `release` InventoryHalLink: A HAL link describing a related operation on the resource.
      - `href` string: Absolute URI of the linked resource.
      - `actions` string[]: The HTTP methods supported on the linked resource.
      - `types` string[]: The media types supported on the linked resource.

## Other responses

- `401`: Missing or invalid token.
- `403`: The token does not carry the `agentic:inventory` scope.
- `404`: The reservation does not exist, or is owned by another merchant (`reservation_not_found`).
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)