CHcheckout
Inventory

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.

put/inventory/{variant_id}

Request

Path parameters

variant_idstring required

The merchant-provided identifier for the variant.

Request body

on_handinteger required

The absolute physical stock to set for the variant.

safety_stockinteger

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

reasonstring

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

Example request

{
  "on_hand": 25,
  "safety_stock": 2,
  "reason": "stock take 2026-07"
}

Response

The variant already existed and its levels were updated.

variant_idstring

The merchant-provided identifier for the variant.

on_handinteger

Physical stock known to Checkout.com.

reservedinteger

The sum of all currently active holds against this variant.

safety_stockinteger

A buffer quantity withheld from sale.

availableinteger

The sellable quantity, clamped to zero: max(0, on_hand − reserved − safety_stock). This is the value an availability feed should publish.

state'in_stock' | 'limited' | 'out_of_stock'

A derived availability state for the variant.

source'managed' | 'sync'

How the levels are maintained. Always managed in the current version.

created_onstring date-time

The date and time the inventory item was created.

modified_onstring date-time

The date and time the inventory item was last modified.

Example response

{
  "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:00.0000000+00:00",
  "modified_on": "2026-07-13T14:02:11.0000000+00:00",
  "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:00.0000000+00:00",
    "sale_price_ends_at": "2026-08-31T23:59:59.0000000+00:00",
    "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:00.0000000+00:00",
    "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:00.0000000+00:00",
    "modified_on": "2026-08-13T14:02:11.0000000+00:00",
    "_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": [
          "GET"
        ],
        "types": [
          "application/json"
        ]
      },
      "delete": {
        "href": "https://api.checkout.com/inventory/var_123",
        "actions": [
          "GET"
        ],
        "types": [
          "application/json"
        ]
      }
    }
  },
  "_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": [
        "GET"
      ],
      "types": [
        "application/json"
      ]
    }
  }
}

Changes

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