Checkout.com API logo

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.

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.

SecurityOAuth2: OAuth
Request
path Parameters
variant_id
required
string <= 128 characters

The merchant-provided identifier for the variant.

Example: var_123
query Parameters
expand
string

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.

Value: "product"
Example: expand=product
Responses
200

The current stock levels for the variant.

401

Missing or invalid token.

403

The token does not carry the agentic:inventory scope.

404

The variant does not exist, or is owned by another merchant.

429

Rate limit exceeded.

get/inventory/{variant_id}
Request samples 
Response samples 
application/json
{}
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.


SecurityOAuth2: OAuth 
Request 
path Parameters
variant_id
required
string  <= 128 characters 
The merchant-provided identifier for the variant.


 
 Example:  var_123
Request Body schema: application/json
required
on_hand
required
integer  >= 0 
The absolute physical stock to set for the variant.


 
safety_stock
integer  >= 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
string  <= 256 characters 
An optional free-text reason recorded in the ledger. Must not contain personal data.


 
Responses 
200
The variant already existed and its levels were updated.


201
The inventory item was created.


401
Missing or invalid token.


403
The token does not carry the agentic:inventory scope.


422
Request validation failed.


429
Rate limit exceeded.


put/inventory/{variant_id}
Request samples 
application/json
{
  • "on_hand": 25,
  • "safety_stock": 2,
  • "reason": "stock take 2026-07"
}
Response samples 
application/json
{}
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.


SecurityOAuth2: OAuth 
Request 
path Parameters
variant_id
required
string  <= 128 characters 
The merchant-provided identifier for the variant.


 
 Example:  var_123
Responses 
200
The product knowledge for the variant.


401
Missing or invalid token.


403
The token does not carry the agentic:inventory scope.


404
No product knowledge exists for the variant, or the variant is owned by another
merchant.


429
Rate limit exceeded.


get/inventory/{variant_id}/product
Request samples 
Response samples 
application/json
{}
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.


SecurityOAuth2: OAuth 
Request 
path Parameters
variant_id
required
string  <= 128 characters 
The merchant-provided identifier for the variant.


 
 Example:  var_123
Request Body schema: application/json
required
title
required
string  <= 512 characters 
The product's display title.


 
description
required
string  <= 4000 characters 
The product's display description.


 
product_url
required
string  <= 2048 characters 
The canonical URL for the product page.


 
image_url
required
string  <= 2048 characters 
The URL of the primary product image.


 
additional_image_urls
Array of strings
Additional product image URLs, beyond image_url.


 
video_url
string
The URL of a product video.


 
model_3d_url
string
The URL of a 3D model of the product.


 
sku
string  <= 128 characters 
The merchant's stock-keeping unit for the product.


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


 
mpn
string
The product's Manufacturer Part Number.


 
brand
string
The product's brand name.


 
category
string
The merchant's category for the product.


 
object
The product's regular price. When provided together with sale_price, sale_price must
use the same currency and be less than or equal to price.


 
object
The product's discounted price. Must share price's currency and be less than or equal
to price.


 
sale_price_starts_at
string <date-time> 
The date and time from which sale_price applies. Paired with sale_price.


 
sale_price_ends_at
string <date-time> 
The date and time after which sale_price no longer applies. Paired with sale_price.


 
group_id
string
The identifier shared by all variants of the same product (for example, the same belt in
different sizes). When set, color and size are both required.


 
group_title
string
A display title for the variant group.


 
color
string
The variant's color. Required when group_id is set.


 
size
string
The variant's size. Required when group_id is set.


 
size_system
string
The sizing system that size is expressed in.


 
gender
string
The target gender for the product.


 
condition
string
The product's condition, as an exact lowercase match of one of the enum values.
Defaults to new when omitted.


 Enum: "new" "used" "refurbished"  
material
string
The product's primary material.


 
age_group
string
The target age group for the product.


 
length
number
The product's length. length, width, height and dimension_unit must be provided
together, or not at all.


 
width
number
The product's width. length, width, height and dimension_unit must be provided
together, or not at all.


 
height
number
The product's height. length, width, height and dimension_unit must be provided
together, or not at all.


 
dimension_unit
string
The unit that length, width and height are expressed in. Required when any of
length, width or height is set.


 
weight
number
The product's weight. Must be provided together with weight_unit, or not at all.


 
weight_unit
string
The unit that weight is expressed in. Required when weight is set.


 
expiration_date
string <date-time> 
The date and time after which the product should no longer be offered.


 
harmonized_system_code
string
The product's Harmonized System (HS) code, for customs purposes.


 
country_of_origin
string
The two-letter ISO 3166-1 alpha-2 country of origin.


 
seller_name
string
The name of the seller of record, when different from the merchant.


 
seller_url
string
The URL of the seller of record.


 
seller_privacy_policy
string
The URL of the seller's privacy policy.


 
seller_tos
string
The URL of the seller's terms of service.


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


