You are viewing an old version of the API

All Versions

Search catalog items BETA

POST /v2/catalog/search-catalog-items

Searches for catalog items or item variations by matching supported search attribute values, including custom attribute values, against one or more of the specified query expressions.

This (SearchCatalogItems) endpoint differs from the SearchCatalogObjects endpoint in the following aspects:

SearchCatalogItems can only search for items or item variations, whereas SearchCatalogObjects can search for any type of catalog objects.
SearchCatalogItems supports the custom attribute query filters to return items or item variations that contain custom attribute values, where SearchCatalogObjects does not.
SearchCatalogItems does not support the include_deleted_objects filter to search for deleted items or item variations, whereas SearchCatalogObjects does.
The both endpoints use different call conventions, including the query filter formats.

Permissions

ITEMS_READ

Guide

Call SearchCatalogItems Try in API Explorer

Request Body

Example code

Name	Description
`text_filter string`	The text filter expression to return items or item variations containing specified text in the `name`, `description`, or `abbreviation` attribute value of an item, or in the `name`, `sku`, or `upc` attribute value of an item variation.
`category_ids string [ ]`	The category id query expression to return items containing the specified category IDs.
`stock_levels string [ ]`	The stock-level query expression to return item variations with the specified stock levels.
`enabled_location_ids string [ ]`	The enabled-location query expression to return items and item variations having specified enabled locations.
`cursor string`	The pagination token, returned in the previous response, used to fetch the next batch of pending results.
`limit integer`	The maximum number of results to return per page. The default value is 100. Max 100
`sort_order string`	The order to sort the results by item names. The default sort order is ascending (`ASC`).
`product_types string [ ]`	The product types query expression to return items or item variations having the specified product types.
`custom_attribute_filters CustomAttributeFilter [ ]`	The customer-attribute filter to return items or item variations matching the specified custom attribute expressions. A maximum number of 10 custom attribute expressions are supported in a single call to the SearchCatalogItems endpoint.

Response Fields

Name	Description
`errors Error [ ]`	Any errors that occurred during the request.
`items CatalogObject [ ]`	Returned items matching the specified query expressions.
`cursor string`	Pagination token used in the next request to return more of the search result.
`matched_variation_ids string [ ]`	Ids of returned item variations matching the specified query expression.

Examples

POST /v2/catalog/search-catalog-items

curl https://connect.squareup.com/v2/catalog/search-catalog-items \
  -X POST \
  -H 'Square-Version: 2021-01-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "sort_order": "ASC",
    "product_types": [
      "REGULAR"
    ],
    "category_ids": [
      "WINE_CATEGORY_ID"
    ],
    "enabled_location_ids": [
      "ATL_LOCATION_ID"
    ],
    "text_filter": "red",
    "custom_attribute_filters": [
      {
        "custom_attribute_definition_id": "VEGAN_DEFINITION_ID",
        "bool_filter": true
      },
      {
        "custom_attribute_definition_id": "BRAND_DEFINITION_ID",
        "string_filter": "Dark Horse"
      },
      {
        "key": "VINTAGE",
        "number_filter": {
          "min": 2017,
          "max": 2018
        }
      },
      {
        "custom_attribute_definition_id": "VARIETAL_DEFINITION_ID",
        "selection_ids_filter": "MERLOT_SELECTION_ID"
      }
    ],
    "stock_levels": [
      "OUT",
      "LOW"
    ],
    "limit": 100
  }'

{
  "items": [
    {
      "type": "ITEM",
      "id": "GPOKJPTV2KDLVKCADJ7I77EZ",
      "updated_at": "2020-06-18T17:55:56.646Z",
      "version": 1592502956646,
      "is_deleted": false,
      "present_at_all_locations": true,
      "custom_attribute_values": {
        "VINTAGE": {
          "name": "Vintage",
          "custom_attribute_definition_id": "EI7IJQDUKYSHULREPIPH6HNU",
          "type": "NUMBER",
          "number_value": 2018,
          "key": "VINTAGE"
        },
        "VARIETAL": {
          "name": "Varietal",
          "custom_attribute_definition_id": "VARIETAL_DEFINITION_ID",
          "type": "SELECTION",
          "selection_uid_values": [
            "MERLOT_SELECTION_ID",
            null
          ],
          "key": "VARIETAL"
        },
        "BRAND": {
          "name": "Brand",
          "custom_attribute_definition_id": "BRAND_DEFINITION_ID",
          "type": "STRING",
          "string_value": "Dark Horse",
          "key": "BRAND"
        }
      },
      "item_data": {
        "name": "Dark Horse Merlot 2018",
        "product_type": "REGULAR",
        "description": "A nice red wine",
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "VBJNPHCOKDFECR6VU25WRJUD",
            "updated_at": "2020-06-18T17:55:56.646Z",
            "version": 1592502956646,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "GPOKJPTV2KDLVKCADJ7I77EZ",
              "name": "750 mL",
              "ordinal": 0,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 1000,
                "currency": "USD"
              }
            }
          }
        ]
      }
    }
  ],
  "matched_variation_ids": [
    "VBJNPHCOKDFECR6VU25WRJUD"
  ]
}

Catalog API You are viewing an old version of the API 2021-01-21 Version 2021-01-21 All Versions Catalog API Search catalog items BETA

Request Body

Response Fields

Examples

Share Feedback

You are viewing an old version of the API

All Versions

Search catalog items BETA