GET Provides keyword and refinement-based search for products, returning only product ID, link, and name. Results are limited to products that are online and part of the site catalog.
GET /organizations/{organizationId}/product-search
Operation ID: productSearch. Security: ShopperToken (sfcc.shopper-product-search, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-product-search, sfcc.shopper-standard).
Provide keyword and refinement search functionality for products. Only returns the product ID, link, and name in the product search hit. The search result only contains products that are online and assigned to the site catalog.
Parameters
organizationId(path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f_ecom_' followed by a 4-character realm identifier and a 3-character instance type identifier.Example
f_ecom_zzxy_prdselect(query, Select) The property selector declaring which fields are included in the product search response payload. For details, see Property Selection.Example
(hits.(**), refinements, sortingOptions.(id))siteId(query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.Example: SiteId
RefArchq(query, string) The query phrase to search for. For example to search for a product "shirt", type q=shirt. Note: - Lexical search queries are limited to a maximum of 50 characters.
Minimum length: 1. Maximum length: 500. Example:shirt.refine(query, array of string, style: form, explode: true)Parameter that represents a refinement attribute or values pair. Refinement attribute ID and values are separated by '='.
Multiple values are supported by a subset of refinement attributes and can be provided by separating them using a pipe (URL encoded = "|"), for example: refine=c_refinementColor=red|green|blue.
Value ranges can be specified like this: refine=price=(100..500).
Multiple refine parameters can be provided by using the refine as the key, for example: refine=price=(0..10)&refine=c_refinementColor=green.
The refinements can be a collection of custom defined attributes IDs and the system defined attributes IDs but the search can only accept a total of 9 refinements at a time.The following system refinement attribute ids are supported:
cgid: Allows refinement per single category ID. Multiple category IDs are not supported.
cgslug: Allows refinement by a category URL slug (for example,mens/clothing). The server resolves the slug to a category ID using the site's storefront URL mapping. If the slug can't be resolved to a category, the API returns a 400 error. This parameter is mutually exclusive withcgid. If both are provided,cgidtakes priority andcgslugis ignored.
price: Allows refinement per single price range. Multiple price ranges are not supported.
htype: Allow refinement by including only the provided hit types. Accepted types are 'product', 'master', 'set', 'bundle', 'slicing_group' (deprecated), 'variation_group'.
orderable_only: Unavailable products are excluded from the search results if true is set. Multiple refinement values are not supported.
ilids: Allows refining by inventory list IDs. Supports up to 10 inventory list IDs per request.
pmid: Allows refinement on the supplied promotion ID(s). When used withpmpt, filters products by their role in the promotion.
pmpt: Allows refinement per promotion product type. Must be used withpmidto filter products by their role in the promotion. Valid values are:all: Returns all products related to the promotion (default)qualifying: Returns only products that qualify for the promotion but don't receive the discount/bonusdiscounted: Returns only products that receive a discount in the promotionbonus: Returns only products that are given as bonuses in the promotion
Note: To refine a search using multiple promotion filters—for example, to find products in both the spring and summer campaigns—see Refining by Multiple Promotions.
Items: Maximum length: 4000. Example:price=(0..10). Maximum items: 9.sort(query, string) The ID of the sorting option to sort the search hits.
Maximum length: 256. Example:brand.searchMode(query, string)A hint for the search matching approach the platform should use for this request.
semanticselects meaning-based matching;lexicalselects keyword/token-based matching.The hint is non-authoritative and applies only to this request: the platform runs its full routing cascade and may demote a
semanticrequest tolexical(for example when the semantic index is unavailable). Always read the resolvedeffectiveSearchModefield in the response rather than assuming the requested mode was honored. When omitted, the platform's configured default applies.
Allowed values:semantic,lexical. Example:semantic.currency(query, CurrencyCode) A three letter uppercase currency code conforming to the ISO 4217 standard, or the stringN/Aindicating that a currency is not applicable.Example: CurrencyCode
USDlocale(query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameterAccept-Languagefollowing RFC 2616 & RFC 1766. This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.Example: LanguageCountry
en-USExample: CountryCode
USexpand(query, array of string) A comma-separated list with allowed values -availability,images,prices,represented_products,variations,promotions,custom_properties,slug. By default, the expand parameter includesavailability, images, prices, represented_products, variations. Use none to disable all expand options.
Items: Allowed values:none,availability,images,prices,represented_products,variations,promotions,custom_properties,page_meta_tags,slug. Example:prices.allImages(query, boolean) When theimagesexpand parameter is used with this flag, the response includes theimageGroupsproperty, which contains an image model. If this flag is true, the full image model is returned and you can combine withimgTypesto filter image types and counts. If false, only matching images are included. If no flag is passed, theimageGroupsproperty is omitted from the response.
Example:true.imgTypes(query, string) Filters product images by type with optional count limits per type. This parameter requires both theimagesexpand parameter andallImages=true. When used, the response includes theimageGroupsproperty filtered by the specified image types. The format is a comma-separated list of image types with optional counts:<imageType>:<count>,<imageType>:<count>. If the count is omitted, all images of that type are returned. If specified, the count limits the number of images returned for that type. For example,imgTypes=large:2,small:1returns up to 2 large images and 1 small image per product in the imageGroups. IfimgTypesis used withoutallImages=true, it is ignored and imageGroups aren't included in the response.
Maximum length: 50. Example:large:2,small:1.perPricebook(query, boolean) When this flag is set totrueand is used with thepricesexpand parameter, the response includes per PriceBook prices and tiered prices (if available).
Example:true.allVariationProperties(query, boolean) The flag that determines which variation properties are included in the result. When set totruewith thevariationsexpand parameter, all variation properties (variationAttributes,variationGroups,variants) are returned. When set to false, only the default propertyvariationAttributesis returned.
Example:false.includedCustomVariationProperties(query, array of string) A comma-separated list of custom property ids to be returned for variant products. Thevariantsexpand parameter andallVariationPropertiesquery parameter are required for these properties to be returned.
Items: Maximum length: 256. Pattern: ^c_.*. Example:c_batteryLife. Maximum items: 5.limit(query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.
Default:25. Minimum: 1. Maximum: 200.offset(query, integer (int32)) Used to retrieve the results based on a particular resource offset.
Default:0. Minimum: 0.sfdc_usid(header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.
Example:550e8400-e29b-41d4-a716-446655440000.personalized(query, string) Controls whether personalization is applied to the response. When set tonone, the server skips applying personalization to the response.
Allowed values:none. Example:none.sfdc_shopper_context(header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.
Responses
- 200
Product search successfully returned results.
Media type:
application/json. Schema:ProductSearchResult.Example: ProductSearchResultExample
{ "limit": 3, "hits": [ { "currency": "USD", "hitType": "master", "image": { "alt": "Modern Dress Shirt, , large", "disBaseLink": "https://edge.disstg.commercecloud.salesforce.com/dw/image/v2/ZZEU_006/on/demandware.static/-/Sites-apparel-catalog/default/dw7671b929/images/large/B0174501_GY9_0.jpg", "link": "https://zzeu-006.sandbox.us01.dx.commercecloud.salesforce.com/on/demandware.static/-/Sites-apparel-catalog/default/dw7671b929/images/large/B0174501_GY9_0.jpg", "title": "Modern Dress Shirt, " }, "orderable": true, "price": 135, "productId": "74974310", "productName": "Modern Dress Shirt", "productType": { "master": true }, "representedProduct": { "id": "74974310-1" }, "representedProducts": [ { "id": "74974310-1" }, { "id": "74974310-2" }, { "id": "74974310-3" }, { "id": "74974310-4" } ], "variationAttributes": [ { "id": "color", "name": "color", "values": [ { "name": "Blue", "orderable": true, "value": "002" } ] }, { "id": "size", "name": "size", "values": [ { "name": "15R", "orderable": true, "value": "15R" }, { "name": "15L", "orderable": true, "value": "15L" }, { "name": "16L", "orderable": true, "value": "16L" } ] } ] }, { "currency": "USD", "hitType": "master", "image": { "alt": "The White Dress Shirt, , large", "disBaseLink": "https://edge.disstg.commercecloud.salesforce.com/dw/image/v2/ZZEU_006/on/demandware.static/-/Sites-apparel-catalog/default/dw9368b001/images/large/70284588_100_0.jpg", "link": "https://zzeu-006.sandbox.us01.dx.commercecloud.salesforce.com/on/demandware.static/-/Sites-apparel-catalog/default/dw9368b001/images/large/70284588_100_0.jpg", "title": "The White Dress Shirt, " }, "orderable": true, "price": 135, "productId": "78916783", "productName": "The White Dress Shirt", "productType": { "master": true }, "representedProduct": { "id": "78916783-1" }, "representedProducts": [ { "id": "78916783-1" }, { "id": "78916783-2" }, { "id": "78916783-3" }, { "id": "78916783-4" } ], "variationAttributes": [ { "id": "color", "name": "Color", "values": [ { "name": "White", "orderable": true, "value": "white" } ] }, { "id": "size", "name": "size", "values": [ { "name": "15L", "orderable": true, "value": "15L" }, { "name": "15R", "orderable": true, "value": "15R" } ] } ] }, { "currency": "USD", "hitType": "master", "image": { "alt": "Striped Shirt, , large", "disBaseLink": "https://edge.disstg.commercecloud.salesforce.com/dw/image/v2/ZZEU_006/on/demandware.static/-/Sites-apparel-catalog/default/dw83b22281/images/large/PG.10213135.JJ9VSA5.PZ.jpg", "link": "https://zzeu-006.sandbox.us01.dx.commercecloud.salesforce.com/on/demandware.static/-/Sites-apparel-catalog/default/dw83b22281/images/large/PG.10213135.JJ9VSA5.PZ.jpg", "title": "Striped Shirt, " }, "orderable": true, "price": 40.99, "productId": "25518484", "productName": "Striped Shirt", "productType": { "master": true }, "representedProduct": { "id": "701642854760" }, "representedProducts": [ { "id": "701642854760" }, { "id": "701642854784" }, { "id": "701642854791" }, { "id": "701642854777" } ], "variationAttributes": [ { "id": "color", "name": "Color", "values": [ { "name": "Royal Multi", "orderable": true, "value": "JJ9VSA5" } ] }, { "id": "size", "name": "Size", "values": [ { "name": "S", "orderable": true, "value": "9SM" }, { "name": "M", "orderable": true, "value": "9MD" }, { "name": "L", "orderable": true, "value": "9LG" }, { "name": "XL", "orderable": true, "value": "9XL" } ] } ] } ], "pageMetaTags": [ { "id": "description", "value": "Browse our latest selection of shirts. Free shipping on orders over $50.", "type": "name" }, { "id": "robots", "value": "index,follow", "type": "name" }, { "id": "title", "value": "Find amazing products in Storefront Catalog - EN' today", "type": "title" }, { "id": "og:title", "value": "Shirts - Storefront Catalog", "type": "property" }, { "id": "itemList", "value": "{\"@context\":\"https://schema.org/\",\"@type\":\"ItemList\",\"name\":\"Shirts\",\"numberOfItems\":4}", "type": "jsonld" } ], "query": "shirt", "searchMode": "semantic", "effectiveSearchMode": "semantic", "refinements": [ { "attributeId": "cgid", "label": "Category", "values": [ { "hitCount": 4, "label": "New Arrivals", "value": "newarrivals" } ] }, { "attributeId": "c_refinementColor", "label": "Color", "values": [ { "hitCount": 0, "label": "Beige", "presentationId": "beige", "value": "Beige" }, { "hitCount": 0, "label": "Yellow", "presentationId": "yellow", "value": "Yellow" }, { "hitCount": 7, "label": "Miscellaneous", "presentationId": "miscellaneous", "value": "Miscellaneous" } ] }, { "attributeId": "price", "label": "Price", "values": [ { "hitCount": 14, "label": "$20 - $49.99", "value": "(20..50)" }, { "hitCount": 26, "label": "$50 - $99.99", "value": "(50..100)" }, { "hitCount": 6, "label": "$100 - $499.99", "value": "(100..500)" } ] }, { "attributeId": "c_isNew", "label": "New Arrival", "values": [ { "hitCount": 1, "label": "true", "value": "true" } ] }, { "attributeId": "brand", "label": "brand", "values": [ { "hitCount": 1, "label": "Lacy-S", "value": "Lacy-S" } ] } ], "searchPhraseSuggestions": { "suggestedPhrases": [ { "exactMatch": true, "phrase": "shirt" } ], "suggestedTerms": [ { "originalTerm": "shirt", "terms": [ { "completed": false, "corrected": false, "exactMatch": true, "value": "shirt" } ] } ] }, "sortingOptions": [ { "id": "best-matches", "label": "Best Matches" }, { "id": "price-low-to-high", "label": "Price Low To High" } ], "offset": 0, "total": 46 }Example: ProductSearchWithPromotionFilterExample Product search with promotion filtering using pmid and pmpt
Example showing how to filter products by their role in a promotion using pmid and pmpt parameters
{ "limit": 1, "hits": [ { "currency": "USD", "hitType": "master", "image": { "alt": "Platinum Red Stripes Easy Care Fitted Shirt, , large", "disBaseLink": "https://image.demandware.com/dw/image/v2/zzzz_s01/on/demandware.static/-/Sites-apparel-catalog/default/dw8c838411/images/large/PG.10123426.JJ8WXXX.PZ.jpg", "link": "https://localhost/on/demandware.static/-/Sites-apparel-catalog/default/dw8c838411/images/large/PG.10123426.JJ8WXXX.PZ.jpg", "title": "Platinum Red Stripes Easy Care Fitted Shirt, " }, "orderable": true, "price": 75, "pricePerUnit": 75, "productId": "25050730", "productName": "Platinum Red Stripes Easy Care Fitted Shirt", "productType": { "master": true }, "representedProduct": { "id": "008884304108" }, "representedProducts": [ { "id": "008884304108" } ], "variationAttributes": [ { "id": "color", "name": "Color", "values": [ { "name": "White", "orderable": true, "value": "JJ8WXXX" } ] }, { "id": "size", "name": "Size", "values": [ { "name": "6", "orderable": true, "value": "006" } ] } ] } ], "query": "shirts", "refinements": [ { "attributeId": "cgid", "label": "Category", "values": [ { "hitCount": 1, "label": "Womens", "value": "womens", "values": [ { "hitCount": 1, "label": "Clothing", "value": "womens-clothing", "values": [ { "hitCount": 1, "label": "Tops", "value": "womens-clothing-tops" } ] } ] } ] }, { "attributeId": "c_refinementColor", "label": "Color", "values": [ { "hitCount": 0, "label": "Beige", "presentationId": "beige", "value": "Beige" }, { "hitCount": 0, "label": "White", "presentationId": "white", "value": "White" } ] }, { "attributeId": "c_isNew", "label": "New Arrival" }, { "attributeId": "c_topType", "label": "Type | Use" }, { "attributeId": "c_size", "label": "Size", "values": [ { "hitCount": 0, "label": "4", "value": "4" }, { "hitCount": 1, "label": "6", "value": "6" }, { "hitCount": 0, "label": "8", "value": "8" } ] }, { "attributeId": "price", "label": "Price", "values": [ { "hitCount": 1, "label": "$50 - $99.99", "value": "(50..100)" } ] } ], "searchPhraseSuggestions": { "suggestedPhrases": [ { "exactMatch": true, "phrase": "shirts" } ], "suggestedTerms": [ { "originalTerm": "shirts", "terms": [ { "completed": false, "corrected": false, "exactMatch": true, "value": "shirts" } ] } ] }, "selectedRefinements": { "pmid": "BonusProductOnOrderOfAmountABove250", "pmpt": "bonus" }, "sortingOptions": [ { "id": "best-matches", "label": "Best Matches" }, { "id": "price-low-to-high", "label": "Price Low To High" }, { "id": "price-high-to-low", "label": "Price High to Low" }, { "id": "product-name-ascending", "label": "Product Name A - Z" }, { "id": "product-name-descending", "label": "Product Name Z - A" }, { "id": "brand", "label": "Brand" }, { "id": "most-popular", "label": "Most Popular" }, { "id": "top-sellers", "label": "Top Sellers" } ], "offset": 0, "total": 1 }Example: ProductSearchResultWithCustomVariationPropertiesExample Product search result demonstrating custom variation properties on product variants.
{ "limit": 1, "hits": [ { "hitType": "master", "productId": "portable-media-player", "productName": "Portable Media Player", "productType": { "master": true }, "representedProduct": { "id": "media-player-purple-8gb" }, "variants": [ { "productId": "media-player-silver-8gb", "variationValues": { "color": "Silver", "memorySize": "8 GB" }, "c_badges": [ "Popular" ], "c_mediaFormat": [ "0020", "0050" ], "c_musicStorage": "2,000 songs" }, { "productId": "media-player-purple-8gb", "variationValues": { "color": "Purple", "memorySize": "8 GB" }, "c_badges": [ "Best Seller" ], "c_mediaFormat": [ "0010", "0020", "0030" ], "c_musicStorage": "2,000 songs" } ] } ], "query": "media player purple", "refinements": [], "searchPhraseSuggestions": { "suggestedPhrases": [], "suggestedTerms": [] }, "sortingOptions": [ { "id": "best-matches", "label": "Best Matches" } ], "offset": 0, "total": 1 }Example: ProductSearchWithProcessedQueryExample Product search result demonstrating processors being executed on the search query.
{ "limit": 1, "hits": [ { "hitType": "master", "productId": "portable-media-player", "productName": "Portable Media Player", "productType": { "master": true }, "representedProduct": { "id": "media-player-purple-8gb" }, "variants": [ { "productId": "media-player-silver-8gb", "variationValues": { "color": "Silver", "memorySize": "8 GB" }, "c_badges": [ "Popular" ], "c_mediaFormat": [ "0020", "0050" ], "c_musicStorage": "2,000 songs" }, { "productId": "media-player-purple-8gb", "variationValues": { "color": "Purple", "memorySize": "8 GB" }, "c_badges": [ "Best Seller" ], "c_mediaFormat": [ "0010", "0020", "0030" ], "c_musicStorage": "2,000 songs" } ] } ], "processedQuery": { "appliedProcessors": [ { "processorName": "Attribute Aware Search", "refinements": { "price": "(..200)" }, "result": "media player purple" } ], "query": "media player purple" }, "query": "media player purple under 200", "refinements": [], "searchPhraseSuggestions": { "suggestedPhrases": [], "suggestedTerms": [] }, "sortingOptions": [ { "id": "best-matches", "label": "Best Matches" } ], "offset": 0, "total": 1 }Example: ProductSearchWithFallbackModeExample Product search where a semantic request was demoted to lexical.
The caller requested
searchMode=semantic, but the platform could not serve semantically (for example a single-token SKU lookup) and demoted tolexical. The response echoes the requestedsearchModeand reports the mode actually used ineffectiveSearchMode, which a client reads to detect that the requested mode was not honored.{ "limit": 25, "hits": [ { "currency": "USD", "hitType": "product", "orderable": true, "price": 19.99, "productId": "ABC-12345", "productName": "Classic Cotton Crew Sock", "productType": { "item": true }, "representedProduct": { "id": "ABC-12345" } }, { "currency": "USD", "hitType": "product", "orderable": true, "price": 24.99, "productId": "ABC-12346", "productName": "Ribbed Wool Blend Sock", "productType": { "item": true }, "representedProduct": { "id": "ABC-12346" } } ], "query": "ABC-12345", "searchMode": "semantic", "effectiveSearchMode": "lexical", "refinements": [], "searchPhraseSuggestions": { "suggestedPhrases": [], "suggestedTerms": [] }, "sortingOptions": [ { "id": "best-matches", "label": "Best Matches" } ], "offset": 0, "total": 2 }Example: ProductSearchWithConfiguredModeExample Product search with no requested mode, resolved by the platform's configured default.
The request omitted
searchMode, so the response omits the echoed hint and the platform's configured default selected the mode reported ineffectiveSearchMode.{ "limit": 25, "hits": [ { "currency": "USD", "hitType": "master", "orderable": true, "price": 39.99, "productId": "74974310", "productName": "Modern Dress Shirt", "productType": { "master": true }, "representedProduct": { "id": "74974310-1" } }, { "currency": "USD", "hitType": "master", "orderable": true, "price": 44.99, "productId": "78916783", "productName": "The White Dress Shirt", "productType": { "master": true }, "representedProduct": { "id": "78916783-1" } } ], "query": "shirt", "effectiveSearchMode": "semantic", "refinements": [], "searchPhraseSuggestions": { "suggestedPhrases": [], "suggestedTerms": [] }, "sortingOptions": [ { "id": "best-matches", "label": "Best Matches" } ], "offset": 0, "total": 2 } - 400
Bad Request.
Media type:
application/problem+json. Schema:ErrorResponse.Example: MalformedSelectorGetProductsSearchForSelect
{ "title": "Malformed Selector", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-selector", "detail": "The property selector '(hits.(currency, hitType,image.(**))' is malformed.", "selector": "(hits.(currency, hitType,image.(**))" }Example: TooManyCustomVariationAttributes
{ "title": "Bad Request", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "detail": "'includedCustomVariationProperties' violates the value constraint. The expected value is between '(0..5)'.", "parameter": "includedCustomVariationProperties", "expected": "(0..5)" }Example: InvalidCategorySlugRefinement
{ "title": "Invalid Category Slug Refinement", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-category-slug-refinement", "detail": "The category slug refinement 'i-dont-exist' could not be resolved to a category.", "categorySlug": "i-dont-exist" }Example: InvalidSearchMode
{ "title": "Bad Request", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "detail": "'searchMode' violates the value constraint. The expected value is one of '[semantic, lexical]'.", "parameter": "searchMode", "expected": "[semantic, lexical]" }