When you use the URL template, the server returns multiple categories (a result object of category documents). You can use this template to obtain up to 50 categories in a single request. You must enclose the list of IDs in parentheses. If a category identifier contains parenthesis or the separator sign, you must URL encode the character.
If you would like to get a raw Response object use the other getCategories function.
An object containing the options for this method.
A promise of type CategoryResult.
When you use the URL template, the server returns multiple categories (a result object of category documents). You can use this template to obtain up to 50 categories in a single request. You must enclose the list of IDs in parentheses. If a category identifier contains parenthesis or the separator sign, you must URL encode the character.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type CategoryResult otherwise.
When you use the URL template, the server returns a category identified by the ID. By default, the server also returns the first level of subcategories, but you can specify an additional level using the levels parameter.
This endpoint fetches both online and offline categories. For offline categories, only the top-level category is returned, not offline subcategories.
Using a large value for levels can cause performance issues when there is a large and deep category tree.
If you would like to get a raw Response object use the other getCategory function.
An object containing the options for this method.
A promise of type Category.
When you use the URL template, the server returns a category identified by the ID. By default, the server also returns the first level of subcategories, but you can specify an additional level using the levels parameter.
This endpoint fetches both online and offline categories. For offline categories, only the top-level category is returned, not offline subcategories.
Using a large value for levels can cause performance issues when there is a large and deep category tree.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type Category otherwise.
Allows access to product details for a single product ID. Only products that are online and assigned to a site catalog are returned. In addition to product details, the availability, images, price, bundled_products, set_products, recommendations, product options, variations, shipping_methods, and promotions for the products are included, as applicable.
If you would like to get a raw Response object use the other getProduct function.
An object containing the options for this method.
A promise of type Product.
Allows access to product details for a single product ID. Only products that are online and assigned to a site catalog are returned. In addition to product details, the availability, images, price, bundled_products, set_products, recommendations, product options, variations, shipping_methods, and promotions for the products are included, as applicable.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type Product otherwise.
Returns a Product document for the specified product ID, focused on imageGroups and related image fields. Only online products assigned to a site catalog are returned.
Use the following parameters to control image output: imgTypes — Filters which catalog view types to include, with optional per-type image limits. Defaults to all view types with a 200-image cap per type.
allImages — Controls whether the full image model is returned.
variationAttribute — Narrows image selection by variation context. Applies only when allImages is true.
If you would like to get a raw Response object use the other getProductImages function.
An object containing the options for this method.
A promise of type ProductImages.
Returns a Product document for the specified product ID, focused on imageGroups and related image fields. Only online products assigned to a site catalog are returned.
Use the following parameters to control image output: imgTypes — Filters which catalog view types to include, with optional per-type image limits. Defaults to all view types with a 200-image cap per type.
allImages — Controls whether the full image model is returned.
variationAttribute — Narrows image selection by variation context. Applies only when allImages is true.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type ProductImages otherwise.
Returns price details for a single product that is online and assigned to a site catalog. Returns the effective sales price, tiered prices, and per-pricebook prices. Prices are personalized by customer group and pricebook. Responses are not CDN-cached but are eligible for JWA caching with a 15-minute TTL.
If you would like to get a raw Response object use the other getProductPrices function.
An object containing the options for this method.
A promise of type PricesResult.
Returns price details for a single product that is online and assigned to a site catalog. Returns the effective sales price, tiered prices, and per-pricebook prices. Prices are personalized by customer group and pricebook. Responses are not CDN-cached but are eligible for JWA caching with a 15-minute TTL.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type PricesResult otherwise.
Returns active promotion details for a single product that is online and assigned to a site catalog. Active promotions are filtered by customer group, campaign date range, and time slot. Promotions are personalized. Responses are not CDN-cached but are eligible for JWA caching with a 15-minute TTL.
If you would like to get a raw Response object use the other getProductPromotions function.
An object containing the options for this method.
A promise of type PromotionsResult.
Returns active promotion details for a single product that is online and assigned to a site catalog. Active promotions are filtered by customer group, campaign date range, and time slot. Promotions are personalized. Responses are not CDN-cached but are eligible for JWA caching with a 15-minute TTL.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type PromotionsResult otherwise.
Allows access to multiple product details with a single request. Only products that are online and assigned to a site catalog are returned. The maximum number of product IDs that you can request is 24. In addition to product details, the availability, images, price, bundled_products, set_products, recommendations, product options, variations, shipping_methods, and promotions for the products are included, as applicable.
If you would like to get a raw Response object use the other getProducts function.
An object containing the options for this method.
A promise of type ProductResult.
Allows access to multiple product details with a single request. Only products that are online and assigned to a site catalog are returned. The maximum number of product IDs that you can request is 24. In addition to product details, the availability, images, price, bundled_products, set_products, recommendations, product options, variations, shipping_methods, and promotions for the products are included, as applicable.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type ProductResult otherwise.
Generated using TypeDoc
Shopper Products
*Download API specification
API Overview
The Shopper Products API enables you to access product details for products that are online, merchandised to a particular site catalog, and ready to be sold. You can use these product details to merchandise the product on other ecommerce channels. To set up category navigation paths on other commerce apps or storefronts, you can use the Categories API.
Authentication & Authorization
The client requesting the product information must have access to the Products resource. The Shopper Products API requires a shopper access token from the Shopper Login and API Access Service (SLAS).
You must include the relevant scopes in the client ID used to generate the SLAS token. For a full list of required permissions, see the Authorization Scopes Catalog.
For details on how to request a shopper access token from SLAS, see the guest user flows for public clients and private clients in the SLAS guides.
Customization
Custom Properties
This API supports custom properties (prefixed with
c_). For details, see Custom Properties.Hooks
For details on working with hooks, see Extensibility with Hooks.
Request Details
Property Selection
This API supports the
selectquery parameter for filtering response properties. For details, see Property Selection.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.Response Details
Personalization
Responses from this API can be personalized using the Shopper Context API. 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.
Caching
Caching is provided for this API. For details, see Server-Side Web-Tier Caching.
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.
Error Handling
Error responses follow the RFC 7807 problem detail format. To trace errors, include a
correlation-idheader in your request — the response returns it asx-correlation-id. For details, see HTTP Status Codes and Errors.Use Cases
Get a Single Product
Retrieve product details by ID. Replace
{access_token}with a valid SLAS token.curl "https://{shortCode}.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/{organizationId}/products/25695327M?siteId=RefArch" \ -H "Authorization: Bearer {access_token}"Get Multiple Products
Retrieve up to 24 products in a single request:
curl "https://{shortCode}.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/{organizationId}/products?ids=25695327M,25519318M&siteId=RefArch" \ -H "Authorization: Bearer {access_token}"Populate Product Listing Pages
Use the Shopper Product API so that a customer, browsing on a commerce shopping app built using Commerce Cloud APIs, can see a list of products. For example, hydrate a list of products (max 24). The API returns product details including images, prices, promotions, and product availability.
Get Variation Product Details on an Ecommerce Channel
Use the API so that a customer, browsing on a commerce shopping app built using Commerce Cloud APIs, can switch between different variation products. The API returns product details including images, prices, promotions, and available to sell inventory.
Retrieve Promotion Information
Promotions provide discounts to shoppers when they meet certain purchase requirements.
Promotion information is described in detail in Promotion Details, but the following list provides several key points:
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:
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.
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 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.
Resources
Product
A full representation of a product or service that is to merchandise. A ready to merchandise product is one that is online, categorized, and published to a channel. The information associated with a product includes, the product name, description, custom and system attributes, variations, price, availability, and images.
Category
Categories and subcategories are the structure by which products are organized and grouped in a catalog and on a storefront. Categories can have relationships to other categories. Further, each category can provide context that is inherited by subcategories. For example, a category can have an assigned attribute. A product assigned to that category or any subcategory inherits the categories’s attribute value. Once the product is removed from the category, the attribute value is no longer inherited by the product. You can also use category linking for site hierarchical navigation. For example, inside the Clothing category you may have Men’s, and inside the Men’s category you may have Pants.
Categories are not tags.
Related APIs
Simple example:
import { ShopperProducts } from "commerce-sdk-isomorphic"; const clientConfig = { parameters: { clientId: "XXXXXX", organizationId: "XXXX", shortCode: "XXX", siteId: "XX" } }; const shopperProductsClient = new ShopperProducts(clientConfig);Last Updated: