Query service API specifications

The Query service uses a REST API for command and communications. There are two specifications you can use: the Version 2 API intended for use with the React storefronts; and a Version 1 spec designed for backward compatibility.

In this document

The Query service Swagger reference

A Swagger interface to the Query service endpoints is available in the Query REST API. You can use the Swagger as a quick reference to the API and its parameters. In this document the details and logic of the API are explored in a little more detail.

Version 2 storefront APIs

When you explore the Query REST API you will find that some of the classes are prefixed with "V2." These are API calls that are specific to the React storefronts. They do not apply to the Aurora-based stores. The classes that are not prefixed with "V2" are Version 1 calls.

The Version 2 APIs combine functionality from a number of separate Version 1 classes. The following table provides links to specifications and samples for each V2 class. The table gives each API name, which Version 1 endpoints it includes, and a list of parameters that can be used with it. Each parameter can support multiple values.

Type V1 API endpoint URL V2 API endpoint URL V2 API parameters Examples
Categories

/search/resources/store/{id}/categoryview/{categoryIdentifier}

/search/resources/store/{id}/categoryview/@top

/search/resources/store/{id}/categoryview/byId/{categoryId}

/search/resources/store/{id}/categoryview/byIdentifiers

/search/resources/store/{id}/categoryview/byIds

/search/resources/store/{id}/categoryview/byParentCategory/{parentCategoryId}

/search/resources​​​​​​​​​​​​​​​​​​​​​​​/api/v2/categories Required:
  • storeId - operating store of the operation
Optional:
  • id - internal catgroup id
  • identifier - category external identifier
  • catalogId - sales catalog for the operation
  • langId - language for the operation
  • contractId - entitled contract in session from the shopper
  • parentId​​ - parent category id
  • depthAndLimit - sets the maximum number of records to return at each layer. It uses a comma separated list of values. So depthAndLimit=-1,-1 returns all (-1) possible values in the first layer and 2nd layer of categories. For example, with 5 layers of subcategories (with all categories returned at each layer), use the following notation:

    depthAndLimit=-1,-1,-1,-1,-1
  • The field parameter can be used to define an explicit list of fields to be returned in the response, e.g. field=id,name,description,identifier,seo
Products

/search/resources/store/{id}/productview/{partNumber}

/search/resources/store/{id}/productview/byCategory/{categoryId}

/search/resources/store/{id}/productview/byId/{productId}

/search/resources/store/{id}/productview/byIds

/search/resources/store/{id}/productview/byPartNumber/{partNumber}

/search/resources/store/{id}/productview/byPartNumbers

/search/resources/store/{id}/productview/bySearchTerm

/search/resources​​​​​​​​​​​​​​​​​​​​​/api/v2/products Required:
  • storeId - operating store of the operation
Optional:
  • id - internal catentry id
  • catalogId - sales catalog for the operation
  • langId - language of the operation
  • categoryId - parent category ​​id
  • currency - currency for display price
  • associationType​ - type of merchandising association to be included in the search result
  • searchTerm - for text searching
  • contractId - entitled contract in session from the shopper
  • offset, limit - for requests that support paging: when categoryId, term are used; lookup by id or identifier does not require paging
SEO URL

/search/resources/store/{id}/sitecontent/categorySuggestions

/search/resources/store/{id}/sitecontent/keywordSuggestionsByTerm/{term}

/search/resources/api/v2/urls​​​ Required:
  • storeId - operating store of the operation
Optional:
  • identifier - seourl external identifier equivalent to seourl keyword. Use when keyword is known.
Note: This endpoint does not support faceting, sorting, or paging; this is simply a lookup by identifier service.

React API examples

Categories example 1
Request URL:
GET /api/v2/categories?storeId=1&identifier=Apparel or
GET /api/v2/categories?storeId=1&identifier=Women%20Shirts%20Blouses,Dresses,Apparel

    v1 equivalent:    
    /​​​search/resources/store/{id}/categoryview/{categoryIdentifier​}
    /​​​search/resources/store/{id}/categoryview/​byIdentifiers
