Inventory

​

Beta

Manage stock levels for each product variant (e.g. size or color) and temporarily hold stock while an AI agent completes a checkout. Each hold can later be confirmed or cancelled, and automatically expires on its own if left unresolved. This prevents overselling, even when multiple agents are buying at the same time. Holds work the same way regardless of which agentic commerce protocol is used.

Requires the agentic:inventory scope. To onboard your AI platform, contact us.

Inventory Operations

Get stock levels

​

Returns the current stock levels and sellable availability for a single variant.

available is clamped to zero: max(0, on_hand − reserved − safety_stock) — this is the value an availability feed should publish.

Requires the agentic:inventory scope. The merchant is resolved from the token claims; a variant owned by another merchant returns 404.

Path Parameters
  • variant_id
    Type: string
    max length:  
    128
    required

    The merchant-provided identifier for the variant.

Query Parameters
  • expand
    enum
    const:  
    product

    Set expand=product to embed an additional product field alongside the stock fields, containing the variant's product knowledge (merchandising details such as title, description, and images). Setting this parameter does not change how available or the other stock fields are calculated. If product knowledge has not been set for the variant, the product field is omitted.

    values
    • product
Responses
  • application/json
  • 401

    Missing or invalid token.

  • 403

    The token does not carry the agentic:inventory scope.

  • application/json
  • 429

    Rate limit exceeded.

Request Example for get/inventory/{variant_id}
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/inventory/var_123' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "variant_id": "var_123",
  "on_hand": 10,
  "reserved": 2,
  "safety_stock": 1,
  "available": 7,
  "state": "in_stock",
  "source": "managed",
  "created_on": "2026-07-01T09:15:00Z",
  "modified_on": "2026-07-13T14:02:11Z",
  "product": {
    "variant_id": "var_123",
    "title": "Classic leather belt, brown",
    "description": "A full-grain leather belt with a brushed nickel buckle.",
    "product_url": "https://merchant.example.com/products/classic-leather-belt-brown",
    "image_url": "https://merchant.example.com/images/belt-brown-main.jpg",
    "additional_image_urls": [
      "https://merchant.example.com/images/belt-brown-alt1.jpg"
    ],
    "video_url": "https://merchant.example.com/videos/belt-brown.mp4",
    "model_3d_url": "https://merchant.example.com/models/belt-brown.glb",
    "sku": "BELT-BRN-001",
    "gtin": "00012345678905",
    "mpn": "MPN-4471",
    "brand": "Acme Leathercraft",
    "category": "Apparel & Accessories > Belts",
    "price": {
      "amount": 1999,
      "currency": "USD"
    },
    "sale_price": {
      "amount": 1999,
      "currency": "USD"
    },
    "sale_price_starts_at": "2026-08-01T00:00:00Z",
    "sale_price_ends_at": "2026-08-31T23:59:59Z",
    "group_id": "grp_belt_classic",
    "group_title": "Classic leather belt",
    "color": "Brown",
    "size": "M",
    "size_system": "US",
    "gender": "unisex",
    "condition": "new",
    "material": "Full-grain leather",
    "age_group": "adult",
    "length": 110,
    "width": 3.5,
    "height": 0.5,
    "dimension_unit": "cm",
    "weight": 0.2,
    "weight_unit": "kg",
    "expiration_date": "2027-01-01T00:00:00Z",
    "harmonized_system_code": "4203.30",
    "country_of_origin": "IT",
    "seller_name": "Acme Leathercraft Ltd",
    "seller_url": "https://acme-leathercraft.example.com",
    "seller_privacy_policy": "https://acme-leathercraft.example.com/privacy",
    "seller_tos": "https://acme-leathercraft.example.com/terms",
    "created_on": "2026-08-01T09:15:00Z",
    "modified_on": "2026-08-13T14:02:11Z",
    "_links": {
      "self": {
        "href": "https://api.checkout.com/inventory/var_123",
        "actions": [
          "GET"
        ],
        "types": [
          "application/json"
        ]
      },
      "set": {
        "href": "https://api.checkout.com/inventory/var_123",
        "actions": "[Circular]",
        "types": "[Circular]"
      },
      "delete": {
        "href": "https://api.checkout.com/inventory/var_123",
        "actions": "[Circular]",
        "types": "[Circular]"
      }
    }
  },
  "_links": {
    "self": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    },
    "set": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    }
  }
}

