CHcheckout
Inventory

Set product knowledge

<span style="font-size: 12px; font-weight: 500; color: rgb(0, 0, 0); background-color: rgb(255, 176, 97); border-radius: 4px; padding: 2px 6px" >Beta</span><p></p> 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.

put/inventory/{variant_id}/product

Request

Path parameters

variant_idstring required

The merchant-provided identifier for the variant.

Request body

titlestring required

The product's display title.

descriptionstring required

The product's display description.

product_urlstring required

The canonical URL for the product page.

image_urlstring required

The URL of the primary product image.

additional_image_urlsstring[]

Additional product image URLs, beyond image_url.

video_urlstring

The URL of a product video.

model_3d_urlstring

The URL of a 3D model of the product.

skustring

The merchant's stock-keeping unit for the product.

gtinstring

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

mpnstring

The product's Manufacturer Part Number.

brandstring

The product's brand name.

categorystring

The merchant's category for the product.

sale_price_starts_atstring date-time

The date and time from which sale_price applies. Paired with sale_price.

sale_price_ends_atstring date-time

The date and time after which sale_price no longer applies. Paired with sale_price.

group_idstring

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_titlestring

A display title for the variant group.

colorstring

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

sizestring

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

size_systemstring

The sizing system that size is expressed in.

genderstring

The target gender for the product.

condition'new' | 'used' | 'refurbished'

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

materialstring

The product's primary material.

age_groupstring

The target age group for the product.

lengthnumber

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

widthnumber

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

heightnumber

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

dimension_unitstring

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

weightnumber

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

weight_unitstring

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

expiration_datestring date-time

The date and time after which the product should no longer be offered.

harmonized_system_codestring

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

country_of_originstring

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

seller_namestring

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

seller_urlstring

The URL of the seller of record.

seller_privacy_policystring

The URL of the seller's privacy policy.

seller_tosstring

The URL of the seller's terms of service.

Example request

{
  "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"
}

Response

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

variant_idstring required

The merchant-provided identifier for the variant.

titlestring required

The product's display title.

descriptionstring required

The product's display description.

product_urlstring required

The canonical URL for the product page.

image_urlstring required

The URL of the primary product image.

additional_image_urlsstring[]

Additional product image URLs, beyond image_url.

video_urlstring

The URL of a product video.

model_3d_urlstring

The URL of a 3D model of the product.

skustring

The merchant's stock-keeping unit for the product.

gtinstring

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

mpnstring

The product's Manufacturer Part Number.

brandstring

The product's brand name.

categorystring

The merchant's category for the product.

sale_price_starts_atstring date-time

The date and time from which sale_price applies. Paired with sale_price.

sale_price_ends_atstring date-time

The date and time after which sale_price no longer applies. Paired with sale_price.

group_idstring

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_titlestring

A display title for the variant group.

colorstring

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

sizestring

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

size_systemstring

The sizing system that size is expressed in.

genderstring

The target gender for the product.

condition'new' | 'used' | 'refurbished' required

The product's condition. Always present; defaults to new when not provided.

materialstring

The product's primary material.

age_groupstring

The target age group for the product.

lengthnumber

The product's length. Provided together with width, height and dimension_unit, or not at all.

widthnumber

The product's width. Provided together with length, height and dimension_unit, or not at all.

heightnumber

The product's height. Provided together with length, width and dimension_unit, or not at all.

dimension_unitstring

The unit that length, width and height are expressed in.

weightnumber

The product's weight. Provided together with weight_unit, or not at all.

weight_unitstring

The unit that weight is expressed in.

expiration_datestring date-time

The date and time after which the product should no longer be offered.

harmonized_system_codestring

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

country_of_originstring

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

seller_namestring

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

seller_urlstring

The URL of the seller of record.

seller_privacy_policystring

The URL of the seller's privacy policy.

seller_tosstring

The URL of the seller's terms of service.

created_onstring date-time required

The date and time the product knowledge was created.

modified_onstring date-time required

The date and time the product knowledge was last modified.

Example response

{
  "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"
      ]
    }
  }
}

Changes

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