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.

Submit a batch ingestion

​

Submits a batch of up to 500 items, covering stock, product knowledge, or both, for asynchronous processing, and returns 202 Accepted with an ingestion job to poll. Processing is non-atomic: Good items apply even if some are rejected, and the per-item outcome is available at /inventory/ingestions/{id}/results.

Ingestion sets the baseline stock and never overrides an active reservation, so it can never cause an oversell.

Include a Cko-Idempotency-Key header to make a retried submit safe: a repeat with the same key returns the original job instead of creating a duplicate batch.

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 body of a JSON batch submit. Processing is asynchronous and non-atomic: good items apply even if some are rejected.

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

    The list of items to apply. Up to 500 items per batch.

    Beta

    One item in a JSON batch. Provide:

    • stock to set stock
    • product to set product knowledge, or
    • both.

    At least one of the two must be present.

  • mode
    enum
    const:  
    upsert

    The update semantics for the batch. Only upsert is available in this version.

    values
    • upsert
Responses
  • application/json
  • 401

    Missing or invalid token.

  • 403

    The token does not carry the agentic:inventory scope.

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/inventory/ingestions
curl 'https://{prefix}.api.sandbox.checkout.com/inventory/ingestions' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "mode": "upsert",
  "items": [
    {
      "stock": {
        "on_hand": 25,
        "safety_stock": 2,
        "reason": "stock take 2026-07"
      }
    }
  ]
}'

{
  "id": "ing_01hzy8q2m4n6p8r0s2t4v6w8x0",
  "state": "accepted",
  "mode": "upsert",
  "counts": {
    "received": 500,
    "accepted": 498,
    "rejected": 2,
    "pending": 0
  },
  "failure_reason": {
    "code": "file_unreadable",
    "message": "The uploaded file could not be read as CSV."
  },
  "upload_url": "https://inventory-ingestions.s3.eu-west-1.amazonaws.com/ingestions/mer_1/ing_.../payload.csv?X-Amz-Signature=...",
  "created_on": "2026-09-24T15:04:05Z",
  "modified_on": "2026-09-24T15:04:11Z",
  "_links": {
    "self": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": [
        "GET"
      ],
      "types": [
        "application/json"
      ]
    },
    "results": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    },
    "start": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    }
  }
}

The batch was accepted for processing, or the original job on an idempotent replay.

Get an ingestion job

​

Returns an ingestion job and its current state and counts. Poll this until state is either:

  • completed
  • completed_with_errors, or
  • failed

Then read the per-item report at /inventory/ingestions/{id}/results.

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

Path Parameters
  • id
    Type: string
    required

    The ingestion 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/ingestions/{id}
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/inventory/ingestions/ing_01hzy8q2m4n6p8r0s2t4v6w8x0' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "id": "ing_01hzy8q2m4n6p8r0s2t4v6w8x0",
  "state": "accepted",
  "mode": "upsert",
  "counts": {
    "received": 500,
    "accepted": 498,
    "rejected": 2,
    "pending": 0
  },
  "failure_reason": {
    "code": "file_unreadable",
    "message": "The uploaded file could not be read as CSV."
  },
  "upload_url": "https://inventory-ingestions.s3.eu-west-1.amazonaws.com/ingestions/mer_1/ing_.../payload.csv?X-Amz-Signature=...",
  "created_on": "2026-09-24T15:04:05Z",
  "modified_on": "2026-09-24T15:04:11Z",
  "_links": {
    "self": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": [
        "GET"
      ],
      "types": [
        "application/json"
      ]
    },
    "results": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    },
    "start": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    }
  }
}

The ingestion job.

Get an ingestion job's results

​

Returns the per-item results report for a terminal ingestion job. By default only the rejected rows are listed, so you can fix and re-submit them; pass include=all to list every row. Returns 409 results_not_ready until the job is terminal.

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

Path Parameters
  • id
    Type: string
    required

    The ingestion identifier.

