---
title: "Set product knowledge"
method: PUT
path: "/inventory/{variant_id}/product"
tags: ["Inventory"]
---

# Set product knowledge

`PUT /inventory/{variant_id}/product`

## Request

- Base URL: `https://{prefix}.api.sandbox.checkout.com`
- URL: `https://{prefix}.api.sandbox.checkout.com/inventory/{variant_id}/product`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `string` scopes: `agentic:inventory`
- TypeScript: <https://skmtc.dev/checkout/apis/checkout-com-api-reference/docs/inventory/:variant_id/product/put.ts> (a function with typed inputs; its response is checked against the schema)

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

## Path parameters

- `variant_id` string, required

## Request body

- InventorySetProductRequest: <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> The request body for setting the product knowledge for a variant. The call is an upsert.
  - `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 <a href="https://www.checkout.com/docs/resources/calculating-the-amount" target="_blank">minor currency unit</a>.
    - `currency` string, required: The three-letter <a href="https://www.checkout.com/docs/resources/codes/currency-codes" target="_blank">ISO 4217 currency code</a>.
  - `sale_price` InventoryMoney: A monetary amount in the currency's minor units.
    - `amount` integer, required: The amount in the <a href="https://www.checkout.com/docs/resources/calculating-the-amount" target="_blank">minor currency unit</a>.
    - `currency` string, required: The three-letter <a href="https://www.checkout.com/docs/resources/codes/currency-codes" target="_blank">ISO 4217 currency code</a>.
  - `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': The product's condition, as an exact lowercase match of one of the enum values. Defaults to `new` when omitted.
  - `material` string: The product's primary material.
  - `age_group` string: The target age group for the product.
  - `length` number: The product's length. `length`, `width`, `height` and `dimension_unit` must be provided together, or not at all.
  - `width` number: The product's width. `length`, `width`, `height` and `dimension_unit` must be provided together, or not at all.
  - `height` number: The product's height. `length`, `width`, `height` and `dimension_unit` must be provided together, or not at all.
  - `dimension_unit` string: The unit that `length`, `width` and `height` are expressed in. Required when any of `length`, `width` or `height` is set.
  - `weight` number: The product's weight. Must be provided together with `weight_unit`, or not at all.
  - `weight_unit` string: The unit that `weight` is expressed in. Required when `weight` is set.
  - `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.

## Response `200`

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

- InventoryProductKnowledge: <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> 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 <a href="https://www.checkout.com/docs/resources/calculating-the-amount" target="_blank">minor currency unit</a>.
    - `currency` string, required: The three-letter <a href="https://www.checkout.com/docs/resources/codes/currency-codes" target="_blank">ISO 4217 currency code</a>.
  - `sale_price` InventoryMoney: A monetary amount in the currency's minor units.
    - `amount` integer, required: The amount in the <a href="https://www.checkout.com/docs/resources/calculating-the-amount" target="_blank">minor currency unit</a>.
    - `currency` string, required: The three-letter <a href="https://www.checkout.com/docs/resources/codes/currency-codes" target="_blank">ISO 4217 currency code</a>.
  - `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.

## Other responses

- `201`: The product knowledge was created for the variant.
- `401`: Missing or invalid token.
- `403`: The token does not carry the `agentic:inventory` scope.
- `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)