VariantSearch resource (Data API 19.8)

Summary

Http Method Resource Description
POST /products/{id}/variant_search

Searches product variations for master product or variation group product.

The query attribute specifies a complex query that can be used to narrow down the search. This is the list of searchable attributes:

  • id - String
  • product_id - String
  • name - String
  • online - SiteSpecific Boolean
  • in_stock - Boolean
  • searchable - SiteSpecific Boolean
  • ats - Actual available quantity to sell - Double
  • variation_attribute.ATTRIBUTE_ID (Ex:variation_attribute.color) - String

Sortable Fields:

  • id - String
  • product_id - String
  • name - String
  • online - SiteSpecific Boolean
  • in_stock - Boolean
  • searchable - SiteSpecific Boolean
  • ats - Actual available quantity to sell - Double

Note: The calculated value of "online" and "searchable" is used in the search/sort.

A search/sort by the the site specific attributes require the Site ID query parameter to be set. They are "online", "in_stock", "searchable" and "ats".

We assume that every field that starts with variation_attribute. is searchable and dot is followed by ATTRIBUTE_ID".

The list of expansions to retrieve product information. The expand values available are:

  • _base - Basic product information is retrieved. This expand is included by default.
  • all - All product information including the following properties are retrieved:
    • image
    • price - site_id has to be provided to see this property
    • price_currency - site_id has to be provided to see this property
  • availability - Information related to the availability of the product variation. This expand is not included by default.
    • ats - site_id has to be provided to see this property
    • in_stock - site_id has to be provided to see this property
    • online - site_id has to be provided to see this property
    • searchable
  • variations - Information related to product variation is retrieved. This expand is included by default.
  • attributes - Information related to product variation attributes is retrieved. This expand is not included by default.

Search Variants

Searches product variations for master product or variation group product.

The query attribute specifies a complex query that can be used to narrow down the search. This is the list of searchable attributes:

Sortable Fields:

Note: The calculated value of "online" and "searchable" is used in the search/sort.

A search/sort by the the site specific attributes require the Site ID query parameter to be set. They are "online", "in_stock", "searchable" and "ats".

We assume that every field that starts with variation_attribute. is searchable and dot is followed by ATTRIBUTE_ID".

The list of expansions to retrieve product information. The expand values available are:

Url

POST https://hostname:port/dw/data/v19_8/products/{id}/variant_search?site_id={String}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

SearchRequest

Response Document

VariantSearchResult

Path Parameters

Parameter Type Description Constraints
id String The product id of master product or variation group product  

Query Parameters

Parameter Type Description Constraints
site_id String The id of the site to get site specific product attributes.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 MalformedSearchParameterException   Thrown if the query is ill-formed.
400 ProductNotMasterGroupException

productId (String)

Thrown if the id is not the product id of a Variation Master product or Variation Group product.
400 SiteIdMissingForSiteSpecificFilterException

filterId (String)

Thrown if the Site ID query parameter is missing in the search of Variants by a site-specific product attribute.
404 ProductNotFoundException

productId (String)

Thrown if the product is not found.

Sample

REQUEST:
POST /s/-/dw/data/v19_8/products/spring-dress/variant_search?site_id=APAC_site HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Accept: application/json
{
    "query" : {
        "text_query": {
            "fields": ["id"],
            "search_phrase": "dress"
        }
    },
    "select": "(**)",
    "expand": ["variations"]
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 367
Content-Type: application/json; charset=UTF-8

{
   "_v" : "19.8",
   "_type" : "variant_search_result",
   "count" : 2,
   "expand" : 
   [
      "variations"
   ],
   "hits" : 
   [
      
      {
         "_type" : "variant",
         "product_id" : "dress-spring-red",
         "link" : "https://ocapi-mon.demandware.net/s/-/dw/data/v19_8/products/dress-spring-red",
         "variation_values" : 
         {
            "color" : "red"
         }
      },
      
      {
         "_type" : "variant",
         "product_id" : "dress-spring-blue",
         "link" : "https://ocapi-mon.demandware.net/s/-/dw/data/v19_8/products/dress-spring-blue",
         "variation_values" : 
         {
            "color" : "blue"
         }
      }
   ],
    "query" : {
        "text_query": {
            "fields": ["id"],
            "search_phrase": "dress"
        }
    },
   "select" : "(**)",
   "start" : 0,
   "total" : 2
}

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.8",
  "fault":{
    "type":"ProductNotFoundException",
    "message":"No product with ID 'my-product' was found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.8",
  "fault":{
    "type":"ProductNotMasterGroupException",
    "message":"Product 'my-product' is neither a variation master product nor a variation group product."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.8",
  "fault":{
    "type":"SiteIdMissingForSiteSpecificFilterException",
    "message":"A site ID is required to search and or sort by site-specific filter: 'ats'."
  }
}