Or,
GET /api/v2/categories?storeId=1&id=10002 or​
GET /api/v2/categories?storeId=1&id=10002,10001,1

    v1 equivalent:​  
    /​​​search/resources/store/{id}/categoryview/byId/{categoryId​}
​    /​​​search/resources/store/{id}/categoryview/​byId​s​
Request header:
accept: application/json
Response body:
{
  "contents​": [
    {
      "id": "10001"​,
      "name": "Dresses",
      "identifier": "Dresses",
      "description": "Dresses",
      "thumbnail": "images/catalog/apparel/women/category/catr_wcl_dresses.png",
      "seo": {
         "href": "/shop/apparel/women/dresses"
      },
​      "links": {
         "self": {
           "href": "/api/v2/categories?storeId=1&id=10001"
          },
         "parent": {
           "href": "/api/v2/categories?storeId=1&id=3"
         }
      }
    },
    {
      "id": "10002",
      "name": "Blouses",
      "identifier": "Women Shirts Blouses",
      "description": "Blouses",
      "thumbnail": "images/catalog/apparel/women/category/catr_wcl_blouses.png",
      "seo": {
         "href": "/shop/apparel/women/blouses"
      },
      "links": {
         "self": {
           "href": "/api/v2/categories?storeId=1​&id=10002"
         },
         "parent": {
           "href": "/api/v2/categories?storeId=1&id=3"
         }
      }
    },
​    {
      "id": "1",
      "name": "Apparel",
      "identifier": "Apparel",
      "description": "The latest styles for the entire family.",
      "thumbnail": "images/catalog/apparel/women/category/catr_wcl_pants.png",
      "seo": {
         "href": "/shop/apparel"
      },
      "links": {
         "self": {
           "href": "/api/v2/categories?storeId=1&id=1​"
         },
         "children": [
              { "href": "/api/v2/categories?storeId=1&id=2" }, 
              { "href": "/api/v2/categories?storeId=1&id=3" },
              { "href": "/api/v2/categories?storeId=1&id=4" },
              { "href": "/api/v2/categories?storeId=1&id=5" }
         ]
      }
    }
​​  ]
}
Categories example 2
Request URL:
GET /api/v2/categories?storeId=1&depthAndLimit=-1,-1

    v1 equivalent:    
    /​​​search/resources/store/{id}/categoryview/@top
