CHcheckout
Inventory

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.

post/inventory/adjustments

Request

Headers

Cko-Idempotency-Keystring

An optional idempotency key for safely retrying payment requests

Request body

variant_idstring required

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

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

reasonstring required

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

Example request

{
  "variant_id": "var_123",
  "delta": -3,
  "reason": "damaged in warehouse"
}

Response

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

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.