j1.3.0
API Overview
Use this API to access stores via search or ID lookup.
Authentication & Authorization
The Shopper Stores API requires a shopper access token from the Shopper Login and API Access Service (SLAS).
You must include sfcc.shopper-stores and other relevant scope(s) in the client ID used to generate the SLAS token. For a full list of permissions, see 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
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 the Shopper Stores 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
Search Stores by Location
Find stores within a radius of a geographic coordinate.
curl "https://{shortCode}.api.commercecloud.salesforce.com/store/shopper-stores/v1/organizations/{organizationId}/store-search?latitude=37.7749&longitude=-122.4194&distanceUnit=mi&maxDistance=25&siteId=RefArch" \
-H "Authorization: Bearer {access_token}"
Store Retrieval
- Specific Lookup: Retrieve detailed information for one or more stores using unique IDs.
- Localization: Fetch store data tailored to specific languages and regional formats using locale.
Location-Based Search
- Proximity Search: Find stores within a specific radius (miles or kilometers) of a shopper.
- Coordinate Search: Locate stores using precise latitude and longitude pairs.
- Postal Code Search: Identify stores near a specific zip or postal code using automated geolocation mapping.
Search Optimization
- Threshold Filtering: Limit results to a maximum distance from the shopper's location.
- Pagination: Manage large result sets efficiently using limit and offset parameters.
Related APIs
- Stores (Admin) — Manage store records and attributes.
Let us know so we can improve!