Request header:
accept: application/json
Response body:
{
  "contents": [
    {
      "id": "1",
      "name": "Apparel",
      "identifier": "Apparel",
      "description": "The latest styles for the entire family.",
      "thumbnail": "images/catalog/apparel/women/category/catr_wcl_pants.png",
      "seo": {
         "href": "/shop/apparel"
      },
      "children": [
          {
              "id": "2",
              "name": "Men",
              "identifier": "Men",
              "description": "Men",
              "thumbnail": "images/catalog/apparel/men/category/catr_app_men.png",
              "seo": {
                 "href": "/shop/apparel/men"
              },
              "children": [
                 { "href": "/api/v2/categories?storeId=1&id=10013" }, 
                 { "href": "/api/v2/categories?storeId=1&id=10012" },
                 { "href": "/api/v2/categories?storeId=1&id=10011" },
                 { "href": "/api/v2/categories?storeId=1&id=10010" },
                 { "href": "/api/v2/categories​?storeId=1​&id=10014" }
              ]
          },
          {
              "id": "5",
              "name": "Girls",
              "identifier": "Girls",
              "description": "Girls",
              "thumbnail": "images/catalog/apparel/girls/category/catr_app_girls.png",
              "seo": {
                 "url": "/shop/apparel/girls"
              },
              "children": [
                 { "href": "/api/v2/categories?storeId=1&id=10015" }, 
                 { "href": "/api/v2/categories?storeId=1&id=10016" },
                 { "href": "/api/v2/categories?storeId=1&id=10017" },
                 { "href": "/api/v2/categories?storeId=1&id=10018" }
              ]
​          },
          {
              "id": "4",
              "name": "Boys",
              "identifier": "Boys",
              "description": "Boys",
              "thumbnail": "images/catalog/apparel/boys/category/catr_app_boys.png",
              "seo": {
                 "url": "/shop/apparel/boys"
              },
              "children": [
                 { "href": "/api/v2/categories?storeId=1&id=10019" },
                 { "href": "/api/v2/categories?storeId=1&id=10020" },
                 { "href": "/api/v2/categories?storeId=1&id=10021" }
              ]
​          },
          {
              "id": 3,
              "name": "Women",
              "identifier": "Women",
              "description": "Women",
              "thumbnail": "images/catalog/apparel/women/category/catr_app_women.png​",
              "seo": {
                 "url": "/shop/apparel/wo​men"
              },
              "children": [
                 { "href": "/api/v2/categories?storeId=1&id=10003" }, 
                 { "href": "/api/v2/categories?storeId=1&id=10007" },
                 { "href": "/api/v2/categories?storeId=1&id=10008" },
                 { "href": "/api/v2/categories?storeId=1&id=10002" },
                 { "href": "/api/v2/categories?storeId=1&id=10006" },
                 { "href": "/api/v2/categories​?storeId=1&id=10001" },
                 { "href": "/api/v2/categories?storeId=1&id=10004" },
                 { "href": "/api/v2/categories​?storeId=1&id=10005" }
              ]
​          }
       ]
    },
    {  ... rest of top categories ...  }
  ]
​}
Response header:
 content-type: application/json;charset=UTF-8 
 date: Sun, 02 Feb 2020 22:15:28 GMT 
 transfer-encoding: chunked
Products example 1
Request URL:
GET /api/v2/products?storeId=1&id=10046&associationType=accessories or
GET /api/v2/products?storeId=1&id=10046&id=10045&associationType=accessories

​​    v1 equivalent
    /​​​search/resources/store/{id}​/productview/byId/{productId​}​​
    /​​​search/resources/store/{id}/productview/​byId​s
