---
title: "Create a reservation"
method: POST
path: "/inventory/reservations"
tags: ["Inventory"]
---

# Create a reservation

`POST /inventory/reservations`

## Request

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

Creates an atomic hold across multiple variants, with a time-to-live (TTL). All items in the hold are reserved together, or none are, so a reservation can never oversell.

The hold is protocol-neutral: it is bound to an `owner_type` and `owner_reference` supplied by the calling protocol adapter, for example a UCP session or an ACP checkout.

Requires the `agentic:inventory` scope.

## Headers

- `Cko-Idempotency-Key` string

## Request body

- InventoryReservationRequest: <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> The request body for creating an atomic multi-variant hold. All items are reserved together or none are. The hold is protocol-neutral: it is bound to an `owner_type` / `owner_reference` supplied by the calling protocol adapter (for example, a UCP session or an ACP checkout).
  - `owner_type` string, required: The kind of caller that owns the hold.
  - `owner_reference` string, required: An opaque reference to the owning session or checkout.
  - `items` InventoryReservationItem[], required: The variants and quantities to hold. `variant_id`s must be unique within the request.
    - `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.
  - `ttl_seconds` integer: How long the hold remains valid before it auto-expires. Defaults to `900`.

## Response `200`

Idempotent replay of an earlier reservation made with the same key.

- 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

- `201`: The reservation was created and the stock is held.
- `401`: Missing or invalid token.
- `403`: The token does not carry the `agentic:inventory` scope.
- `404`: One of the requested variants does not exist.
- `409`: Not enough stock to hold one of the variants or the idempotency key was reused with a different request body.
- `422`: Request validation failed.
- `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)