Search catalog items BETA
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, whereasSearchCatalogObjects
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, whereSearchCatalogObjects
does not.SearchCatalogItems
does not support theinclude_deleted_objects
filter to search for deleted items or item variations, whereasSearchCatalogObjects
does.- The both endpoints use different call conventions, including the query filter formats.
Name | Description |
---|---|
text_
|
The text filter expression to return items or item variations containing specified text in
the |
category_
|
The category id query expression to return items containing the specified category IDs. |
stock_
|
The stock-level query expression to return item variations with the specified stock levels. |
enabled_
|
The enabled-location query expression to return items and item variations having specified enabled locations. |
cursor
|
The pagination token, returned in the previous response, used to fetch the next batch of pending results. |
limit
|
The maximum number of results to return per page. The default value is 100. |
sort_
|
The order to sort the results by item names. The default sort order is ascending ( |
product_
|
The product types query expression to return items or item variations having the specified product types. |
custom_
|
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
|
Any errors that occurred during the request. |
items
|
Returned items matching the specified query expressions. |
cursor
|
Pagination token used in the next request to return more of the search result. |
matched_
|
Ids of returned item variations matching the specified query expression. |
Examples
- cURL
- Ruby
- Python
- C#
- Java
- PHP
- Node.js
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"
]
}