Request header:
accept: application/json
Response body:
{
    "contents": [
        {
            "id": "11907",
            "description": "Relaxed fit traditional cut two button suit",
            "type": "product",
            "image": "images/catalog/apparel/men/mcl008_suits/646x1000/mcl008_0819.jpg",
            "buyable": true,
            "thumbnail": "images/catalog/apparel/men/mcl008_suits/200x310/mcl008_0819.jpg",
            "sku​": "MCL008_0819",
            "name": "Hermitage Black Relaxed Fit Traditional Two Button Suit",
            "manufacturer": "Hermitage Collection",
            "seo": {
               "href": "/...."
            },
            "links": {
              "self": {
                 "href": "/api/v2/products?storeId=1&id=11907"​
              },
              "parent": {
                 "href": "/api/v2/categories?storeId=1&id=10001"​
              }
            },
            "price": [
                {
                    "usage": "Display",
                    "currency": "USD",
                    "value": 980
                },
                {
                    "usage": "Offer",
                    "currency": "USD",
                    "value": 980
                }
            ],
            "items": [
                {
                    "id": "11908",
                    "description": "Relaxed fit traditional cut two button suit",
                    "type": "item",
                    "image": "images/catalog/apparel/men/mcl008_suits/646x1000/mcl008_0819.jpg",
                    "buyable": true,
                    "thumbnail": "images/catalog/apparel/men/mcl008_suits/200x310/mcl008_0819.jpg",
                    "sku": "MCL008_081901",
                    "name": "Hermitage Black Relaxed Fit Traditional Two Button Suit",
                    "manufacturer": "Hermitage Collection",
                    "price": [
                        {
                            "usage": "Display",
                            "currency": "USD",
                            "value": 980
                        },
                        {
                            "usage": "Offer",
                            "currency": "USD",
                            "value": 980
                        }
                    ],
                    "links": {
                      "self": {
                         "href": "/api/v2/products?storeId=1&id=11988"​
                      },
                      "parent": {
                         "href": "/api/v2/categories?storeId=1&id=10001"​
                      }
                    },
                    "attributes": [
                        {
                            "identifier": "MenSuitsColor",
                            "usage": "Defining",
                            "values": [
                                {
                                    "identifier": "Black",
                                    "unit": {
                                        "name": "one",
                                        "id": "C62"
                                    },
                                    "value": "Black",
                                    "id": "7000000000000000904"
                                }
                            ],
                            "name": "Color",
                            "id": "7000000000000000047"
                        },
                        {
                            "identifier": "MenSuitsSize",
                            "usage": "Defining",
                            "values": [
                                {
                                    "identifier": "40R",
                                    "unit": {
                                        "name": "one",
                                        "id": "C62"
                                    },
                                    "value": "40R",
                                    "id": "7000000000000000908"
                                }
                            ],
                            "name": "Size",
                            "id": "7000000000000000048"
                        }
                    ]
                },
                { ... rest of items ... }
            ],
            "attributes": [
                {
                    "identifier": "MenSuitsColor",
                    "usage": "Defining",
                    "values": [
                        {
                            "identifier": "Black",
                            "unit": {
                                "name": "one",
                                "id": "C62"
                            },
                            "value": "Black",
                            "id": "7000000000000000904"
                        }
                    ],
                    "name": "Color",
                    "comparable": true,
                    "id": "7000000000000000047"
                },
                {
                    "identifier": "MenSuitsSize",
                    "usage": "Defining",
                    "values": [
                        {
                            "identifier": "44L",
                            "unit": {
                                "name": "one",
                                "id": "C62"
                            },
                            "value": "44L",
                            "id": "7000000000000000912"
                        },
                        {
                            "identifier": "44R",
                            "unit": {
                                 "name": "one",
                                 "id": "C62"
                            },
                            "value": "44R",
                            "id": "7000000000000000911"
                        },
                        { ... rest of attribute values ... }
                    ],
                    "name": "Size",
                    "comparable": true,
                    "id": "7000000000000000048"
                }
            ],
            "associations": [
                {
                    "id": "11907",
                    "description": "Relaxed fit traditional cut two button suit",
                    "type": "product",
                    "image": "images/catalog/apparel/men/mcl008_suits/646x1000/mcl008_0819.jpg",
                    "buyable": true,
                    "thumbnail": "images/catalog/apparel/men/mcl008_suits/200x310/mcl008_0819.jpg",
                    "sku​": "MCL008_0819",
                    "name": "Hermitage Black Relaxed Fit Traditional Two Button Suit",
                    "manufacturer": "Hermitage Collection",
                    "seo": {
                       "href": "/...."
                    },
                    "links": {
                      "self": {
                         "href": "/api/v2/products?storeId=1&id=11907"​
                      },
                      "parent": {
                         "href": "/api/v2/categories?storeId=1&id=10001"​
                      }
                    },
                    "price": [
                        {
                            "usage": "Display",
                            "currency": "USD",
                            "value": 980
                        },
                        {
                            "usage": "Offer",
                            "currency": "USD",
                            "value": 980
                        }
                    ],
                }
        ​    ]
        },
        {
            "id": "11908",
            "description": "Relaxed fit traditional cut two button suit",
            "type": "item",
            "image": "images/catalog/apparel/men/mcl008_suits/646x1000/mcl008_0819.jpg",
            "buyable": true,
            "thumbnail": "images/catalog/apparel/men/mcl008_suits/200x310/mcl008_0819.jpg",
            "sku": "MCL008_081901",
            "name": "Hermitage Black Relaxed Fit Traditional Two Button Suit",
            "manufacturer": "Hermitage Collection",
            "seo": {
               "href": "/...."
            },
            "links": {
              "self": {
                 "href": "/api/v2/products?storeId=1&id=11908"​
              },
              "parent": {
                 "href": "/api/v2/categories?storeId=1&id=10001​"​
              }
            },
​            "price": [
                {
                    "usage": "Display",
                    "currency": "USD",
                    "value": 980
                },
                {
                    "usage": "Offer",
                    "currency": "USD",
                    "value": 980
                }
            ],
            "attributes": [
                {
                    "identifier": "MenSuitsColor",
                    "usage": "Defining",
                    "values": [
                        {
                            "identifier": "Black",
                            "unit": {
                                 "name": "one",
                                 "id": "C62"
                            },
                            "value": "Black",
                            "id": "7000000000000000904"
                        }
                    ],
                    "name": "Color",
                    "comparable": true,
                    "id": "7000000000000000047"
                },
                {
                    "identifier": "MenSuitsSize",
                    "usage": "Defining",
                    "values": [
                        {
                            "identifier": "40R",
                            "unit": {
                                 "name": "one",
                                 "id": "C62"
                            },
​                            "value": "40R",
                            "id": "7000000000000000908"
                        }
                    ],
                    "name": "Size",
                    "comparable": true,
                    "id": "7000000000000000048"
                }
            ]
        }
    ]
}
Products example 2
Request URL:
/api/v2/products?storeId=1&categoryId=10001​

