Catalog Item Structure

{
  "$schema": "https://json-structure.org/meta/core/v0/#",
  "$id": "https://raw.githubusercontent.com/api-evangelist/square/refs/heads/main/json-structure/catalog-item-structure.json",
  "name": "Square Catalog Item",
  "description": "A CatalogObject instance of the ITEM type, also referred to as an item, in the catalog. Represents a product or service that a seller offers for sale.",
  "type": "object",
  "properties": {
    "name": {
      "description": "The item's name. This is a searchable attribute for use in applicable query filters.",
      "maxLength": 512,
      "type": "string"
    },
    "description": {
      "description": "The item's description as plain text.",
      "maxLength": 4096,
      "type": "string"
    },
    "description_html": {
      "description": "The item's description as expressed in valid HTML elements.",
      "maxLength": 65535,
      "type": "string"
    },
    "abbreviation": {
      "description": "The text of the item's display label in the Square Point of Sale app. Only up to the first five characters of the string are used.",
      "maxLength": 24,
      "type": "string"
    },
    "label_color": {
      "description": "The color of the item's display label in the Square Point of Sale app. This must be a valid hex color code.",
      "type": "string"
    },
    "is_taxable": {
      "description": "Indicates whether the item is taxable (true) or non-taxable (false). Default is true.",
      "type": "boolean"
    },
    "category_id": {
      "description": "The ID of the item's category, if any. Deprecated: use categories instead.",
      "type": "string"
    },
    "categories": {
      "items": {
        "properties": {
          "id": {
            "description": "The ID of the category.",
            "type": "string"
          },
          "ordinal": {
            "description": "The order of the category within the item.",
            "type": "int64"
          }
        },
        "type": "object"
      },
      "description": "The list of categories that this item belongs to.",
      "type": "array"
    },
    "tax_ids": {
      "items": {
        "type": "string"
      },
      "description": "A set of IDs indicating the taxes enabled for this item.",
      "type": "array"
    },
    "modifier_list_info": {
      "items": {
        "properties": {
          "modifier_list_id": {
            "description": "The ID of the CatalogModifierList controlled by this CatalogModifierListInfo.",
            "type": "string"
          },
          "min_selected_modifiers": {
            "description": "The minimum number of modifiers that must be selected from the modifier list.",
            "type": "int32"
          },
          "max_selected_modifiers": {
            "description": "The maximum number of modifiers that can be selected from the modifier list.",
            "type": "int32"
          },
          "enabled": {
            "description": "Whether the modifier list is enabled for this item.",
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "description": "A set of CatalogItemModifierListInfo objects representing the modifier lists that apply to this item.",
      "type": "array"
    },
    "variations": {
      "items": {
        "properties": {
          "id": {
            "description": "The unique ID for the catalog variation object.",
            "type": "string"
          },
          "type": {
            "description": "The type of this object, always ITEM_VARIATION.",
            "const": "ITEM_VARIATION",
            "type": "string"
          },
          "item_variation_data": {
            "properties": {
              "item_id": {
                "description": "The ID of the CatalogItem associated with this item variation.",
                "type": "string"
              },
              "name": {
                "description": "The item variation's name.",
                "type": "string"
              },
              "sku": {
                "description": "The item variation's SKU, if any.",
                "type": "string"
              },
              "upc": {
                "description": "The universal product code (UPC) of the item variation, if any.",
                "type": "string"
              },
              "pricing_type": {
                "description": "Indicates whether the item variation's price is fixed or determined at the time of sale.",
                "enum": [
                  "FIXED_PRICING",
                  "VARIABLE_PRICING"
                ],
                "type": "string"
              },
              "price_money": {
                "$ref": "money.json",
                "description": "The item variation's price, if fixed pricing is used."
              },
              "track_inventory": {
                "description": "If true, inventory tracking is active for the variation.",
                "type": "boolean"
              },
              "sellable": {
                "description": "Whether this variation can be sold.",
                "type": "boolean"
              },
              "stockable": {
                "description": "Whether stock of this variation can be counted.",
                "type": "boolean"
              }
            },
            "type": "object"
          }
        },
        "type": "object"
      },
      "description": "A list of CatalogItemVariation objects for this item. An item must have at least one variation.",
      "type": "array"
    },
    "product_type": {
      "description": "The product type of the item. Once set, the product_type value cannot be modified.",
      "enum": [
        "REGULAR",
        "GIFT_CARD",
        "APPOINTMENTS_SERVICE",
        "FOOD_AND_BEV",
        "LEGACY_SQUARE_ONLINE_SERVICE",
        "LEGACY_SQUARE_ONLINE_MEMBERSHIP"
      ],
      "type": "string"
    },
    "skip_modifier_screen": {
      "description": "If false, the Square Point of Sale app will present the CatalogItem's details screen immediately, allowing the merchant to choose CatalogModifiers before adding the item to the cart.",
      "type": "boolean"
    },
    "item_options": {
      "items": {
        "properties": {
          "item_option_id": {
            "description": "The unique id of the item option.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "description": "List of item options IDs for this item. Used to manage and group item variations in a specified order. Maximum: 6 item options.",
      "type": "array"
    },
    "image_ids": {
      "items": {
        "type": "string"
      },
      "description": "The IDs of images associated with this CatalogItem instance.",
      "type": "array"
    },
    "sort_name": {
      "description": "A name to sort the item by. If unspecified, the regular name field is used for sorting.",
      "type": "string"
    },
    "reporting_category": {
      "description": "The reporting category associated with this item.",
      "properties": {
        "id": {
          "description": "The ID of the reporting category.",
          "type": "string"
        },
        "ordinal": {
          "description": "The order of the reporting category.",
          "type": "int64"
        }
      },
      "type": "object"
    },
    "channels": {
      "items": {
        "type": "string"
      },
      "description": "The channels where this item is available.",
      "type": "array"
    },
    "is_archived": {
      "description": "Whether this item is archived (soft-deleted).",
      "type": "boolean"
    }
  }
}