--- title: "Adjust stock" method: POST path: "/inventory/adjustments" tags: ["Inventory"] --- # Adjust stock `POST /inventory/adjustments` ## Request - Base URL: `https://{prefix}.api.sandbox.checkout.com` - URL: `https://{prefix}.api.sandbox.checkout.com/inventory/adjustments` - Auth: OAuth 2 - Client credentials - Token URL: `string` scopes: `agentic:inventory` - TypeScript: (a function with typed inputs; its response is checked against the schema) 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` string ## Request body - InventoryAdjustmentRequest: Beta

The request body for applying a relative adjustment to a variant's on-hand stock. - `variant_id` string, required: The identifier of the variant to adjust. The variant must already exist. - `delta` 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` string, required: A required free-text reason recorded in the ledger (for example, damage or found stock). Must not contain personal data. ## Response `200` Idempotent replay of an earlier adjustment made with the same key. - InventoryLevels: Beta

The current stock levels and sellable availability for a single variant. - `variant_id` string: The merchant-provided identifier for the variant. - `on_hand` integer: Physical stock known to Checkout.com. - `reserved` integer: The sum of all currently active holds against this variant. - `safety_stock` integer: A buffer quantity withheld from sale. - `available` integer: 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_on` string, date-time: The date and time the inventory item was created. - `modified_on` string, date-time: The date and time the inventory item was last modified. - `product` InventoryProductKnowledge: Beta

The product knowledge for a single variant: the merchandising fields an AI agent needs to present, compare and recommend a product, independent of stock and pricing operations. Optional fields are omitted from the response entirely when not set. - `variant_id` string, required: The merchant-provided identifier for the variant. - `title` string, required: The product's display title. - `description` string, required: The product's display description. - `product_url` string, required: The canonical URL for the product page. - `image_url` string, required: The URL of the primary product image. - `additional_image_urls` string[]: 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: 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. - `price` InventoryMoney: A monetary amount in the currency's minor units. - `amount` integer, required: The amount in the minor currency unit. - `currency` string, required: The three-letter ISO 4217 currency code. - `sale_price` InventoryMoney: A monetary amount in the currency's minor units. - `amount` integer, required: The amount in the minor currency unit. - `currency` string, required: The three-letter ISO 4217 currency code. - `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` 'new' | 'used' | 'refurbished', required: The product's condition. Always present; defaults to `new` when not provided. - `material` string: The product's primary material. - `age_group` string: The target age group for the product. - `length` number: The product's length. Provided together with `width`, `height` and `dimension_unit`, or not at all. - `width` number: The product's width. Provided together with `length`, `height` and `dimension_unit`, or not at all. - `height` number: The product's height. Provided together with `length`, `width` and `dimension_unit`, or not at all. - `dimension_unit` string: The unit that `length`, `width` and `height` are expressed in. - `weight` number: The product's weight. Provided together with `weight_unit`, or not at all. - `weight_unit` string: The unit that `weight` is expressed in. - `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. - `created_on` string, date-time, required: The date and time the product knowledge was created. - `modified_on` string, date-time, required: The date and time the product knowledge was last modified. - `_links` object, required: Links to related operations on the variant's product knowledge. - `self` InventoryHalLink: A HAL link describing a related operation on the resource. - `href` string: Absolute URI of the linked resource. - `actions` string[]: The HTTP methods supported on the linked resource. - `types` string[]: The media types supported on the linked resource. - `set` InventoryHalLink: A HAL link describing a related operation on the resource. - `href` string: Absolute URI of the linked resource. - `actions` string[]: The HTTP methods supported on the linked resource. - `types` string[]: The media types supported on the linked resource. - `delete` InventoryHalLink: A HAL link describing a related operation on the resource. - `href` string: Absolute URI of the linked resource. - `actions` string[]: The HTTP methods supported on the linked resource. - `types` string[]: The media types supported on the linked resource. - `_links` object: Links to related operations on the variant. - `self` InventoryHalLink: A HAL link describing a related operation on the resource. - `href` string: Absolute URI of the linked resource. - `actions` string[]: The HTTP methods supported on the linked resource. - `types` string[]: The media types supported on the linked resource. - `set` InventoryHalLink: A HAL link describing a related operation on the resource. - `href` string: Absolute URI of the linked resource. - `actions` string[]: The HTTP methods supported on the linked resource. - `types` string[]: The media types supported on the linked resource. ## Other responses - `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. --- [API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)