Search for a Commerce entity using the GenericSearch API

Abstract

How to use the GenericSearch API sample command in Postman to search for a Commerce entity.

The Sitecore Experience Commerce SDK includes the GenericSearch API command, as part of the SearchApiSamples collection in Postman. You can use the sample request to search the Commerce Engine for indexed Commerce entities. The Search plugin defines the GenericSearch API endpoint as part of the generic search framework. You construct a GenericSearch query using a syntax that is search provider agnostic. You can search for catalog Items, promotions, orders, price cards, or customers.

The following instructions assume that you have installed the Postman application, imported the sample collections from the Sitecore Commerce Engine SDK, configured your environment, and retrieved a bearer token to access the Commerce Engine API, as described here.

To search for a Commerce entity, such as a catalog item, using the GenericSearch sample:

  1. In the Postman Collections pane, expand the SearchAPISamples collection.

  2. Open the API folder, and click the POST GenericSearch request ({{ServiceHost}}/{{ShopsApi}}/GenericSearch()).

  3. Click the Body tab, and update the query parameters to build your search query. The following example shows a query constructed to search the sample Habitat_Master catalog for a sellable item that matches the name "InstaClix Instant Film Camera":

    {
      "searchScope": "<hostname>-CatalogItemsScope",
      "searchQuery": null,
      "filterQuery": {
         "FilterNode": {
           "@odata.type": "#Sitecore.Commerce.Plugin.Search.EqualsFilterNode",
           "FieldName": {
             "@odata.type": "#Sitecore.Commerce.Plugin.Search.FieldNameFilterNode",
             "Name": "name"
           },
           "FieldValue": {
             "@odata.type": "#Sitecore.Commerce.Plugin.Search.FieldValueFilterNode",
             "Value": "Habitat_Master",
             "ValueType": "1"
           }
        }
     },
     "searchOptions": {
        "Skip": "0",
        "Top": "3",
        "ResultsOrderFields": [],
        "FieldsToRetrieve": []
      }
    }
  4. Click Send. The following shows an example of the returned search results:

    {
      "@odata.context": "https://cqa-dem-01-dk1:5000/api/$metadata#Collection(Sitecore.Commerce.Plugin.Search.SearchResult)", 
      "value": [
         {
           "Fields": [
              { 
                "Key": "sitecoreid",
                "Value": "46455327-796c-8125-b838-f6d7f678303d"
              },
              {
                "Key": "entityuniqueid",
                "Value": "6d737cc2-333b-ae32-73f0-cc3d67631409"
              },
              {
                "Key": "entityid",
                "Value": "Entity-SellableItem-7042066"
              },
              {
                "Key": "entityversion",
                "Value": "1"
              },
              { 
                "Key": "productid",  
                "Value": "7042066" 
              },  
              {
                "Key": "displayname",
                "Value": "InstaClix Instant Film Camera"
              },
              {
                "Key": "name",
                "Value": "InstaClix Instant Film Cmera"
              },
              {
                "Key": "datecreated",  
                "Value": "5/16/2019 2:09:35 PM +00:00"
              },
              {
                 "Key": "dateupdated",
                 "Value": "2/29/2020 10:57:28 AM +00:00"
              },
              {
                 "Key": "artifactstoreid",
                 "Value": "78a1ea61-1f37-42a7-ac89-9a3f46d60ca5"
              },
              {
                 "Key": "parentcataloglist",
                 "Value": "[\"59ddadc1-9b88-727e-9e14-3f6cf321ae0f\"]"
              },
              {
                 "Key": "variantid",
                 "Value": "57042066|57042067|57042068|
    57042069|57042070"
              },
              {
                 "Key": "variantdisplayname",
                 "Value": "InstaClix Instant Film Camera
    (Blue)|InstaClix Instant Film Camera (Red)| InstaClix Instant Film Camera (Green)|InstaClix Instant Film Camera (Teal)|InstaClix Instant Film Camera (Pink)"
               },
               { 
                 "Key": "inventorysetids",  
                 "Value": "Entity-InventorySet-Habitat_Inventory" 
               },
               {
                 "Key": "_version_",  
                 "Value": "1659868448064274437"
               }
            ]
         }
      ]
    }

Note

The generic search framework defines the search and filter nodes, criteria, and operators that can you use to build your query.