​​    v1 equivalent
    /​​​search/resources/store/{id}​/productview/​byCategory​​​/{cate​goryId}
Request header:
accept: application/json
Response body:
{
    "total": 56,
    "offset": 12,
    "limit": 12,
    "next": "/api/v2/products?storeId=1&categoryId=10001&id=11909&limit=12&offset=24",
    "previous": "/api/v2/products?storeId=1&categoryId=10001&id=11909&limit=12&offset=0",
    "contents": [
        {
            "id": "11907",
            "description": "Relaxed fit traditional cut two button suit",
            "type": "product",
            "image": "images/catalog/apparel/men/mcl008_suits/646x1000/mcl008_0819.jpg",
            "buyable": true,
            "thumbnail": "images/catalog/apparel/men/mcl008_suits/200x310/mcl008_0819.jpg",
            "sku": "MCL008_0819",
            "name": "Hermitage Black Relaxed Fit Traditional Two Button Suit",
            "manufacturer": "Hermitage Collection",
            "seo": {
               "href": "/...."
            },
            "links": {
              "self": {
                 "href": "/api/v2/products?storeId=1&id=11907"​
              },
              "parent": {
                 "href": "/api/v2/categories?storeId=1&id=10001"​
              }
            },
            "price": [
                {
                    "usage": "Display",
                    "currency": "USD",
                    "value": 980
                },
                {
                    "usage": "Offer",
                    "currency": "USD",
                    "value": 980
                }
            ],
            "items": [ 
                { "href": "/api/v2/products?storeId=1&id=11988" }, 
                { "href": "/api/v2/products?storeId=1&id=11909" }
            ]
        },
        
        ..... other products in the search result set ....
        
        {
            "id": "11907",
            "description": "Relaxed fit traditional cut two button suit",
            "type": "product",
            "parent": "/api/v2/categories/10001?storeId=1",
​            "image": "images/catalog/apparel/men/mcl008_suits/646x1000/mcl008_0819.jpg",
            "buyable": true,
            "thumbnail": "images/catalog/apparel/men/mcl008_suits/200x310/mcl008_0819.jpg",
            "sku": "MCL008_0819",
            "name": "Hermitage Black Relaxed Fit Traditional Two Button Suit",
            "manufacturer": "Hermitage Collection",
            "seo": {
               "href": "/...."
            },
            "links": {
              "self": {
                 "href": "/api/v2/products?storeId=1&id=11908"​
              },
              "parent": {
                 "href": "/api/v2/categories?storeId=1&id=10001"​
              }
            },
            "price": [
                {
                    "usage": "Display",
                    "currency": "USD",
                    "value": 980
                },
                {
                    "usage": "Offer",
                    "currency": "USD",
                    "value": 980
                }
            ],
            "items": [
                { "href": "/api/v2/products?storeId=1&id=11988" }, 
                { "href": "/api/v2/products?storeId=1&id=11909" }
            ]
        }​
  ],
​  "facets": [
        {
            "value": "price_USD",
            "name": "price_USD",
            "entry": [
                {
                    "count": 0,
                    "label": "*-100.0",
                    "value": "price_USD%3A*-100.0"
                },
                {
                    "count": 0,
                    "label": "100.0-200.0",
                    "value": "price_USD%3A100.0-200.0"
                },
                { ... rest of facet entries ... }
            ]
        }
    ]
}
Response header:
 content-type: application/json;charset=UTF-8 
 date: Sun, 02 Feb 2020 22:15:28 GMT 
 transfer-encoding: chunked