The current stock levels for the variant.

Set stock levels

​

Sets the absolute stock levels for a variant (Managed mode and corrections). The call is an upsert: it returns 201 when the inventory item is created and 200 when an existing item is updated. Availability is recomputed and a set entry is written to the ledger. Active reservations are never disturbed.

Requires the agentic:inventory scope.

Path Parameters
  • variant_id
    Type: string
    max length:  
    128
    required

    The merchant-provided identifier for the variant.

Body·
required
application/json

Beta

The request body for setting absolute stock levels on a variant.

  • on_hand
    Type: integer
    min:  
    0
    required

    The absolute physical stock to set for the variant.

  • safety_stock
    Type: integer
    min:  
    0

    The buffer quantity to withhold from sale. Defaults to 0 when the item is created and is left unchanged on update if omitted.

  • reason
    Type: string
    max length:  
    256

    An optional free-text reason recorded in the ledger. Must not contain personal data.

Responses
  • application/json
  • application/json
  • 401

    Missing or invalid token.

  • 403

    The token does not carry the agentic:inventory scope.

  • application/json
  • 429

    Rate limit exceeded.

Request Example for put/inventory/{variant_id}
curl 'https://{prefix}.api.sandbox.checkout.com/inventory/var_123' \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "on_hand": 25,
  "safety_stock": 2,
  "reason": "stock take 2026-07"
}'

{
  "variant_id": "var_123",
  "on_hand": 10,
  "reserved": 2,
  "safety_stock": 1,
  "available": 7,
  "state": "in_stock",
  "source": "managed",
  "created_on": "2026-07-01T09:15:00Z",
  "modified_on": "2026-07-13T14:02:11Z",
  "product": {
    "variant_id": "var_123",
    "title": "Classic leather belt, brown",
    "description": "A full-grain leather belt with a brushed nickel buckle.",
    "product_url": "https://merchant.example.com/products/classic-leather-belt-brown",
    "image_url": "https://merchant.example.com/images/belt-brown-main.jpg",
    "additional_image_urls": [
      "https://merchant.example.com/images/belt-brown-alt1.jpg"
    ],
    "video_url": "https://merchant.example.com/videos/belt-brown.mp4",
    "model_3d_url": "https://merchant.example.com/models/belt-brown.glb",
    "sku": "BELT-BRN-001",
    "gtin": "00012345678905",
    "mpn": "MPN-4471",
    "brand": "Acme Leathercraft",
    "category": "Apparel & Accessories > Belts",
    "price": {
      "amount": 1999,
      "currency": "USD"
    },
    "sale_price": {
      "amount": 1999,
      "currency": "USD"
    },
    "sale_price_starts_at": "2026-08-01T00:00:00Z",
    "sale_price_ends_at": "2026-08-31T23:59:59Z",
    "group_id": "grp_belt_classic",
    "group_title": "Classic leather belt",
    "color": "Brown",
    "size": "M",
    "size_system": "US",
    "gender": "unisex",
    "condition": "new",
    "material": "Full-grain leather",
    "age_group": "adult",
    "length": 110,
    "width": 3.5,
    "height": 0.5,
    "dimension_unit": "cm",
    "weight": 0.2,
    "weight_unit": "kg",
    "expiration_date": "2027-01-01T00:00:00Z",
    "harmonized_system_code": "4203.30",
    "country_of_origin": "IT",
    "seller_name": "Acme Leathercraft Ltd",
    "seller_url": "https://acme-leathercraft.example.com",
    "seller_privacy_policy": "https://acme-leathercraft.example.com/privacy",
    "seller_tos": "https://acme-leathercraft.example.com/terms",
    "created_on": "2026-08-01T09:15:00Z",
    "modified_on": "2026-08-13T14:02:11Z",
    "_links": {
      "self": {
        "href": "https://api.checkout.com/inventory/var_123",
        "actions": [
          "GET"
        ],
        "types": [
          "application/json"
        ]
      },
      "set": {
        "href": "https://api.checkout.com/inventory/var_123",
        "actions": "[Circular]",
        "types": "[Circular]"
      },
      "delete": {
        "href": "https://api.checkout.com/inventory/var_123",
        "actions": "[Circular]",
        "types": "[Circular]"
      }
    }
  },
  "_links": {
    "self": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    },
    "set": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    }
  }
}

The variant already existed and its levels were updated.

Get product knowledge

​

Beta

