Sign in

v1

latestOpenAPI 3.0.0Apache 2.02026-07-143281,4552.1 MB
Catalog

SearchCatalogItems

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

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.
post/v2/catalog/search-catalog-items

Request body

text_filterstring

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.

category_idsstring[]

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

stock_levelsSearchCatalogItemsRequestStockLevel[]

The stock-level query expression to return item variations with the specified stock levels. See SearchCatalogItemsRequestStockLevel for possible values

enabled_location_idsstring[]

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

cursorstring

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

limitinteger

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

sort_order'DESC' | 'ASC'

The order (e.g., chronological or alphabetical) in which results from a request are returned.

product_typesCatalogItemProductType[]

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

archived_state'ARCHIVED_STATE_NOT_ARCHIVED' | 'ARCHIVED_STATE_ARCHIVED' | 'ARCHIVED_STATE_ALL'

Defines the values for the archived_state query expression used in SearchCatalogItems to return the archived, not archived or either type of catalog items.

Example request

{
  "category_ids": [
    "WINE_CATEGORY_ID"
  ],
  "custom_attribute_filters": [
    {
      "bool_filter": true,
      "custom_attribute_definition_id": "VEGAN_DEFINITION_ID"
    },
    {
      "custom_attribute_definition_id": "BRAND_DEFINITION_ID",
      "string_filter": "Dark Horse"
    },
    {
      "key": "VINTAGE",
      "number_filter": {
        "max": 2018,
        "min": 2017
      }
    },
    {
      "custom_attribute_definition_id": "VARIETAL_DEFINITION_ID",
      "selection_ids_filter": "MERLOT_SELECTION_ID"
    }
  ],
  "enabled_location_ids": [
    "ATL_LOCATION_ID"
  ],
  "limit": 100,
  "product_types": [
    "REGULAR"
  ],
  "sort_order": "ASC",
  "stock_levels": [
    "OUT",
    "LOW"
  ],
  "text_filter": "red"
}

Response

Success

cursorstring

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

matched_variation_idsstring[]

Ids of returned item variations matching the specified query expression.

Example response

{
  "items": [
    {
      "custom_attribute_values": {
        "BRAND": {
          "custom_attribute_definition_id": "BRAND_DEFINITION_ID",
          "key": "BRAND",
          "name": "Brand",
          "string_value": "Dark Horse",
          "type": "STRING"
        },
        "VARIETAL": {
          "custom_attribute_definition_id": "VARIETAL_DEFINITION_ID",
          "key": "VARIETAL",
          "name": "Varietal",
          "selection_uid_values": [
            "MERLOT_SELECTION_ID",
            null
          ],
          "type": "SELECTION"
        },
        "VINTAGE": {
          "custom_attribute_definition_id": "EI7IJQDUKYSHULREPIPH6HNU",
          "key": "VINTAGE",
          "name": "Vintage",
          "number_value": 2018,
          "type": "NUMBER"
        }
      },
      "id": "GPOKJPTV2KDLVKCADJ7I77EZ",
      "is_deleted": false,
      "item_data": {
        "description": "A nice red wine",
        "is_archived": false,
        "name": "Dark Horse Merlot 2018",
        "product_type": "REGULAR",
        "variations": [
          {
            "id": "VBJNPHCOKDFECR6VU25WRJUD",
            "is_deleted": false,
            "item_variation_data": {
              "item_id": "GPOKJPTV2KDLVKCADJ7I77EZ",
              "name": "750 mL",
              "ordinal": 0,
              "price_money": {
                "amount": 1000,
                "currency": "USD"
              },
              "pricing_type": "FIXED_PRICING"
            },
            "present_at_all_locations": true,
            "type": "ITEM_VARIATION",
            "updated_at": "2020-06-18T17:55:56.646Z",
            "version": 1592502956646
          }
        ]
      },
      "present_at_all_locations": true,
      "type": "ITEM",
      "updated_at": "2020-06-18T17:55:56.646Z",
      "version": 1592502956646
    }
  ],
  "matched_variation_ids": [
    "VBJNPHCOKDFECR6VU25WRJUD"
  ]
}