SEO URL example 1: request by identifier for a category
Request URL:
GET /api/v2/urls?storeId=12101&identifier=Bath 

or

GET /api/v2/urls?storeId=12101&identifier=Bath,Accessories
Request header:
accept: application/json
Response body:
{
  "contents": [
    {
      "id": 18801,
      "identifier": "bath",
      "status": 1,
      "tokenName": "CategoryToken",
      "tokenValue": "11509",
      "tokenExternalValue": "Bath",
      "storeId": 12101,
      "redirectURL": ​"",
      "page": {
          "name": "CATEGORY_PAGE",
          "type": "CATEGORY_PAGE",
          "layout": "",
          "title": "Bath | Stockholm",
          "metaKeyword": "space, light, faucet, mirror, brush, bath, decor",
          "metaDescription": "Modernize your bath space with a variety of vanity fixtures and lighting options",
          "imageAlternateDescription": "Image for Bath from Stockholm"
      }   
    },

    {
      "id": 18804,
      "identifier": "accessories",
      "status": 1,
      "tokenName": "CategoryToken",
      "tokenValue": "11509",
      "tokenExternalValue": "Accessories",
 ​​     "storeId": 12101,
      "redirectURL": ​"",
      "page": {
          "name": "CATEGORY_PAGE",
          "type": "PRODUCT_LISTING_PAGE",
          "layout": "",
          "title": "Accessories | Stockholm",
          "metaKeyword": "makeup mirrors, style, space, bath",
          "metaDescription": "Accent your bath with stylish accessories and makeup mirrors",
          "imageAlternateDescription": "Image for Accessories from Stockholm​"
    }

   ]​
​}
SEO URL example 2: request by identifier for a product
Request URL:
GET /api/v2/urls?storeId=12101&identifier=makeup-mirror-br-acce-0001

or

​GET /api/v2/urls​?storeId=12101
Request header:
accept: application/json
Response body:
{
  "contents": [
    {
      "id": 18501,
      "identifier": "makeup-mirror-br-acce-0001",
      "status": 1,
      "tokenName": "ProductToken",
      "tokenValue": "15733",
      "tokenExternalValue": "BR-ACCE-0001​",
      "storeId": 12101,
      "redirectURL": ​"",
      "page": {
          "name": "PRODUCT_PAGE",
          "type": "PRODUCT_PAGE",
          "layout": "",
          "title": "Makeup Mirror | Stockholm",
          "metaKeyword": "Stockholm",
          "metaDescription": "A modern makeup mirror that sits elegantly on any bathroom counter.",
          "imageAlternateDescription": "Image for Makeup Mirror from Stockholm"
      }   
    }

   ]
​}
Response header:
 content-type: application/json;charset=UTF-8 
 date: Sun, 02 Feb 2020 22:15:28 GMT 
 transfer-encoding: chunked