CHcheckout
Inventory

Create a reservation

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.

post/inventory/reservations

Request

Headers

Cko-Idempotency-Keystring

An optional idempotency key for safely retrying payment requests

Request body

owner_typestring required

The kind of caller that owns the hold.

owner_referencestring required

An opaque reference to the owning session or checkout.

ttl_secondsinteger

How long the hold remains valid before it auto-expires. Defaults to 900.

Example request

{
  "owner_type": "ucp_session",
  "owner_reference": "cs_8f42",
  "items": [
    {
      "variant_id": "var_123",
      "quantity": 2
    }
  ],
  "ttl_seconds": 900
}

Response

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

idstring

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_typestring

Echo of the owning caller kind.

owner_referencestring

Echo of the owning session or checkout reference.

expires_atstring date-time

The server-authoritative time at which the hold expires.

created_onstring date-time

The date and time the reservation was created.

Example response

{
  "id": "rsv_tkoi5db4hryu5cei5vwoabr7we",
  "state": "held",
  "owner_type": "ucp_session",
  "owner_reference": "cs_8f42",
  "items": [
    {
      "variant_id": "var_123",
      "quantity": 2
    }
  ],
  "expires_at": "2026-07-14T08:47:00.0000000+00:00",
  "created_on": "2026-07-14T08:32:00.0000000+00:00",
  "_links": {
    "self": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": [
        "GET"
      ],
      "types": [
        "application/json"
      ]
    },
    "commit": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": [
        "GET"
      ],
      "types": [
        "application/json"
      ]
    },
    "release": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": [
        "GET"
      ],
      "types": [
        "application/json"
      ]
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.