Search catalog objects
Searches for CatalogObject of any type by matching supported search attribute values, excluding custom attribute values on items or item variations, against one or more of the specified query filters.
This (SearchCatalogObjects
) endpoint differs from the SearchCatalogItems
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 have different call conventions, including the query filter formats.
Name | Description |
---|---|
cursor
|
The pagination cursor returned in the previous response. Leave unset for an initial request. See Pagination for more information. |
object_
|
The desired set of object types to appear in the search results. If this is unspecified, the operation returns objects of all the top level types at the version of the Square API used to make the request. Object types that are nested onto other object types are not included in the defaults. At the current API version the default object types are: ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS. |
include_
|
If |
include_
|
If If the Default value: |
begin_
|
Return objects modified after this timestamp, in RFC 3339
format, e.g., Examples for January 25th, 2020 6:25:34pm Pacific Standard Time: UTC: 2020-01-26T02:25:34Z Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00 |
query
|
A query to be used to filter or sort the results. If no query is specified, the entire catalog will be returned. |
limit
|
A limit on the number of results to be returned in a single page. The limit is advisory - the implementation may return more or fewer results. If the supplied limit is negative, zero, or is higher than the maximum limit of 1,000, it will be ignored. |
Response Fields
Name | Description |
---|---|
errors
|
Any errors that occurred during the request. |
cursor
|
The pagination cursor to be used in a subsequent request. If unset, this is the final response. See Pagination for more information. |
objects
|
The CatalogObjects returned. |
related_
|
A list of CatalogObjects referenced by the objects in the |
latest_
Beta
|
When the associated product catalog was last updated. Will
match the value for |
Examples
- cURL
- Ruby
- Python
- C#
- Java
- PHP
- Node.js
curl https://connect.squareup.com/v2/catalog/search \
-X POST \
-H 'Square-Version: 2023-03-15' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"object_types": [
"ITEM"
],
"query": {
"prefix_query": {
"attribute_name": "name",
"attribute_prefix": "tea"
}
},
"limit": 100
}'
{
"objects": [
{
"type": "ITEM",
"id": "X5DZ5NWWAQ44CKBLKIFQGOWK",
"updated_at": "2017-10-26T15:41:32.337Z",
"version": 1509032492337,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Tea - Black",
"description": "A delicious blend of black tea.",
"category_id": "E7CLE5RZZ744BHWVQQEAHI2C",
"product_type": "REGULAR",
"tax_ids": [
"ZXITPM6RWHZ7GZ7EIP3YKECM"
],
"variations": [
{
"type": "ITEM_VARIATION",
"id": "5GSZPX6EU7MM75S57OONG3V5",
"updated_at": "2017-10-26T15:27:31.626Z",
"version": 1509031651626,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "X5DZ5NWWAQ44CKBLKIFQGOWK",
"name": "Regular",
"ordinal": 1,
"price_money": {
"amount": 150,
"currency": "USD"
},
"pricing_type": "FIXED_PRICING"
}
},
{
"type": "ITEM_VARIATION",
"id": "XVLBN7DU6JTWHJTG5F265B43",
"updated_at": "2017-10-26T15:27:31.626Z",
"version": 1509031651626,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "X5DZ5NWWAQ44CKBLKIFQGOWK",
"name": "Large",
"ordinal": 2,
"price_money": {
"amount": 225,
"currency": "USD"
},
"pricing_type": "FIXED_PRICING"
}
}
],
"visibility": "PRIVATE"
}
},
{
"type": "ITEM",
"id": "NNNEM3LA656Q46NXLWCNI7S5",
"updated_at": "2017-10-26T15:41:23.232Z",
"version": 1509032483232,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Tea - Green",
"description": "Relaxing green herbal tea.",
"category_id": "E7CLE5RZZ744BHWVQQEAHI2C",
"product_type": "REGULAR",
"tax_ids": [
"ZXITPM6RWHZ7GZ7EIP3YKECM"
],
"variations": [
{
"type": "ITEM_VARIATION",
"id": "FHYBVIA6NVBCSOVETA62WEA4",
"updated_at": "2017-10-26T15:29:00.524Z",
"version": 1509031740524,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "NNNEM3LA656Q46NXLWCNI7S5",
"name": "Regular",
"ordinal": 1,
"price_money": {
"amount": 150,
"currency": "USD"
},
"pricing_type": "FIXED_PRICING"
}
}
],
"visibility": "PRIVATE"
}
}
]
}