201
The product knowledge was created for the variant.


401
Missing or invalid token.


403
The token does not carry the agentic:inventory scope.


422
Request validation failed.


429
Rate limit exceeded.


put/inventory/{variant_id}/product
Request samples 
application/json
{}
Response samples 
application/json
{}
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.


SecurityOAuth2: OAuth 
Request 
path Parameters
variant_id
required
string  <= 128 characters 
The merchant-provided identifier for the variant.


 
 Example:  var_123
Responses 
204
The product knowledge existed and was deleted.


401
Missing or invalid token.


403
The token does not carry the agentic:inventory scope.


404
No product knowledge exists for the variant, or the variant is owned by another
merchant.


429
Rate limit exceeded.


delete/inventory/{variant_id}/product
Request samples 
Response samples 
application/json
{
  • "request_id": "req_7f3c9a12b8d54e6f",
  • "error_type": "conflict",
  • "error_codes": [
    ],
  • "variant_id": "var_123",
  • "available": 1
}
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.


SecurityOAuth2: OAuth 
Request 
header Parameters
Cko-Idempotency-Key
string
An optional idempotency key for safely retrying payment requests


 
Request Body schema: application/json
required
variant_id
required
string  <= 128 characters 
The identifier of the variant to adjust. The variant must already exist.


 
delta
required
integer
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
required
string  [ 1 .. 256 ] characters 
A required free-text reason recorded in the ledger (for example, damage or found stock).
Must not contain personal data.


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


201
The adjustment was applied.


401
Missing or invalid token.


403
The token does not carry the agentic:inventory scope.


404
The variant does not exist.


409
The adjustment drives the physical stock below zero.


422
Request validation failed.


429
Rate limit exceeded.


post/inventory/adjustments
Request samples 
application/json
{
  • "variant_id": "var_123",
  • "delta": -3,
  • "reason": "damaged in warehouse"
}
Response samples 
application/json
{}
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.


SecurityOAuth2: OAuth 
Request 
header Parameters
Cko-Idempotency-Key
string
An optional idempotency key for safely retrying payment requests


 
Request Body schema: application/json
required
owner_type
required
string  <= 64 characters 
The kind of caller that owns the hold.


 
owner_reference
required
string  <= 256 characters 
An opaque reference to the owning session or checkout.


 
required
Array of objects (InventoryReservationItem)   [ 1 .. 45 ] items 
The variants and quantities to hold. variant_ids must be unique within the request.


 
ttl_seconds
integer  [ 60 .. 3600 ] 
How long the hold remains valid before it auto-expires. Defaults to 900.


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


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.


post/inventory/reservations
Request samples 
application/json
{
  • "owner_type": "ucp_session",
  • "owner_reference": "cs_8f42",
  • "items": [
    ],
  • "ttl_seconds": 900
}
Response samples 
application/json
{}
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.


SecurityOAuth2: OAuth 
Request 
path Parameters
id
required
string
The reservation identifier.


 
 Example:  rsv_tkoi5db4hryu5cei5vwoabr7we
Responses 
200
The reservation.


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.


get/inventory/reservations/{id}
Request samples 
Response samples 
application/json
{}
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.


SecurityOAuth2: OAuth 
Request 
path Parameters
id
required
string
The reservation identifier.


 
 Example:  rsv_tkoi5db4hryu5cei5vwoabr7we
Responses 
200
The reservation was committed (or is already committed).


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.


409
The reservation expired or was released. You must create a new reservation.


429
Rate limit exceeded.


post/inventory/reservations/{id}/commit
Request samples 
Response samples 
application/json
{}
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.


SecurityOAuth2: OAuth 
Request 
path Parameters
id
required
string
The reservation identifier.


 
 Example:  rsv_tkoi5db4hryu5cei5vwoabr7we
Responses 
200
The reservation was released (or is already released, or had already expired — in which case
state reads expired).


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.


409
The reservation was already committed and cannot be released; use an adjustment to return stock for a completed sale.


429
Rate limit exceeded.


post/inventory/reservations/{id}/release
Request samples 
Response samples 
application/json
{}