Square · Schema

Square Catalog Item

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.

RestaurantBookingsCatalogCheckoutCustomersDisputesEcommerceFinancial TechnologyGift CardsInventoryInvoicingLaborLocationsLoyaltyMerchantsOrdersPaymentsPoint of SaleRefundsRetailSubscriptionsTeamTerminalWebhooks

Properties

Name	Type	Description
name	string	The item's name. This is a searchable attribute for use in applicable query filters.
description	string	The item's description as plain text.
description_html	string	The item's description as expressed in valid HTML elements.
abbreviation	string	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.
label_color	string	The color of the item's display label in the Square Point of Sale app. This must be a valid hex color code.
is_taxable	boolean	Indicates whether the item is taxable (true) or non-taxable (false). Default is true.
category_id	string	The ID of the item's category, if any. Deprecated: use categories instead.
categories	array	The list of categories that this item belongs to.
tax_ids	array	A set of IDs indicating the taxes enabled for this item.
modifier_list_info	array	A set of CatalogItemModifierListInfo objects representing the modifier lists that apply to this item.
variations	array	A list of CatalogItemVariation objects for this item. An item must have at least one variation.
product_type	string	The product type of the item. Once set, the product_type value cannot be modified.
skip_modifier_screen	boolean	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.
item_options	array	List of item options IDs for this item. Used to manage and group item variations in a specified order. Maximum: 6 item options.
image_ids	array	The IDs of images associated with this CatalogItem instance.
sort_name	string	A name to sort the item by. If unspecified, the regular name field is used for sorting.
reporting_category	object	The reporting category associated with this item.
channels	array	The channels where this item is available.
is_archived	boolean	Whether this item is archived (soft-deleted).

View JSON Schema on GitHub

JSON Schema

{
  "$id": "https://github.com/api-evangelist/square/blob/main/json-schema/catalog-item.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "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": {
      "type": "string",
      "description": "The item's name. This is a searchable attribute for use in applicable query filters.",
      "maxLength": 512
    },
    "description": {
      "type": "string",
      "description": "The item's description as plain text.",
      "maxLength": 4096
    },
    "description_html": {
      "type": "string",
      "description": "The item's description as expressed in valid HTML elements.",
      "maxLength": 65535
    },
    "abbreviation": {
      "type": "string",
      "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
    },
    "label_color": {
      "type": "string",
      "description": "The color of the item's display label in the Square Point of Sale app. This must be a valid hex color code."
    },
    "is_taxable": {
      "type": "boolean",
      "description": "Indicates whether the item is taxable (true) or non-taxable (false). Default is true."
    },
    "category_id": {
      "type": "string",
      "description": "The ID of the item's category, if any. Deprecated: use categories instead."
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the category."
          },
          "ordinal": {
            "type": "integer",
            "format": "int64",
            "description": "The order of the category within the item."
          }
        }
      },
      "description": "The list of categories that this item belongs to."
    },
    "tax_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "A set of IDs indicating the taxes enabled for this item."
    },
    "modifier_list_info": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "modifier_list_id": {
            "type": "string",
            "description": "The ID of the CatalogModifierList controlled by this CatalogModifierListInfo."
          },
          "min_selected_modifiers": {
            "type": "integer",
            "description": "The minimum number of modifiers that must be selected from the modifier list."
          },
          "max_selected_modifiers": {
            "type": "integer",
            "description": "The maximum number of modifiers that can be selected from the modifier list."
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether the modifier list is enabled for this item."
          }
        }
      },
      "description": "A set of CatalogItemModifierListInfo objects representing the modifier lists that apply to this item."
    },
    "variations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The unique ID for the catalog variation object."
          },
          "type": {
            "type": "string",
            "description": "The type of this object, always ITEM_VARIATION.",
            "const": "ITEM_VARIATION"
          },
          "item_variation_data": {
            "type": "object",
            "properties": {
              "item_id": {
                "type": "string",
                "description": "The ID of the CatalogItem associated with this item variation."
              },
              "name": {
                "type": "string",
                "description": "The item variation's name."
              },
              "sku": {
                "type": "string",
                "description": "The item variation's SKU, if any."
              },
              "upc": {
                "type": "string",
                "description": "The universal product code (UPC) of the item variation, if any."
              },
              "pricing_type": {
                "type": "string",
                "description": "Indicates whether the item variation's price is fixed or determined at the time of sale.",
                "enum": ["FIXED_PRICING", "VARIABLE_PRICING"]
              },
              "price_money": {
                "$ref": "money.json",
                "description": "The item variation's price, if fixed pricing is used."
              },
              "track_inventory": {
                "type": "boolean",
                "description": "If true, inventory tracking is active for the variation."
              },
              "sellable": {
                "type": "boolean",
                "description": "Whether this variation can be sold."
              },
              "stockable": {
                "type": "boolean",
                "description": "Whether stock of this variation can be counted."
              }
            }
          }
        }
      },
      "description": "A list of CatalogItemVariation objects for this item. An item must have at least one variation."
    },
    "product_type": {
      "type": "string",
      "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"]
    },
    "skip_modifier_screen": {
      "type": "boolean",
      "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."
    },
    "item_options": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "item_option_id": {
            "type": "string",
            "description": "The unique id of the item option."
          }
        }
      },
      "description": "List of item options IDs for this item. Used to manage and group item variations in a specified order. Maximum: 6 item options."
    },
    "image_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The IDs of images associated with this CatalogItem instance."
    },
    "sort_name": {
      "type": "string",
      "description": "A name to sort the item by. If unspecified, the regular name field is used for sorting."
    },
    "reporting_category": {
      "type": "object",
      "description": "The reporting category associated with this item.",
      "properties": {
        "id": {
          "type": "string",
          "description": "The ID of the reporting category."
        },
        "ordinal": {
          "type": "integer",
          "format": "int64",
          "description": "The order of the reporting category."
        }
      }
    },
    "channels": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The channels where this item is available."
    },
    "is_archived": {
      "type": "boolean",
      "description": "Whether this item is archived (soft-deleted)."
    }
  }
}