<- Catalog API

Catalog API

All versions ->

Search catalog itemsBeta

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

Try in API Explorer

Link to section

Request body

Example code

Link to section

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.

Link to section

category_ids

string [ ]

The category id query expression to return items containing the specified category IDs.

Link to section

stock_levels

The stock-level query expression to return item variations with the specified stock levels.

Link to section

enabled_location_ids

string [ ]

The enabled-location query expression to return items and item variations having specified enabled locations.

Link to section

cursor

string

The pagination token, returned in the previous response, used to fetch the next batch of pending results.

Link to section

limit

integer(32-bit)

The maximum number of results to return per page. The default value is 100.

Max

100

Link to section

sort_order

string

The order to sort the resutls. The default sort order is ascending (ASC).

Link to section

product_types

The product types query expression to return items or item variations having the specified product types.

Link to section

custom_attribute_filters

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.

Link to section

Response fields

Link to section

errors

Errors detected when the call to SearchCatalogItems endpoint fails.

Link to section

items

Returned items matching the specified query expressions.

Link to section

cursor

string

Pagination token used in the next request to return more of the search result.

Link to section

matched_variation_ids

string [ ]

Ids of returned item variations matching the specified query expression.

Link to section

Examples

All versions ->

POST /v2/catalog/search-catalog-items

curl https://connect.squareup.com/v2/catalog/search-catalog-items \
  -X POST \
  -H 'Square-Version: 2020-07-22' \
  -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
  }'

Response JSON

{
  "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"
  ]
}