Query Parameters
  • include
    enum
    const:  
    all

    Set to all to include accepted items as well as rejected ones. Defaults to rejected only.

    values
    • all
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 get/inventory/ingestions/{id}/results
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/inventory/ingestions/ing_01hzy8q2m4n6p8r0s2t4v6w8x0/results' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "ingestion_id": "ing_01hzy8q2m4n6p8r0s2t4v6w8x0",
  "counts": {
    "received": 500,
    "accepted": 498,
    "rejected": 2,
    "pending": 0
  },
  "items": [
    {
      "index": 1,
      "variant_id": "var_123",
      "status": "rejected",
      "error_codes": [
        "on_hand_negative"
      ]
    }
  ]
}

The per-item results report.

Start processing an uploaded file

​

Begins processing a CSV file that was uploaded to the presigned upload_url. Validates and parses the file, then queues it, moving the job out of awaiting_upload. Poll the job for status and read the per-item report as for a JSON batch.

Requires the agentic:inventory scope.

Path Parameters
  • id
    Type: string
    required

    The ingestion identifier.

Responses
  • application/json
  • 401

    Missing or invalid token.

  • 403

    The token does not carry the agentic:inventory scope.

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

    Rate limit exceeded.

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

{
  "id": "ing_01hzy8q2m4n6p8r0s2t4v6w8x0",
  "state": "accepted",
  "mode": "upsert",
  "counts": {
    "received": 500,
    "accepted": 498,
    "rejected": 2,
    "pending": 0
  },
  "failure_reason": {
    "code": "file_unreadable",
    "message": "The uploaded file could not be read as CSV."
  },
  "upload_url": "https://inventory-ingestions.s3.eu-west-1.amazonaws.com/ingestions/mer_1/ing_.../payload.csv?X-Amz-Signature=...",
  "created_on": "2026-09-24T15:04:05Z",
  "modified_on": "2026-09-24T15:04:11Z",
  "_links": {
    "self": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": [
        "GET"
      ],
      "types": [
        "application/json"
      ]
    },
    "results": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    },
    "start": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    }
  }
}

The uploaded file was accepted and queued for processing.

Create a CSV upload slot

​

Creates an upload slot for a CSV ingestion by generating a short-lived, PUT-only presigned URL. Returns 202 Accepted with a job in the awaiting_upload state carrying an upload_url and a start link.

Upload the file directly to upload_url (it never transits the API), then call the start operation to begin processing.

Requires the agentic:inventory scope.

Body·
application/json

Beta

The body of a CSV upload-slot request. The response returns a presigned upload_url to PUT the file to and a start link to begin processing.

  • mode
    enum
    const:  
    upsert

    The update semantics for the upload. Only upsert is available in this version.

    values
    • upsert
  • format
    enum
    const:  
    csv

    The uploaded file format. Only csv is available in this version.

    values
    • csv
Responses
  • application/json
  • 401

    Missing or invalid token.

  • 403

    The token does not carry the agentic:inventory scope.

  • application/json
  • application/json
Request Example for post/inventory/ingestions/uploads
curl 'https://{prefix}.api.sandbox.checkout.com/inventory/ingestions/uploads' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "mode": "upsert",
  "format": "csv"
}'

{
  "id": "ing_01hzy8q2m4n6p8r0s2t4v6w8x0",
  "state": "accepted",
  "mode": "upsert",
  "counts": {
    "received": 500,
    "accepted": 498,
    "rejected": 2,
    "pending": 0
  },
  "failure_reason": {
    "code": "file_unreadable",
    "message": "The uploaded file could not be read as CSV."
  },
  "upload_url": "https://inventory-ingestions.s3.eu-west-1.amazonaws.com/ingestions/mer_1/ing_.../payload.csv?X-Amz-Signature=...",
  "created_on": "2026-09-24T15:04:05Z",
  "modified_on": "2026-09-24T15:04:11Z",
  "_links": {
    "self": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": [
        "GET"
      ],
      "types": [
        "application/json"
      ]
    },
    "results": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    },
    "start": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": "[Circular]",
      "types": "[Circular]"
    }
  }
}

The upload slot was created. Upload the file to upload_url, then call start.

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).