SearchCatalogItemsRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/square/main/json-schema/square-search-catalog-items-request-schema.json",
  "title": "SearchCatalogItemsRequest",
  "description": "Defines the request body for the [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems) endpoint.",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/square-catalog-api-openapi.yml#/components/schemas/SearchCatalogItemsRequest",
  "type": "object",
  "x-release-status": "PUBLIC",
  "properties": {
    "text_filter": {
      "type": "string",
      "description": "The text filter expression to return items or item variations containing specified text in\nthe `name`, `description`, or `abbreviation` attribute value of an item, or in\nthe `name`, `sku`, or `upc` attribute value of an item variation."
    },
    "category_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The category id query expression to return items containing the specified category IDs."
    },
    "stock_levels": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SearchCatalogItemsRequestStockLevel"
      },
      "description": "The stock-level query expression to return item variations with the specified stock levels.\nSee [SearchCatalogItemsRequestStockLevel](#type-searchcatalogitemsrequeststocklevel) for possible values"
    },
    "enabled_location_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The enabled-location query expression to return items and item variations having specified enabled locations."
    },
    "cursor": {
      "type": "string",
      "description": "The pagination token, returned in the previous response, used to fetch the next batch of pending results."
    },
    "limit": {
      "type": "integer",
      "description": "The maximum number of results to return per page. The default value is 100.",
      "maximum": 100
    },
    "sort_order": {
      "$ref": "#/$defs/SortOrder",
      "description": "The order to sort the results by item names. The default sort order is ascending (`ASC`).\nSee [SortOrder](#type-sortorder) for possible values"
    },
    "product_types": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/CatalogItemProductType"
      },
      "description": "The product types query expression to return items or item variations having the specified product types."
    },
    "custom_attribute_filters": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/CustomAttributeFilter"
      },
      "description": "The customer-attribute filter to return items or item variations matching the specified\ncustom attribute expressions. A maximum number of 10 custom attribute expressions are supported in\na single call to the [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems) endpoint."
    },
    "archived_state": {
      "$ref": "#/$defs/ArchivedState",
      "description": "The query filter to return not archived (`ARCHIVED_STATE_NOT_ARCHIVED`), archived (`ARCHIVED_STATE_ARCHIVED`), or either type (`ARCHIVED_STATE_ALL`) of items."
    }
  },
  "$defs": {
    "ArchivedState": {
      "type": "string",
      "enum": [
        "ARCHIVED_STATE_NOT_ARCHIVED",
        "ARCHIVED_STATE_ARCHIVED",
        "ARCHIVED_STATE_ALL"
      ],
      "x-enum-elements": [
        {
          "name": "ARCHIVED_STATE_NOT_ARCHIVED",
          "description": "Requested items are not archived with the `is_archived` attribute set to `false`."
        },
        {
          "name": "ARCHIVED_STATE_ARCHIVED",
          "description": "Requested items are archived with the `is_archived` attribute set to `true`."
        },
        {
          "name": "ARCHIVED_STATE_ALL",
          "description": "Requested items can be archived or not archived."
        }
      ],
      "description": "Defines the values for the `archived_state` query expression \nused in [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems) \nto return the archived, not archived or either type of catalog items.",
      "x-release-status": "PUBLIC"
    },
    "CatalogItemProductType": {
      "type": "string",
      "enum": [
        "REGULAR",
        "GIFT_CARD",
        "APPOINTMENTS_SERVICE",
        "FOOD_AND_BEV",
        "EVENT",
        "DIGITAL",
        "DONATION",
        "LEGACY_SQUARE_ONLINE_SERVICE",
        "LEGACY_SQUARE_ONLINE_MEMBERSHIP"
      ],
      "x-enum-elements": [
        {
          "name": "REGULAR",
          "description": "An ordinary item."
        },
        {
          "name": "GIFT_CARD",
          "description": "A Square gift card."
        },
        {
          "name": "APPOINTMENTS_SERVICE",
          "description": "A service that can be booked using the Square Appointments app."
        },
        {
          "name": "FOOD_AND_BEV",
          "description": "A food or beverage item that can be sold by restaurants and other food venues."
        },
        {
          "name": "EVENT",
          "description": "An event which tickets can be sold for, including location, address, and times."
        },
        {
          "name": "DIGITAL",
          "description": "A digital item like an ebook or song."
        },
        {
          "name": "DONATION",
          "description": "A donation which site visitors can send for any cause."
        },
        {
          "name": "LEGACY_SQUARE_ONLINE_SERVICE",
          "description": "A legacy Square Online service that is manually fulfilled. This corresponds to the `Other` item type displayed in the Square Seller Dashboard and Square POS apps."
        },
        {
          "name": "LEGACY_SQUARE_ONLINE_MEMBERSHIP",
          "description": "A legacy Square Online membership that is manually fulfilled. This corresponds to the `Membership` item type displayed in the Square Seller Dashboard and Square POS apps."
        }
      ],
      "description": "The type of a CatalogItem. Connect V2 only allows the creation of `REGULAR` or `APPOINTMENTS_SERVICE` items.",
      "x-release-status": "PUBLIC"
    },
    "CustomAttributeFilter": {
      "type": "object",
      "description": "Supported custom attribute query expressions for calling the\n[SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems)\nendpoint to search for items or item variations.",
      "x-release-status": "PUBLIC",
      "properties": {
        "custom_attribute_definition_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "A query expression to filter items or item variations by matching their custom attributes'\n`custom_attribute_definition_id` property value against the the specified id.\nExactly one of `custom_attribute_definition_id` or `key` must be specified."
        },
        "key": {
          "type": [
            "string",
            "null"
          ],
          "description": "A query expression to filter items or item variations by matching their custom attributes'\n`key` property value against the specified key.\nExactly one of `custom_attribute_definition_id` or `key` must be specified."
        },
        "string_filter": {
          "type": [
            "string",
            "null"
          ],
          "description": "A query expression to filter items or item variations by matching their custom attributes'\n`string_value`  property value against the specified text.\nExactly one of `string_filter`, `number_filter`, `selection_uids_filter`, or `bool_filter` must be specified."
        },
        "number_filter": {
          "$ref": "#/$defs/Range",
          "description": "A query expression to filter items or item variations with their custom attributes\ncontaining a number value within the specified range.\nExactly one of `string_filter`, `number_filter`, `selection_uids_filter`, or `bool_filter` must be specified."
        },
        "selection_uids_filter": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          },
          "description": "A query expression to filter items or item variations by matching  their custom attributes'\n`selection_uid_values` values against the specified selection uids.\nExactly one of `string_filter`, `number_filter`, `selection_uids_filter`, or `bool_filter` must be specified."
        },
        "bool_filter": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "A query expression to filter items or item variations by matching their custom attributes'\n`boolean_value` property values against the specified Boolean expression.\nExactly one of `string_filter`, `number_filter`, `selection_uids_filter`, or `bool_filter` must be specified."
        }
      }
    },
    "Range": {
      "type": "object",
      "description": "The range of a number value between the specified lower and upper bounds.",
      "x-release-status": "PUBLIC",
      "properties": {
        "min": {
          "type": [
            "string",
            "null"
          ],
          "description": "The lower bound of the number range. At least one of `min` or `max` must be specified.\nIf unspecified, the results will have no minimum value."
        },
        "max": {
          "type": [
            "string",
            "null"
          ],
          "description": "The upper bound of the number range. At least one of `min` or `max` must be specified.\nIf unspecified, the results will have no maximum value."
        }
      }
    },
    "SearchCatalogItemsRequestStockLevel": {
      "type": "string",
      "enum": [
        "OUT",
        "LOW"
      ],
      "x-enum-elements": [
        {
          "name": "OUT",
          "description": "The item inventory is empty."
        },
        {
          "name": "LOW",
          "description": "The item inventory is low."
        }
      ],
      "description": "Defines supported stock levels of the item inventory.",
      "x-release-status": "PUBLIC"
    },
    "SortOrder": {
      "type": "string",
      "enum": [
        "DESC",
        "ASC"
      ],
      "x-enum-elements": [
        {
          "name": "DESC",
          "description": "The results are returned in descending (e.g., newest-first or Z-A) order."
        },
        {
          "name": "ASC",
          "description": "The results are returned in ascending (e.g., oldest-first or A-Z) order."
        }
      ],
      "description": "The order (e.g., chronological or alphabetical) in which results from a request are returned.",
      "x-release-status": "PUBLIC"
    }
  }
}