Returns the product knowledge for a single variant.

Requires the agentic:inventory scope. The merchant is resolved from the token claims; a variant owned by another merchant, or one with no product knowledge set, returns 404.

Path Parameters
  • variant_id
    Type: string
    max length:  
    128
    required

    The merchant-provided identifier for the variant.

Responses
  • application/json
  • 401

    Missing or invalid token.

  • 403

    The token does not carry the agentic:inventory scope.

  • application/json
  • 429

    Rate limit exceeded.

Request Example for get/inventory/{variant_id}/product
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/inventory/var_123/product' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "variant_id": "var_123",
  "title": "Classic leather belt, brown",
  "description": "A full-grain leather belt with a brushed nickel buckle.",
  "product_url": "https://merchant.example.com/products/classic-leather-belt-brown",
  "image_url": "https://merchant.example.com/images/belt-brown-main.jpg",
  "additional_image_urls": [
    "https://merchant.example.com/images/belt-brown-alt1.jpg"
  ],
  "video_url": "https://merchant.example.com/videos/belt-brown.mp4",
  "model_3d_url": "https://merchant.example.com/models/belt-brown.glb",
  "sku": "BELT-BRN-001",
  "gtin": "00012345678905",
  "mpn": "MPN-4471",
  "brand": "Acme Leathercraft",
  "category": "Apparel & Accessories > Belts",
  "price": {
    "amount": 1999,
    "currency": "USD"
  },
  "sale_price": {
    "amount": 1999,
    "currency": "USD"
  },
  "sale_price_starts_at": "2026-08-01T00:00:00Z",
  "sale_price_ends_at": "2026-08-31T23:59:59Z",
  "group_id": "grp_belt_classic",
  "group_title": "Classic leather belt",
  "color": "Brown",
  "size": "M",
  "size_system": "US",
  "gender": "unisex",
  "condition": "new",
  "material": "Full-grain leather",
  "age_group": "adult",
  "length": 110,
  "width": 3.5,
  "height": 0.5,
  "dimension_unit": "cm",
  "weight": 0.2,
  "weight_unit": "kg",
  "expiration_date": "2027-01-01T00:00:00Z",
  "harmonized_system_code": "4203.30",
  "country_of_origin": "IT",
  "seller_name": "Acme Leathercraft Ltd",
  "seller_url": "https://acme-leathercraft.example.com",
  "seller_privacy_policy": "https://acme-leathercraft.example.com/privacy",
  "seller_tos": "https://acme-leathercraft.example.com/terms",
  "created_on": "2026-08-01T09:15:00Z",
  "modified_on": "2026-08-13T14:02:11Z",
  "_links": {
    "self": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": [
        "GET"
      ],
      "types": [
        "application/json"
      ]
    },
    "set": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    },
    "delete": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    }
  }
}

The product knowledge for the variant.

Set product knowledge

​

Beta

Sets the product knowledge for a variant. The call is an upsert: it returns 201 when the product knowledge is created and 200 when it is updated.

Requires the agentic:inventory scope.

Path Parameters
  • variant_id
    Type: string
    max length:  
    128
    required

    The merchant-provided identifier for the variant.

Body·
required
application/json

Beta

The request body for setting the product knowledge for a variant. The call is an upsert.

  • title
    Type: string
    max length:  
    512
    required

    The product's display title.

  • description
    Type: string
    max length:  
    4000
    required

    The product's display description.

  • product_url
    Type: string
    max length:  
    2048
    required

    The canonical URL for the product page.

  • image_url
    Type: string
    max length:  
    2048
    required

    The URL of the primary product image.

  • additional_image_urls
    Type: array string[]

    Additional product image URLs, beyond image_url.

  • video_url
    Type: string

    The URL of a product video.

  • model_3d_url
    Type: string

    The URL of a 3D model of the product.

  • sku
    Type: string
    max length:  
    128

    The merchant's stock-keeping unit for the product.

  • gtin
    Type: string

    The product's Global Trade Item Number (UPC, EAN, ISBN, or JAN).

  • mpn
    Type: string

    The product's Manufacturer Part Number.

  • brand
    Type: string

    The product's brand name.

  • category
    Type: string

    The merchant's category for the product.

Responses
  • application/json
  • application/json
  • 401

    Missing or invalid token.

  • 403

    The token does not carry the agentic:inventory scope.

  • application/json
  • 429

    Rate limit exceeded.

