Using catalogProductInfo for retail products -

Using `catalogProductInfo` for retail products

The MenuItem object includes a catalogProductInfo value that provides retail catalog product information for menu items representing products available through e-commerce and retail sales channels. This value is null for menu items that do not represent retail catalog products (for example, a restaurant menu item).

Some retail catalog products exist as distinct variants of a base product. For example, a t-shirt in size "small" is a different product than the same t-shirt in size "large." The catalogProductInfo structure represents products with their variants and options.

The catalogProductInfo value includes objects that work together to represent retail catalog products:

Object structure overview

CatalogProductInfo: The container object with two values: product and productVariant.
- product - A CatalogProduct object containing retail-related information about a retail catalog product. This information applies to all variants of the product. It includes information about all the options available (for example, size or color).
- productVariant - A CatalogProductVariant object containing information about the options that apply to the specific retail catalog product represented by the menu item. For example, if options for a product are "size" and "color," a product variant might specify that the current product item is "small" and "blue."
CatalogProduct: Describes the base retail catalog product with its name, type, images, and all available options. The availableOptions array of CatalogProductOption objects defines what variations exist for this product.
CatalogProductOption: Represents a product attribute (such as size or color). Each option has an id, name, sortOrder, and a values array of CatalogProductOptionValue objects.
CatalogProductOptionValue: Represents a specific value within an option (such as "Small", "Medium", "Large" for "Size," or "Red", "White", "Blue" for "Color"). Each value has its own id, name, and sortOrder.
CatalogProductVariant: Describes the specific variant of the product represented by the menu item, with its own name and description. The selectedOptions array of CatalogProductVariantOption objects identifies which combination of option values defines this variant.
CatalogProductVariantOption: Links the variant to a specific option value. Each variant option's value property references a CatalogProductOptionValue from the base product's availableOptions.

The base retail catalog product (described by a CatalogProduct object) defines all possible options and values (for example, size: small/medium/large, color: red/white/blue), while the CatalogProductVariant object specifies which combination applies to this particular product (for example, color: red, size: small).

The type value of the CatalogProduct object indicates how the product is structured:

Product types

SINGLE: The product has exactly one variant and no configurable options. Use this type for simple retail items without variations.
OPTION: The product has multiple variants with at least one option. Options represent product attributes with their available values. Use this type for products where guests select from predefined variants.
UNSPECIFIED: The product type is not specified or unknown.

Retail catalog product variants reference option values. The same CatalogProductOptionValue objects appear in two places:

Understanding the relationship between variants and options

In the base product's availableOptions array, defining all possible values for each option.
Referenced by the selectedOptions array for a variant, identifying which specific values apply to the variant

This structure allows your integration to understand both the complete product catalog (all available options and values) and the specific variant represented by a menu item.

Example catalogProductInfo value

The following example shows a catalogProductInfo value in a MenuItem object for a t-shirt product with two options (color and size):

{
  "guid": "d707c11e-8e77-4e21-8f4a-4c8e8b8f8d1a",
  "name": "T-Shirt (Red, Small)",
  "price": 24.99,

  [content omitted]

  "catalogProductInfo": {
    "product": { 
      "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "name": "T-Shirt",
      "description": "Red/white/blue shirt",
      "type": "OPTION",
      "images": ["https://example.com/images/t-shirt.jpg"],
      "availableOptions": [ 
        {
          "id": "c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f",
          "name": "Color",
          "sortOrder": 0,
          "values": [ 
            {
              "id": "d0e1f2a3-4b5c-6d7e-8f9a-0b1c2d3e4f5a",
              "name": "Red",
              "sortOrder": 0
            },
            {
              "id": "e1f2a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
              "name": "White",
              "sortOrder": 1
            },
            {
              "id": "f2a3b4c5-6d7e-8f9a-0b1c-2d3e4f5a6b7c",
              "name": "Blue",
              "sortOrder": 2
            }
          ]
        },
        {
          "id": "e5f6a7b8-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
          "name": "Size",
          "sortOrder": 1,
          "values": [ 
            {
              "id": "f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f9a0b1c",
              "name": "Small",
              "sortOrder": 0
            },
            {
              "id": "a7b8c9d0-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
              "name": "Medium",
              "sortOrder": 1
            },
            {
              "id": "b8c9d0e1-2f3a-4b5c-6d7e-8f9a0b1c2d3e",
              "name": "Large",
              "sortOrder": 2
            }
          ]
        }
      ]
    },
    "productVariant": { 
      "id": "a3b4c5d6-7e8f-9a0b-1c2d-3e4f5a6b7c8d",
      "name": "T-Shirt (Red, Small)",
      "description": "Red/white/blue shirt",
      "selectedOptions": [ 
        {
          "id": "c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f",
          "name": "Color",
          "sortOrder": 0,
          "value": { 
            "id": "d0e1f2a3-4b5c-6d7e-8f9a-0b1c2d3e4f5a",
            "name": "Red",
            "sortOrder": 0
          }
        },
        {
          "id": "e5f6a7b8-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
          "name": "Size",
          "sortOrder": 1,
          "value": { 
            "id": "f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f9a0b1c",
            "name": "Small",
            "sortOrder": 0
          }
        }
      ]
    }
  }
}

	The `CatalogProduct` object defines the base "T-Shirt" product with `type` set to `OPTION`, indicating multiple variants exist.
	The `availableOptions` array defines all product options. This product has two options: `Color` and `Size`.
	The `Color` option's `values` array contains three `CatalogProductOptionValue` objects (red, white, blue). Each value has a unique ID and `sortOrder` starting at 0.
	The `Size` option's `values` array contains three `CatalogProductOptionValue` objects (small, medium, large) with `sortOrder` values starting at 0.
	The `CatalogProductVariant` object describes this specific variant.
	The `selectedOptions` array contains two `CatalogProductVariantOption` objects identifying which color and size apply to this variant.
	The `Color` variant option's `value` references the "Red" `CatalogProductOptionValue`. Note that the ID (`d0e1f2a3-4b5c-6d7e-8f9a-0b1c2d3e4f5a`) matches the ID from the product's `availableOptions`.
	The `Size` variant option's `value` references the "Small" `CatalogProductOptionValue`. The ID also matches the corresponding value in the product's `availableOptions`.