You are viewing an old version of the API
Search catalog objects

Required permissions ITEMS_READ

Request Body

Name Description
begin_time
string

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.

cursor
string

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

include_deleted_objects
boolean

If true, deleted objects will be included in the results. Deleted objects will have their is_deleted field set to true.

include_related_objects
boolean

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.

limit
integer

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.

object_types
string [ ]

The desired set of object types to appear in the search results. The legal values are taken from the CatalogObjectType enum: "ITEM", "ITEM_VARIATION", "CATEGORY", "DISCOUNT", "TAX", "MODIFIER", or "MODIFIER_LIST".

query
Catalog​Query

A query to be used to filter or sort the results. If no query is specified, the entire catalog will be returned.

Response Fields

Name Description
cursor
string

The pagination cursor to be used in a subsequent request. If unset, this is the final response. See Pagination for more information.

errors
Error [ ]

Information on any errors encountered.

latest_time
string

Beta

When the associated product catalog was last updated. Will match the value for end_time or cursor if either field is included in the SearchCatalog request.

objects
Catalog​Object [ ]

The CatalogObjects returned.

related_objects
Catalog​Object [ ]

A list of CatalogObjects referenced by the objects in the objects field.

Examples

You are viewing an old version of the API
POST /v2/catalog/search
cURL
  • cURL
  • Ruby
  • Python
curl https://connect.squareup.com/v2/catalog/search \
  -X POST \
  -H 'Square-Version: 2019-11-20' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -d '{
    "object_types": [
      "ITEM"
    ],
    "query": {
      "prefix_query": {
        "attribute_name": "name",
        "attribute_prefix": "tea"
      }
    },
    "limit": 100
  }'
Response JSON
{
  "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"
      }
    }
  ]
}

Share Feedback

Thanks for visiting the Square API documentation. What's on your mind?