Pricing Templates
Log in Sign up
Integrations / Square Connect / ...

POST /v2/catalog/search

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 expressions.

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

Servers

Request headers

Name Type Required Description
Content-Type String Yes The media type of the request body.

Default value: "application/json"

Request body fields

Name Type Required Description
begin_time String No

Return objects modified after this timestamp, in RFC 3339 format, e.g., 2016-09-04T23:59:33.123Z. The timestamp is exclusive - objects with a timestamp equal to begin_time will not be included in the response.
query Object No

A query composed of one or more different types of filters to narrow the scope of targeted objects when calling the SearchCatalogObjects endpoint.

Although a query can have multiple filters, only certain query types can be combined per call to SearchCatalogObjects. Any combination of the following types may be used together:

  • exact_query
  • prefix_query
  • range_query
  • sorted_attribute_query
  • text_query All other query types cannot be combined with any others.

When a query filter is based on an attribute, the attribute must be searchable. Searchable attributes are listed as follows, along their parent types that can be searched for with applicable query filters.

  • Searchable attribute and objects queryable by searchable attributes **
  • name: CatalogItem, CatalogItemVariation, CatalogCategory, CatalogTax, CatalogDiscount, CatalogModifier, 'CatalogModifierList,CatalogItemOption,CatalogItemOptionValue`
  • description: CatalogItem, CatalogItemOptionValue
  • abbreviation: CatalogItem
  • upc: CatalogItemVariation
  • sku: CatalogItemVariation
  • caption: CatalogImage
  • display_name: CatalogItemOption

For example, to search for CatalogItem objects by searchable attributes, you can use the "name", "description", or "abbreviation" attribute in an applicable query filter.
query.items_for_modifier_list_query Object No

The query filter to return the items containing the specified modifier list IDs.
query.items_for_modifier_list_query.modifier_list_ids[] Array Yes

A set of CatalogModifierList IDs to be used to find associated CatalogItems.
query.prefix_query Object No

The query filter to return the search result whose named attribute values are prefixed by the specified attribute value.
query.prefix_query.attribute_name String Yes

The name of the attribute to be searched.
query.prefix_query.attribute_prefix String Yes

The desired prefix of the search attribute value.
query.set_query Object No

The query filter to return the search result(s) by exact match of the specified attribute_name and any of the attribute_values.
query.set_query.attribute_name String Yes

The name of the attribute to be searched. Matching of the attribute name is exact.
query.set_query.attribute_values[] Array Yes

The desired values of the search attribute. Matching of the attribute values is exact and case insensitive. A maximum of 250 values may be searched in a request.
query.exact_query Object No

The query filter to return the search result by exact match of the specified attribute name and value.
query.exact_query.attribute_value String Yes

The desired value of the search attribute. Matching of the attribute value is case insensitive and can be partial. For example, if a specified value of "sma", objects with the named attribute value of "Small", "small" are both matched.
query.exact_query.attribute_name String Yes

The name of the attribute to be searched. Matching of the attribute name is exact.
query.sorted_attribute_query Object No

The query expression to specify the key to sort search results.
query.sorted_attribute_query.initial_attribute_value String No

The first attribute value to be returned by the query. Ascending sorts will return only objects with this value or greater, while descending sorts will return only objects with this value or less. If unset, start at the beginning (for ascending sorts) or end (for descending sorts).
query.sorted_attribute_query.sort_order String No

The desired sort order, "ASC" (ascending) or "DESC" (descending).
query.sorted_attribute_query.attribute_name String Yes

The attribute whose value is used as the sort key.
query.range_query Object No

The query filter to return the search result whose named attribute values fall between the specified range.
query.range_query.attribute_name String Yes

The name of the attribute to be searched.
query.range_query.attribute_min_value Integer No

The desired minimum value for the search attribute (inclusive).
query.range_query.attribute_max_value Integer No

The desired maximum value for the search attribute (inclusive).
query.text_query Object No

The query filter to return the search result whose searchable attribute values contain all of the specified keywords or tokens, independent of the token order or case.
query.text_query.keywords[] Array Yes

A list of 1, 2, or 3 search keywords. Keywords with fewer than 3 characters are ignored.
query.item_variations_for_item_option_values_query Object No

The query filter to return the item variations containing the specified item option value IDs.
query.item_variations_for_item_option_values_query.item_option_value_ids[] Array No

A set of CatalogItemOptionValue IDs to be used to find associated CatalogItemVariations. All ItemVariations that contain all of the given Item Option Values (in any order) will be returned.
query.items_for_tax_query Object No

The query filter to return the items containing the specified tax IDs.
query.items_for_tax_query.tax_ids[] Array Yes

A set of CatalogTax IDs to be used to find associated CatalogItems.
query.items_for_item_options_query Object No

The query filter to return the items containing the specified item option IDs.
query.items_for_item_options_query.item_option_ids[] Array No

A set of CatalogItemOption IDs to be used to find associated CatalogItems. All Items that contain all of the given Item Options (in any order) will be returned.
limit Integer No

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.
include_deleted_objects Boolean No

If true, deleted objects will be included in the results. Deleted objects will have their is_deleted field set to true.
object_types[] Array No

The desired set of object types to appear in the search results.
include_related_objects Boolean No

If true, the response will include additional objects that are related to the requested object, as follows:

If a CatalogItem is returned in the object field of the response, its associated CatalogCategory, CatalogTax objects, CatalogImage objects and CatalogModifierList objects will be included in the related_objects field of the response.

If a CatalogItemVariation is returned in the object field of the response, its parent CatalogItem will be included in the related_objects field of the response.
cursor String No

The pagination cursor returned in the previous response. Leave unset for an initial request. See Pagination for more information.

How to start integrating

  1. Add HTTP Task to your workflow definition.
  2. Search for the API you want to integrate with and click on the name.
    • This loads the API reference documentation and prepares the Http request settings.
  3. Click Test request to test run your request to the API and see the API's response.
All third party trademarks (including logos and icons) are the property of their respective owners, which do not sponsor, authorize, or endorse this website.
Pricing Templates Integrations Blog Contact Us Help
© 2025 SimWorkflow
Terms of Service Privacy Policy