--- schema_version: "1" id: f4f3be1a625931ce88b971c9dab469a6c1c8182104be93e105c14e4772eb80cf title: Shopper Search collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-search.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search source_site: developer.salesforce.com content_type: documentation content_hash: af18ebf0597b49db62c40544e84b4afa7116fa9186598ffb9a7da8a213bca355 products: - B2C Commerce API - Salesforce APIs --- Shopper Search # Shopper Search [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-search/shopper-search-oas-v1-public.yaml) ## API Overview Use the Shopper Search API for search functionality that lets shoppers search for products using keywords and refinement. The search results can be products or suggestions based on the endpoint you choose in the API. ### Authentication & Authorization The client requesting the API must have access to the product search and search suggestion resources. The Shopper Search API requires a JWT acquired via the Shopper Customers endpoint: ``` https://{shortCode}.api.commercecloud.salesforce.com/customer/shopper-customers/v1/organizations/{organizationId}/customers/actions/login ``` You must include the relevant scopes in the client ID used to generate the SLAS token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html) ### Customization #### Custom Properties This API supports custom properties (prefixed with `c_`). For details, see [Custom Properties.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-properties.html) #### Hooks For details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html) ### Request Details #### Property Selection This API supports the `select` query parameter for filtering response properties. For details, see [Property Selection.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html) #### URL Encoding If resource identifiers in request parameters contain commas (`,`) or percent signs (`%`), they must be URL encoded. For details, see [Encode URL Special Characters.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-encode.html) ### Response Details #### Personalization Responses from this API can be personalized using the [Shopper Context API.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html) By setting context attributes such as customer group, source code, or store ID, you can retrieve personalized promotions, pricing, and shipping methods. For details on how personalization interacts with caching, see [Personalized Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html#personalized-caching) #### Caching Caching is provided for this API. For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html) #### Timeouts Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html) #### Error Handling Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html) ### Use Cases #### Search for Products Search for products by keyword. Replace `{access_token}` with a valid SLAS token. ```sh curl "https://{shortCode}.api.commercecloud.salesforce.com/search/shopper-search/v1/organizations/{organizationId}/product-search?q=dress&siteId=RefArch&limit=5" \ -H "Authorization: Bearer {access_token}" ``` #### Provide Search Suggestions Use the Shopper Search API to provide search suggestions as a shopper searches. For example, a developer who is building a shopping app using the Salesforce Commerce API would like to provide product, brand, and category suggestions. When a shopper types in a search phrase that exceeds a definable minimum length and the GET Search Suggestion endpoint is requested, the platform delivers a set of suggestions with products (name, ID), brands (name), and categories (name, ID). Shoppers can reach their desired search results more quickly using the suggested completion and correction. #### Provide Search Results Use the Shopper Search API to gather product results for a shoppers search query. For example, a developer who is building a shopping app using the Salesforce Commerce API would like to implement a product search functionality. When a shopper enters a search phrase and the GET Product Search endpoint is requested, the platform performs a keyword search and a sorted search result is returned. The sorted search result can be refined according to given values (for example, a price range). The product search result contains a definable number of product search hits. A product search hit describes a matching product with its ID and name. Furthermore, the search hit contains product images, prices, represented products, and variations. In addition to the search hits, the search results also deliver refinement and sorting options. #### Retrieve Promotion Information Note: This only applies if `promotions` expand is provided in the query parameter. Promotions provide discounts to shoppers when they meet certain purchase requirements. Promotion information is described in detail in [Promotion Details](https://developer.salesforce.com/docs/commerce/commerce-api/guide/promotion-details.html), but the following list provides several key points: * Pricing discounts for basket and shipping promotions are NEVER returned by the 'getProduct' or 'getProducts' endpoint. * Promotional pricing is ONLY returned for products that are included with non-conditional promotions. * Callout messages are ALWAYS returned by the 'getProduct' and 'getProducts' endpoints. By default, 'getProduct' and 'getProducts' return promotion information for a queried product. Promotion information includes both pricing and callout message information. However, the specific pricing and callout information that is fetched is determined by: * Promotion Type * Product Type * Product Purchase Requirements Some promotions can be displayed on a Product Data Page (PDP) or Product Listing page (PLP), while other promotions are displayed in the context of a basket, such as an order level promotion: "add the product to your basket to view price information". It is important to understand what is included in the response when designing a PDP or PLP on top of SCAPI to ensure your design aligns with implementable features. Note: When you search for a variant product, the Product Search API returns the master or main product as the primary search hit. When promotion data (productPromotion) is returned, it does not contain pricing information because the returned product is the main product. To retrieve pricing information, pass the query string `allVariationProperties=true` with the `promotions` expand parameter, which returns pricing data for variant products if the promotion is unconditional. The `allVariationProperties` flag specifies the variation properties to be included in the result. #### Filter Products by Promotion Role You can filter products by their role in a promotion using the `pmid` (promotion ID) and `pmpt` (promotion product type) refinement parameters together. This allows you to find specific types of products within a promotion: * `pmid`: Specifies the promotion ID to filter by * `pmpt`: Specifies the type of products to return within that promotion: * `all`: Returns all products related to the promotion (default behavior) * `qualifying`: Returns only products that qualify for the promotion but don't receive the discount/bonus * `discounted`: Returns only products that receive a discount in the promotion * `bonus`: Returns only products that are given as bonuses in the promotion Example Usage: ``` GET /organizations/{organizationId}/product-search?refine=pmid=summer-sale&refine=pmpt=discounted ``` This would return only the products that receive discounts in the "summer-sale" promotion. **Note:** The `pmpt` parameter only has an effect when used with `pmid`. If `pmpt` is specified without `pmid`, it will be ignored and all products will be returned. #### Shopper Personalization The SCAPI response can be personalized using the Shopper Context API or hooks. By setting specific values in the Shopper Context API, you can modify the response of the 'getProduct' or 'getProducts' endpoint based on the shopper's context. For instance, you can offer a 5% discount or free shipping to shoppers using mobile devices. ### JWA Caching The response is cached in JWA, which means promotion data contained in the response is also cached based on the TTL (Time to Live) specified in the Business Manager [Feature Switches](https://help.salesforce.com/s/articleView?id=cc.b2c_feature_switches.htm&type=5) configuration. When the shopper context value is updated, a check is conducted to see if the updated shopper context affects the retrieval of product-promotion data. If it does, then the response is fetched from the source and cached in the JWA. For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html) ### Best Practices These best practices refer to features that are generally available with B2C Commerce 24.3. For better performance, when you call the GET Product Search endpoint, we recommend that you: * Use the `select` query parameter to filter the response of a specified field or set of fields, and remove default outputs that you don't need. For example, filter the response to return only the relevant product names, ids, variants, and product IDs of the variants. * Limit API requests to the GET Product Search endpoint instead of calling both the GET Product Search and GET Products endpoints to show information on a product listing page (PLP). Use these features to provide the additional product information needed to render product tiles: * **Allowable value:** `promotions` value in the `expand` query parameter * **Query parameters:** `perPricebook`, `allImages`, and `allVariationProperties` * **Responses:** `productPromotions`, `imageGroups`, `priceRanges`, `tieredPrices`, `variants`, and `variationGroups` * Pass in only the `expand` values and query parameters that you consider necessary to meet your PLP requirements. Requesting large amounts of information can increase the latency, especially if there's a lot of data to be returned (for example, many imageGroups and variants). **Version:** 1.15.2 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/search/shopper-search/v1` * `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)` ## Security * `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both the Open Commerce API (OCAPI) and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token. * OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token) * Scope sfcc.shopper-product-search: Allows read operations on shopper search. * OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token) * Scope sfcc.shopper-product-search: Allows read operations on shopper search. * `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only. * OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context) * Scope sfcc.shopper-product-search: Allows read operations on shopper search. ## Operations ### 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `select` (query, Select) The property selector declaring which fields are included in the product search response payload. For details, see [Property Selection.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html) _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_ ``` RefArch ``` * `q` (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 with `cgid`. If both are provided, `cgid` takes priority and `cgslug` is 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 with `pmpt`, filters products by their role in the promotion. `pmpt`: Allows refinement per promotion product type. Must be used with `pmid` to 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/bonus * `discounted`: Returns only products that receive a discount in the promotion * `bonus`: 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](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-promotions-for-developers.html#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. `semantic` selects meaning-based matching; `lexical` selects 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 `semantic` request to `lexical` (for example when the semantic index is unavailable). Always read the resolved `effectiveSearchMode` field 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](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable. _Example: CurrencyCode_ ``` USD ``` * `locale` (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 parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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-US ``` _Example: CountryCode_ ``` US ``` * `expand` (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 includes `availability, 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 the `images` expand parameter is used with this flag, the response includes the `imageGroups` property, which contains an image model. If this flag is true, the full image model is returned and you can combine with `imgTypes` to filter image types and counts. If false, only matching images are included. If no flag is passed, the `imageGroups` property 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 the `images` expand parameter and `allImages=true`. When used, the response includes the `imageGroups` property filtered by the specified image types. The format is a comma-separated list of image types with optional counts: `:,:`. 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:1` returns up to 2 large images and 1 small image per product in the imageGroups. If `imgTypes` is used without `allImages=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 to `true` and is used with the `prices` expand 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 to `true` with the `variations` expand parameter, all variation properties (`variationAttributes`, `variationGroups`, `variants`) are returned. When set to false, only the default property `variationAttributes` is returned. Example: `false`. * `includedCustomVariationProperties` (query, array of string) A comma-separated list of custom property ids to be returned for variant products. The `variants` expand parameter and `allVariationProperties` query 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 to `none`, 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 to `lexical`. The response echoes the requested `searchMode` and reports the mode actually used in `effectiveSearchMode`, 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 in `effectiveSearchMode`. ``` { "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]" } ``` ### GET Provides keyword-based search suggestions for products, categories, and brands. Returns suggested items for each based on the search phrase. `GET /organizations/{organizationId}/search-suggestions` Operation ID: `getSearchSuggestions`. Security: ShopperToken (sfcc.shopper-product-search, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-product-search, sfcc.shopper-standard). Provide keyword search functionality for products, categories, and brands suggestions. Returns suggested products, suggested categories, and suggested brands for the given search phrase. #### 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `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_ ``` RefArch ``` * `q` (query, string, required) The search phrase (q) for which suggestions are evaluated. Search suggestions are determined when the search phrase input is at least three (default) characters long. The value is configurable in the Business Manager. Minimum length: 3. Maximum length: 50. Example: `sho`. * `searchMode` (query, string) A hint for the search matching approach the platform should use for this request. `semantic` selects meaning-based matching; `lexical` selects 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 `semantic` request to `lexical` (for example when the semantic index is unavailable). Always read the resolved `effectiveSearchMode` field 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`. * `limit` (query, integer) The maximum number of suggestions made per request. If no value is defined, by default five suggestions per suggestion type are evaluated. This affects all types of suggestions (category, product, brand, and custom suggestions). Default: `5`. Minimum: 1. Maximum: 10. Example: `5`. * `currency` (query, CurrencyCode) A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable. _Example: CurrencyCode_ ``` USD ``` * `locale` (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 parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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-US ``` _Example: CountryCode_ ``` US ``` * `expand` (query, array of string) A comma-separated list of the values `images`, `prices`, `custom_product_properties`, and `slug`. By default, the expand parameter includes `prices`. Items: Allowed values: `images`, `prices`, `custom_product_properties`, `slug`. Example: `prices`. * `includedCustomProductProperties` (query, array of string) A comma-separated list of custom property ids to be returned for product suggestions. The `custom_product_properties` expand parameter is required for these properties to be returned. Items: Maximum length: 256. Pattern: ^c\_.\*. Example: `c_batteryLife`. Maximum items: 5. * `includeEinsteinSuggestedPhrases` (query, boolean) The flag that determines whether or not to show recent and popular suggested phrases from Einstein. Example: `false`. * `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 to `none`, 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** Search suggestions successfully returned. Media type: `application/json`. Schema: `SuggestionResult`. _Example: SearchSuggestionResultExample_ ``` { "brandSuggestions": { "suggestedPhrases": [ { "exactMatch": false, "phrase": "Sony" } ], "suggestedTerms": [ { "originalTerm": "son", "terms": [ { "completed": true, "corrected": false, "exactMatch": false, "value": "sony" } ] } ] }, "categorySuggestions": { "suggestedTerms": [ { "originalTerm": "son" } ] }, "productSuggestions": { "products": [ { "currency": "EUR", "price": 300, "productId": "sony-ps3-bundle", "productName": "Playstation 3 Bundle" }, { "currency": "EUR", "price": 310, "productId": "sony-alpha350-wlen", "productName": "Sony Alpha 350 Digital SLR Camera w/18-70mm Lens" }, { "currency": "EUR", "price": 10, "productId": "sony-alpha900-body", "productName": "Sony Alpha 900 Digital SLR Camera (body only)" }, { "currency": "EUR", "price": 50, "productId": "sony-warhawk-ps3", "productName": "Warhawk (for Sony PS3)" }, { "currency": "EUR", "price": 280, "productId": "sony-psp-console", "productName": "Sony PSP® Game Console" } ], "suggestedPhrases": [ { "exactMatch": false, "phrase": "sony" } ], "suggestedTerms": [ { "originalTerm": "son", "terms": [ { "completed": true, "corrected": false, "exactMatch": false, "value": "sony" }, { "completed": true, "corrected": false, "exactMatch": false, "value": "sonyalpha" } ] } ] }, "einsteinSuggestedPhrases": { "popularSearchPhrases": [ { "exactMatch": false, "phrase": "sony" }, { "exactMatch": false, "phrase": "sony alpha" } ], "recentSearchPhrases": [ { "exactMatch": false, "phrase": "sony alpha" }, { "exactMatch": false, "phrase": "sony alpha 900 body" } ] }, "searchPhrase": "son", "searchMode": "semantic", "effectiveSearchMode": "semantic" } ``` _Example: SearchSuggestionResultWithCustomProductPropertiesExample_ Search suggestions with custom product properties. ``` { "brandSuggestions": { "suggestedPhrases": [ { "exactMatch": false, "phrase": "Media Player" } ], "suggestedTerms": [ { "originalTerm": "player", "terms": [ { "completed": true, "corrected": false, "exactMatch": false, "value": "media" } ] } ] }, "categorySuggestions": { "suggestedTerms": [ { "originalTerm": "player" } ] }, "productSuggestions": { "products": [ { "currency": "USD", "price": 229, "productId": "portable-media-player", "productName": "Portable Media Player", "c_badges": [], "c_mediaFormat": [ "0020", "0030" ], "c_musicStorage": "1,000 songs" } ], "suggestedPhrases": [ { "exactMatch": false, "phrase": "media player" } ], "suggestedTerms": [ { "originalTerm": "player", "terms": [ { "completed": true, "corrected": false, "exactMatch": true, "value": "player" }, { "completed": true, "corrected": false, "exactMatch": false, "value": "media player" } ] } ] }, "searchPhrase": "player" } ``` _Example: SearchSuggestionWithFallbackModeExample_ Search suggestions where a semantic request was demoted to lexical. The caller requested `searchMode=semantic` for type-ahead, but the platform demoted to `lexical`. The response echoes the requested `searchMode` and reports the mode actually used in `effectiveSearchMode`. ``` { "searchPhrase": "abc12345", "searchMode": "semantic", "effectiveSearchMode": "lexical" } ``` _Example: SearchSuggestionWithConfiguredModeExample_ Search suggestions 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 in `effectiveSearchMode`. ``` { "searchPhrase": "sho", "effectiveSearchMode": "semantic" } ``` * **400** Returned when a query parameter or its value is unknown, or when a maximum or minimum constraint is violated. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example InvalidSearchMode: same as GET /organizations/{organizationId}/product-search 400 response._ _Example: StringConstraintViolation_ ``` { "title": "String Constraint Violation", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/string-constraint-violation", "detail": "The string length constraint was violated by 'q'. The expected length is '(3..50)'.", "expected": "(3..50)", "parameter": "q" } ``` _Example: TooManyCustomProductAttributes_ ``` { "title": "Bad Request", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "detail": "'includedCustomProductProperties' violates the value constraint. The expected value is between '(0..5)'.", "parameter": "includedCustomProductProperties", "expected": "(0..5)" } ``` _Example: InvalidExpandParameter_ ``` { "title": "Invalid Expand Parameter", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-expand-parameter", "detail": "An invalid expand parameter 'invalidParameter' was found.", "param": "invalidParameter" } ``` ## Schemas ### OrganizationId 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). Type: `string`. Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`. ### Select The property selector declaring which fields are included into the response payload. You can specify a single field name, a comma-separated list of names or work with wildcards. You can also specify array operations and filter expressions. The actual selector value must be enclosed within parentheses. For more information, please read the documentation about property selectors [here](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html). Type: `string`. Minimum length: 1. Pattern: ^\[(\].\*\[)\]$. Example: `(name,id,variationAttributes.(**))`. ### SiteId 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 Type: `string`. Minimum length: 1. Maximum length: 32. Example: `RefArch`. ### CurrencyCode A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable. Type: `string`. Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`. ### 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 parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). 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. One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`. ### ProductSearchResult Document representing a product search result. Includes all fields of `PaginatedResultBase`. * `hits` (_array of ProductSearchHit_, required) A sorted array of search hits (`ProductSearchHit` objects). The array can be empty. Minimum length: 1. * `pageMetaTags` (_array of PageMetaTag_) Page Meta tags associated with the search result. * `query` (_string_, required) The query string that was searched for. Maximum length: 50. Example: `dresses`. * `searchMode` (_object_) The search matching approach the client requested for this search, echoed back from the `searchMode` query parameter. Omitted when the request did not supply one. This is the requested hint, not necessarily the mode that served the result — see `effectiveSearchMode`. Includes all fields of `SearchMode`. * `effectiveSearchMode` (_object_) The search matching approach the platform actually used to serve this result. May differ from the requested `searchMode` when the platform demoted the mode (for example when the semantic index is unavailable). Includes all fields of `SearchMode`. * `processedQuery` (_object_) The result of query processing. Includes all fields of `ProcessedQuery`. * `refinements` (_array of ProductSearchRefinement_, required) The sorted array of search refinements. This array can be empty. Minimum length: 1. * `searchPhraseSuggestions` (_object_, required) The suggestion given by the system for the submitted search phrase. Minimum length: 1. Includes all fields of `Suggestion`. Minimum length: 1. * `selectedRefinements` (_object_) A map of selected refinement attribute ID or value pairs. The sorting order is the same as in request URL. Additional properties: `string`. Maximum length: 4000. Example: `Beige`. * `selectedSortingOption` (_string_) The ID of the applied sorting option. Maximum length: 4000. Example: `best-matches`. * `sortingOptions` (_array of ProductSearchSortingOption_, required) The sorted array of search sorting options. This array can be empty. Minimum length: 1. ### ErrorResponse * `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization Maximum length: 256. Example: `You do not have enough credit`. * `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `NotEnoughMoney`. * `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem. Example: `Your current balance is 30, but that costs 50`. * `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `/account/12345/msgs/abc`. ### SuggestionResult Document representing a search suggestion result. * `brandSuggestions` (_object_) Returns the suggested brands. Includes all fields of `BrandSuggestions`. * `categorySuggestions` (_object_) Returns the suggested categories. Includes all fields of `CategorySuggestions`. * `productSuggestions` (_object_) Returns the suggested products. Includes all fields of `ProductSuggestions`. * `customSuggestion` (_object_) Returns custom suggestions. Includes all fields of `CustomSuggestions`. * `einsteinSuggestedPhrases` (_object_) Returns Einstein suggested phrases containing popular and recent search phrases. Includes all fields of `EinsteinSuggestedPhrases`. * `searchPhrase` (_string_, required) The query phrase (q) for which suggestions where made. Minimum length: 3. Maximum length: 50. Example: `dresses`. * `searchMode` (_object_) The search matching approach the client requested for these suggestions, echoed back from the `searchMode` query parameter. Omitted when the request did not supply one. This is the requested hint, not necessarily the mode that served the suggestions — see `effectiveSearchMode`. Includes all fields of `SearchMode`. * `effectiveSearchMode` (_object_) The search matching approach the platform actually used to serve these suggestions. May differ from the requested `searchMode` when the platform demoted the mode (for example when the semantic index is unavailable). Includes all fields of `SearchMode`. ### LanguageCountry A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'. Type: `string`. Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`. ### LanguageCode A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). Type: `string`. Pattern: ^\[a-z\]\[a-z\]$. Example: `en`. ### DefaultFallback A specialized value indicating the system default values for locales. Type: `string`. Default: `default`. Pattern: ^default$. Example: `default`. ### PaginatedResultBase Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`. Includes all fields of `ResultBase`. * `offset` (_Offset_, required) ### ProductSearchHit Document representing a product search hit. * `currency` (_CurrencyCode_) * `hitType` (_string_) The type information for the search hit. Maximum length: 256. Example: `product`. * `image` (_object_) The first image of the product hit for the configured viewtype. Includes all fields of `Image`. * `orderable` (_boolean_) A flag indicating whether the product is orderable. Example: `true`. * `price` (_number (double)_) The sales price of the product. In complex products, like master or set, this is the minimum price of related child products. Example: `135`. * `priceMax` (_number (double)_) The maximum sales of related child products in complex products like master or set. Example: `150`. * `productId` (_string_, required) The ID (SKU) of the product. Minimum length: 1. Maximum length: 100. Example: `74974310`. * `productName` (_string_) The localized name of the product. Maximum length: 4000. Example: `Modern Dress Shirt`. * `productType` (_object_) The type information for the product. Includes all fields of `ProductType`. * `representedProduct` (_object_) The first represented product. Includes all fields of `ProductRef`. * `representedProducts` (_array of ProductRef_) All the represented products. * `variationAttributes` (_array of VariationAttribute_) The array of represented variation attributes, for the master product only. This array can be empty. * `imageGroups` (_array of ImageGroup_) The array of product image groups. * `priceRanges` (_array of PriceRange_) Array of one or more price range objects representing one or more Pricebooks in context for the site. * `productPromotions` (_array of ProductPromotion_) The array of active customer product promotions for this product. This array can be empty. Coupon promotions are not returned in this array. * `tieredPrices` (_array of ProductPriceTable_) The document represents list of tiered prices if the product is a variant * `variants` (_array of Variant_) The array of actual variants. Only for master, variation group, and variant types. This array can be empty. * `variationGroups` (_array of VariationGroup_) The array of actual variation groups. Only for master, variation group, and variant types. This array can be empty. * `slug` (_string_) SEO-friendly slug for the product, derived from the site's configured product URL rule. This is the slug segment only, not a full URL. Returned only when `expand=slug` is requested. Use the slug to construct user-friendly product detail page URLs (for example, /products/{slug}/{productId}). Maximum length: 4000. Example: `modern-dress-shirt`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### PageMetaTag Document representing a Page Meta Tag object. * `id` (_string_) The ID of the Page Meta Tag. Maximum length: 100. Example: `title`. * `value` (_string_) Locale-specific value of the Page Meta Tag, evaluated by resolving the rule set for the given Business Manager ID. Example: `Buy the Long Sleeve Covered Placket Blouse for USD 61.99.`. * `type` (_string_) The kind of Page Meta Tag, indicating how the storefront should render the value. Documented values are `name`, `property`, `title`, and `jsonld`: * `name` — render as ``. * `property` — render as `` (e.g. Open Graph tags). * `title` — render as the HTML `` element. * `jsonld` — JSON-LD structured data, intended for rendering inside `<script type="application/ld+json">`. The field may be absent when the kind cannot be determined. Clients should treat unknown values as opaque so additional kinds can be introduced without breaking the contract. Maximum length: 64. Example: `name`. ### SearchMode A search matching approach. `semantic` is meaning-based matching; `lexical` is keyword/token-based matching. Type: `string`. Allowed values: `semantic`, `lexical`. Example: `semantic`. ### ProcessedQuery The result of query processing. * `query` (_query_) * `appliedProcessors` (_array of AppliedProcessor_) The processors that were executed for the search query and their results. Maximum items: 5. ### ProductSearchRefinement Document representing a product search refinement attribute. * `attributeId` (_string_, required) The ID of the search refinement attribute. In the case of an attribute refinement, this is the attribute ID. Custom attributes are marked by the prefix "c\_" (for example, "c\_refinementColor"). In the case of a category refinement, the ID must be "cgid". In the case of a price refinement, the ID must be "price". Minimum length: 1. Maximum length: 256. Example: `refinementColor`. * `label` (_string_) The localized label of the refinement. Maximum length: 256. Example: `Color`. * `values` (_array of ProductSearchRefinementValue_) The sorted array of refinement values. This array can be empty. ### Suggestion Document representing a suggestion. * `suggestedPhrases` (_array of SuggestedPhrase_) A list of suggested phrases. This list can be empty. * `suggestedTerms` (_array of SuggestedTerms_, required) A list of suggested terms. This list can be empty. Minimum length: 1. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### ProductSearchSortingOption Document representing a product search sorting option. * `id` (_string_, required) The ID of the sorting option. Minimum length: 1. Maximum length: 256. Example: `best-matches`. * `label` (_string_, required) The localized label of the sorting option. Minimum length: 1. Maximum length: 4000. Example: `Best Matches`. ### BrandSuggestions The suggested brand names are listed in suggested phrases. If this list is empty, no brand suggestion for a given search phrase was found. Includes all fields of `Suggestion`. ### CategorySuggestions Includes all fields of `Suggestion`. * `categories` (_array of SuggestedCategory_) The sorted list of suggested categories. This list can be empty. ### ProductSuggestions Includes all fields of `Suggestion`. * `products` (_array of SuggestedProduct_) The sorted list of suggested products. This list can be empty. ### CustomSuggestions The custom suggestions are listed in suggested phrases. If this list is empty, no custom suggestion for the given search phrase was found. Includes all fields of `Suggestion`. * `customSuggestion` (_string_) Example: `Try searching for budget shoes.`. ### EinsteinSuggestedPhrases Einstein-suggested phrases containing popular and recent search phrases. * `popularSearchPhrases` (_array of SuggestedPhrase_) A list of popular search phrases suggested by Einstein. This list can be empty. Maximum length: 10. * `recentSearchPhrases` (_array of SuggestedPhrase_) A list of recent search phrases suggested by Einstein. This list can be empty. Maximum length: 10. ### ResultBase Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned. * `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema. Example: `10`. * `total` (_Total_, required) ### Offset The zero-based index of the first hit/data to include in the result. Type: `integer (int32)`. Default: `0`. Minimum: 0. Example: `0`. ### Image * `alt` (_string_) Maximum length: 4000. Example: `The White Dress Shirt`. * `disBaseLink` (_string_) Maximum length: 4000. Example: `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` (_string_, required) Minimum length: 1. Maximum length: 4000. Example: `https://zzeu-006.sandbox.us01.dx.commercecloud.salesforce.com/on/demandware.static/-/Sites-apparel-catalog/default/dw9368b001/images/large/70284588_100_0.jpg`. * `title` (_string_) Maximum length: 4000. Example: `The White Dress Shirt`. ### ProductType Document representing a product type. * `bundle` (_boolean_) A flag indicating whether the product is a bundle. Example: `true`. * `item` (_boolean_) A flag indicating whether the product is a standard item. Example: `true`. * `master` (_boolean_) A flag indicating whether the product is a master. Example: `true`. * `option` (_boolean_) A flag indicating whether the product is an option. Example: `true`. * `set` (_boolean_) A flag indicating whether the product is a set. Example: `true`. * `variant` (_boolean_) A flag indicating whether the product is a variant. Example: `true`. * `variationGroup` (_boolean_) A flag indicating whether the product is a variation group. Example: `true`. ### ProductRef Document representing a product reference. * `id` (_string_, required) The ID of the product reference. Minimum length: 1. Maximum length: 100. Example: `74974310`. ### VariationAttribute Document representing a variation attribute. * `id` (_string_, required) The ID of the variation attribute. Minimum length: 1. Maximum length: 256. Example: `size`. * `name` (_string_) The localized display name of the variation attribute. Maximum length: 4000. Example: `size`. * `values` (_array of VariationAttributeValue_) The sorted array of variation values. This array can be empty. ### ImageGroup Document representing an image group containing a list of images for a particular view type and an optional variation value. * `images` (_array of Image_, required) The images of the image group. Minimum length: 1. * `variationAttributes` (_array of VariationAttribute_) Returns a list of variation attributes applying to this image group. * `viewType` (_string_, required) The image view type. Minimum length: 1. Maximum length: 256. Example: `hi-res`. ### PriceRange Document representing price ranges for a product which happens to be a master product (per Pricebook) * `maxPrice` (_number (double)_) Maximum price for the given pricebook (usually for a master Product would be the price for the Variant which has the highest price out of all Variants in that pricebook) Example: `10.89`. * `minPrice` (_number (double)_) Minimum price for the given pricebook (usually for a master Product would be the price for the Variant which has the least price out of all Variants in that pricebook) Example: `10.89`. * `pricebook` (_string_) The active pricebook from which the min and the max prices are calculated. The pricebook is based on the site context of the request as defined in ECOM. Maximum length: 256. Example: `usd-list-pricebook`. ### ProductPromotion Document representing a product promotion. * `calloutMsg` (_string_, required) The localized call-out message of the promotion. Minimum length: 1. Maximum length: 4000. Example: `Fantastic promotion`. * `promotionId` (_string_, required) The unique ID of the promotion. Minimum length: 1. Maximum length: 260. Example: `summerSale`. * `promotionalPrice` (_number (double)_, required) The promotional price for this product. Minimum length: 1. Example: `12.99`. ### ProductPriceTable Tiered Price Level Object * `price` (_number (double)_) Price for the product for the specified tier for the specified pricebook Example: `12.99`. * `pricebook` (_string_) The active pricebook for which this price is defined Maximum length: 256. Example: `usd-list-pricebook`. * `quantity` (_number (double)_) Quantity tier for which the price is defined. Example: `1`. ### Variant A product which is a variation within a master product that describes different colors, sizes, or other variation attributes. _Has a SKU._ * `orderable` (_boolean_) A flag indicating whether the variant is orderable. Example: `true`. * `price` (_number (double)_) The sales price of the variant. Example: `25.99`. * `productId` (_string_, required) The ID (SKU) of the variant. Minimum length: 1. Maximum length: 100. Example: `8W4756834`. * `tieredPrices` (_array of ProductPriceTable_) List of tiered prices if the product is a variant * `variationValues` (_object_) The actual variation attribute ID - value pairs. Additional properties: `string`. Maximum length: 4000. Example: `Beige`. * `productPromotions` (_array of ProductPromotion_) The array of active customer product promotions for this product. This array can be empty. Coupon promotions are not returned in this array. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### VariationGroup Representation of a group of variant products by an attribute. This can't be purchased by a shopper. It provides inheritable attributes for its product variants and is used for navigation. A VariationGroup doesn't have a SKU. * `orderable` (_boolean_, required) A flag indicating whether the variation group is orderable. Minimum length: 1. Example: `false`. * `price` (_number (double)_, required) The sales price of the variation group. Minimum length: 1. Example: `24.99`. * `productId` (_string_, required) The ID (SKU) of the variation group. Minimum length: 1. Maximum length: 100. Example: `49345VG`. * `variationValues` (_object_, required) The actual variation attribute ID - value pairs. Minimum length: 1. Minimum length: 1. Additional properties: `string`. Maximum length: 4000. Example: `Beige`. ### query The query string that was searched for. Type: `string`. Maximum length: 50. Example: `dresses`. ### AppliedProcessor The result of a processor execution. * `processorName` (_string_) The name of the processor. Maximum length: 256. Example: `Attribute Aware Search`. * `result` (_query_) * `refinements` (_object_) The refinements that were applied to the query. Additional properties: `string`. Maximum length: 256. Example: `Beige`. ### ProductSearchRefinementValue Document representing a product search refinement value. * `description` (_string_) The localized description of the refinement value. Maximum length: 4000. Example: `The Beige objects`. * `hitCount` (_integer (int32)_, required) The number of search hits when selecting the refinement value. Can be 0. Minimum length: 1. Example: `3`. * `label` (_string_, required) The localized label of the refinement value. Minimum length: 1. Maximum length: 4000. Example: `Beige`. * `presentationId` (_string_) The optional presentation ID associated with the refinement value. The presentation ID can be used, for example, to associate an ID with an HTML widget. Maximum length: 256. Example: `beige`. * `value` (_string_, required) The refinement value. In the case of an attribute refinement, this is the bucket, the attribute value, or a value range. In the case of a category refinement, this is the category ID. In the case of a price refinement, this is the price range. Ranges are enclosed by parentheses and delimited by ".."; for example, "(100..999)" and "(Aa..Fa)" are valid ranges. Minimum length: 1. Maximum length: 4000. Example: `Beige`. * `values` (_array of ProductSearchRefinementValue_) The array of hierarchical refinement values. This array can be empty. ### SuggestedPhrase Document representing a suggested search phrase. * `exactMatch` (_boolean_, required) Returns whether this suggested phrase exactly matches the user input search phrase. Minimum length: 1. Example: `true`. * `phrase` (_string_, required) Returns the suggested search phrase. Minimum length: 1. Maximum length: 50. Example: `sony`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### SuggestedTerms Document representing a list of suggested terms for each term of a search phrase. * `originalTerm` (_string_, required) Returns the original term that the suggested terms relates to. Minimum length: 1. Maximum length: 50. Example: `son`. * `terms` (_array of SuggestedTerm_) Returns the suggested terms. ### SuggestedCategory * `id` (_string_, required) The ID of the category. Minimum length: 1. Maximum length: 260. Example: `womens-clothing-dresses`. * `name` (_string_, required) The localized name of the category. Minimum length: 1. Maximum length: 4000. Example: `Dresses`. * `parentCategoryName` (_string_, required) The name of the parent category. Minimum length: 1. Maximum length: 4000. Example: `Clothing`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### SuggestedProduct Document representing a product search hit. * `currency` (_CurrencyCode_, required) * `price` (_number (double)_, required) The sales price of the product. In the case of complex products like a master or a set, this is the minimum price of related child products. Minimum length: 1. Example: `300`. * `productId` (_string_, required) The ID (SKU) of the product. Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`. * `productName` (_string_, required) The localized name of the product. Minimum length: 1. Maximum length: 4000. Example: `Playstation 3 Bundle`. * `slug` (_string_) SEO-friendly slug for the product, derived from the site's configured product URL rule. This is the slug segment only, not a full URL. Returned only when `expand=slug` is requested. Use the slug to construct user-friendly product detail page URLs (for example, /products/{slug}/{productId}). Maximum length: 4000. Example: `modern-dress-shirt`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### Total The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated. Type: `integer (int32)`. Default: `0`. Minimum: 0. Example: `10`. ### VariationAttributeValue Document representing a variation attribute value. * `description` (_string_) The localized description of the variation value. Maximum length: 4000. Example: `Size 15R`. * `image` (_object_) The first product image for the configured viewtype and this variation value. Includes all fields of `Image`. * `imageSwatch` (_object_) The first product image for the configured viewtype and this variation value. Typically the swatch image. Includes all fields of `Image`. * `name` (_string_) The localized display name of the variation value. Maximum length: 4000. Example: `15R`. * `orderable` (_boolean_) A flag indicating whether at least one variant with this variation attribute value is available to sell. Example: `true`. * `value` (_string_, required) The actual variation value. Minimum length: 1. Maximum length: 4000. Example: `15R`. ### SuggestedTerm Document representing a suggested term. * `completed` (_boolean_, required) Returns whether this term value is a completion match. Minimum length: 1. Example: `true`. * `corrected` (_boolean_, required) Returns whether this term value is a correction match. Minimum length: 1. Example: `false`. * `exactMatch` (_boolean_, required) Returns whether this term value is a exact match. Minimum length: 1. Example: `false`. * `value` (_string_, required) Returns the term value. Minimum length: 1. Maximum length: 50. Example: `sony`.