Request Example for put/inventory/{variant_id}/product
curl 'https://{prefix}.api.sandbox.checkout.com/inventory/var_123/product' \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "title": "Classic leather belt, brown",
  "description": "A full-grain leather belt with a brushed nickel buckle.",
  "product_url": "https://merchant.example.com/products/classic-leather-belt-brown",
  "image_url": "https://merchant.example.com/images/belt-brown-main.jpg",
  "additional_image_urls": [
    "https://merchant.example.com/images/belt-brown-alt1.jpg"
  ],
  "video_url": "https://merchant.example.com/videos/belt-brown.mp4",
  "model_3d_url": "https://merchant.example.com/models/belt-brown.glb",
  "sku": "BELT-BRN-001",
  "gtin": "00012345678905",
  "mpn": "MPN-4471",
  "brand": "Acme Leathercraft",
  "category": "Apparel & Accessories > Belts",
  "price": {
    "amount": 1999,
    "currency": "USD"
  },
  "sale_price": {
    "amount": 1999,
    "currency": "USD"
  },
  "sale_price_starts_at": "2026-08-01T00:00:00Z",
  "sale_price_ends_at": "2026-08-31T23:59:59Z",
  "group_id": "grp_belt_classic",
  "group_title": "Classic leather belt",
  "color": "Brown",
  "size": "M",
  "size_system": "US",
  "gender": "unisex",
  "condition": "new",
  "material": "Full-grain leather",
  "age_group": "adult",
  "length": 110,
  "width": 3.5,
  "height": 0.5,
  "dimension_unit": "cm",
  "weight": 0.2,
  "weight_unit": "kg",
  "expiration_date": "2027-01-01T00:00:00Z",
  "harmonized_system_code": "4203.30",
  "country_of_origin": "IT",
  "seller_name": "Acme Leathercraft Ltd",
  "seller_url": "https://acme-leathercraft.example.com",
  "seller_privacy_policy": "https://acme-leathercraft.example.com/privacy",
  "seller_tos": "https://acme-leathercraft.example.com/terms"
}'

{
  "variant_id": "var_123",
  "title": "Classic leather belt, brown",
  "description": "A full-grain leather belt with a brushed nickel buckle.",
  "product_url": "https://merchant.example.com/products/classic-leather-belt-brown",
  "image_url": "https://merchant.example.com/images/belt-brown-main.jpg",
  "additional_image_urls": [
    "https://merchant.example.com/images/belt-brown-alt1.jpg"
  ],
  "video_url": "https://merchant.example.com/videos/belt-brown.mp4",
  "model_3d_url": "https://merchant.example.com/models/belt-brown.glb",
  "sku": "BELT-BRN-001",
  "gtin": "00012345678905",
  "mpn": "MPN-4471",
  "brand": "Acme Leathercraft",
  "category": "Apparel & Accessories > Belts",
  "price": {
    "amount": 1999,
    "currency": "USD"
  },
  "sale_price": {
    "amount": 1999,
    "currency": "USD"
  },
  "sale_price_starts_at": "2026-08-01T00:00:00Z",
  "sale_price_ends_at": "2026-08-31T23:59:59Z",
  "group_id": "grp_belt_classic",
  "group_title": "Classic leather belt",
  "color": "Brown",
  "size": "M",
  "size_system": "US",
  "gender": "unisex",
  "condition": "new",
  "material": "Full-grain leather",
  "age_group": "adult",
  "length": 110,
  "width": 3.5,
  "height": 0.5,
  "dimension_unit": "cm",
  "weight": 0.2,
  "weight_unit": "kg",
  "expiration_date": "2027-01-01T00:00:00Z",
  "harmonized_system_code": "4203.30",
  "country_of_origin": "IT",
  "seller_name": "Acme Leathercraft Ltd",
  "seller_url": "https://acme-leathercraft.example.com",
  "seller_privacy_policy": "https://acme-leathercraft.example.com/privacy",
  "seller_tos": "https://acme-leathercraft.example.com/terms",
  "created_on": "2026-08-01T09:15:00Z",
  "modified_on": "2026-08-13T14:02:11Z",
  "_links": {
    "self": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": [
        "GET"
      ],
      "types": [
        "application/json"
      ]
    },
    "set": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    },
    "delete": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    }
  }
}

The variant already had product knowledge, and it was updated.

Delete product knowledge

​

Beta

