j1.10.1
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 select query 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-id header in your request — the response returns it as x-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:
- 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.
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
- Products (Admin) — Manage product catalogs, variations, and options.
Let us know so we can improve!