Deletes the product knowledge for a variant. Stock levels and reservations for the variant are unaffected.

Requires the agentic:inventory scope.

Path Parameters
  • variant_id
    Type: string
    max length:  
    128
    required

    The merchant-provided identifier for the variant.

Responses
  • 401

    Missing or invalid token.

  • 403

    The token does not carry the agentic:inventory scope.

  • application/json
  • 429

    Rate limit exceeded.

Request Example for delete/inventory/{variant_id}/product
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/inventory/var_123/product' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No Body

The product knowledge existed and was deleted.

Adjust stock

​

Applies a relative delta to a variant's physical stock (on_hand) with a mandatory reason (for example, damaged or found stock). The call fails if the delta drives the physical stock below zero. An adjust entry is written to the ledger.

Requires the agentic:inventory scope.

Headers
  • Cko-Idempotency-Key
    Type: string

    An optional idempotency key for safely retrying payment requests

Body·
required
application/json

Beta

The request body for applying a relative adjustment to a variant's on-hand stock.

  • variant_id
    Type: string
    max length:  
    128
    required

    The identifier of the variant to adjust. The variant must already exist.

  • delta
    Type: integer
    required

    The signed change to apply to on_hand. Must be non-zero. A negative delta that would drive on_hand below zero is rejected with 409 conflict.

  • reason
    Type: string
    min length:  
    1
    max length:  
    256
    required

    A required free-text reason recorded in the ledger (for example, damage or found stock). Must not contain personal data.

Responses
  • application/json
  • application/json
  • 401

    Missing or invalid token.

  • 403

    The token does not carry the agentic:inventory scope.

  • application/json
  • application/json
  • application/json
  • 429

    Rate limit exceeded.

Request Example for post/inventory/adjustments
curl 'https://{prefix}.api.sandbox.checkout.com/inventory/adjustments' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "variant_id": "var_123",
  "delta": -3,
  "reason": "damaged in warehouse"
}'

{
  "variant_id": "var_123",
  "on_hand": 10,
  "reserved": 2,
  "safety_stock": 1,
  "available": 7,
  "state": "in_stock",
  "source": "managed",
  "created_on": "2026-07-01T09:15:00Z",
  "modified_on": "2026-07-13T14:02:11Z",
  "product": {
    "variant_id": "var_123",
    "title": "Classic leather belt, brown",
    "description": "A full-grain leather belt with a brushed nickel buckle.",
    "product_url": "https://merchant.example.com/products/classic-leather-belt-brown",
    "image_url": "https://merchant.example.com/images/belt-brown-main.jpg",
    "additional_image_urls": [
      "https://merchant.example.com/images/belt-brown-alt1.jpg"
    ],
    "video_url": "https://merchant.example.com/videos/belt-brown.mp4",
    "model_3d_url": "https://merchant.example.com/models/belt-brown.glb",
    "sku": "BELT-BRN-001",
    "gtin": "00012345678905",
    "mpn": "MPN-4471",
    "brand": "Acme Leathercraft",
    "category": "Apparel & Accessories > Belts",
    "price": {
      "amount": 1999,
      "currency": "USD"
    },
    "sale_price": {
      "amount": 1999,
      "currency": "USD"
    },
    "sale_price_starts_at": "2026-08-01T00:00:00Z",
    "sale_price_ends_at": "2026-08-31T23:59:59Z",
    "group_id": "grp_belt_classic",
    "group_title": "Classic leather belt",
    "color": "Brown",
    "size": "M",
    "size_system": "US",
    "gender": "unisex",
    "condition": "new",
    "material": "Full-grain leather",
    "age_group": "adult",
    "length": 110,
    "width": 3.5,
    "height": 0.5,
    "dimension_unit": "cm",
    "weight": 0.2,
    "weight_unit": "kg",
    "expiration_date": "2027-01-01T00:00:00Z",
    "harmonized_system_code": "4203.30",
    "country_of_origin": "IT",
    "seller_name": "Acme Leathercraft Ltd",
    "seller_url": "https://acme-leathercraft.example.com",
    "seller_privacy_policy": "https://acme-leathercraft.example.com/privacy",
    "seller_tos": "https://acme-leathercraft.example.com/terms",
    "created_on": "2026-08-01T09:15:00Z",
    "modified_on": "2026-08-13T14:02:11Z",
    "_links": {
      "self": {
        "href": "https://api.checkout.com/inventory/var_123",
        "actions": [
          "GET"
        ],
        "types": [
          "application/json"
        ]
      },
      "set": {
        "href": "https://api.checkout.com/inventory/var_123",
        "actions": "[Circular]",
        "types": "[Circular]"
      },
      "delete": {
        "href": "https://api.checkout.com/inventory/var_123",
        "actions": "[Circular]",
        "types": "[Circular]"
      }
    }
  },
  "_links": {
    "self": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    },
    "set": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    }
  }
}

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

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.

Headers
  • Cko-Idempotency-Key
    Type: string

    An optional idempotency key for safely retrying payment requests

Body·
required
application/json

Beta

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
    Type: string
    max length:  
    64
    required

    The kind of caller that owns the hold.

  • owner_reference
    Type: string
    max length:  
    256
    required

    An opaque reference to the owning session or checkout.

  • items
    Type: array object[] · 1…45
    required

    The variants and quantities to hold. variant_ids must be unique within the request.

    A single variant and quantity within a reservation.

  • ttl_seconds
    Type: integer
    min:  
    60
    max:  
    3600

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

Responses
  • application/json
  • application/json
  • 401

    Missing or invalid token.

  • 403

    The token does not carry the agentic:inventory scope.

  • application/json
  • application/json
  • application/json
  • 429

    Rate limit exceeded.

Request Example for post/inventory/reservations
curl 'https://{prefix}.api.sandbox.checkout.com/inventory/reservations' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "owner_type": "ucp_session",
  "owner_reference": "cs_8f42",
  "items": [
    {
      "variant_id": "var_123",
      "quantity": 2
    }
  ],
  "ttl_seconds": 900
}'

{
  "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:00Z",
  "created_on": "2026-07-14T08:32:00Z",
  "_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": "[Circular]",
      "types": "[Circular]"
    },
    "release": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    }
  }
}

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

Get a reservation

​

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
    Type: string
    required

    The reservation identifier.

Responses
  • application/json
  • 401

    Missing or invalid token.

  • 403

    The token does not carry the agentic:inventory scope.

  • application/json
  • 429

    Rate limit exceeded.

Request Example for get/inventory/reservations/{id}
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/inventory/reservations/rsv_tkoi5db4hryu5cei5vwoabr7we' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "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:00Z",
  "created_on": "2026-07-14T08:32:00Z",
  "_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": "[Circular]",
      "types": "[Circular]"
    },
    "release": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    }
  }
}

The reservation.

Commit a reservation

​

Converts a hold into a sale on order completion. In one atomic transaction, for each held item, on_hand (physical stock) and reserved are decremented. The reservation moves to committed, and commit entries are written to the ledger.

The transaction is conditioned on the reservation still having a held status and not being past its expires_at, so a late commit can never land on an expired hold.

Requires the agentic:inventory scope.

Path Parameters
  • id
    Type: string
    required

    The reservation identifier.

Responses
  • application/json
  • 401

    Missing or invalid token.

  • 403

    The token does not carry the agentic:inventory scope.

  • application/json
  • application/json
  • 429

    Rate limit exceeded.

Request Example for post/inventory/reservations/{id}/commit
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/inventory/reservations/rsv_tkoi5db4hryu5cei5vwoabr7we/commit' \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "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:00Z",
  "created_on": "2026-07-14T08:32:00Z",
  "_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": "[Circular]",
      "types": "[Circular]"
    },
    "release": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    }
  }
}

The reservation was committed (or is already committed).

Release a reservation

​

Releases a hold when a checkout is cancelled or abandoned. In one atomic transaction, for each held item reserved is decremented and available is restored. The reservation moves to released, and release entries are written to the ledger.

Requires the agentic:inventory scope.

Path Parameters
  • id
    Type: string
    required

    The reservation identifier.

Responses
  • application/json
  • 401

    Missing or invalid token.

  • 403

    The token does not carry the agentic:inventory scope.

  • application/json
  • application/json
  • 429

    Rate limit exceeded.

Request Example for post/inventory/reservations/{id}/release
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/inventory/reservations/rsv_tkoi5db4hryu5cei5vwoabr7we/release' \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "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:00Z",
  "created_on": "2026-07-14T08:32:00Z",
  "_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": "[Circular]",
      "types": "[Circular]"
    },
    "release": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    }
  }
}

The reservation was released (or is already released, or had already expired — in which case state reads expired).