--- schema_version: "1" id: 71f1b12b6459c158ec0ae2ac0453a68b3d8ed8e62e545206b54f6caa5d6715f8 title: Shopper Stores 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-stores.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-stores source_site: developer.salesforce.com content_type: documentation content_hash: 5833a87199ff519c7936c2bd829bca9beb50518f3e7646fe60036fe533afb00c products: - B2C Commerce API - Salesforce APIs --- Shopper Stores # Shopper Stores [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-stores/shopper-stores-oas-v1-public.yaml) ## 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).](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html) 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.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html) For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) in the SLAS guides. ### 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 #### 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 the Shopper Stores 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 Stores by Location Find stores within a radius of a geographic coordinate. ```sh 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)](https://developer.salesforce.com/docs/commerce/commerce-api/references/stores?meta=Summary) — Manage store records and attributes. **Version:** 1.4.2 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/store/shopper-stores/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-stores: Allows read operations on shopper-stores * 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-stores: Allows read operations on shopper-stores * `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-stores: Allows read operations on shopper-stores ## Operations ### GET Return stores identified by the IDs provided as input. `GET /organizations/{organizationId}/stores` Operation ID: `getStores`. Security: ShopperToken (sfcc.shopper-stores, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-stores, sfcc.shopper-standard). #### 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 ``` * `ids` (query, string, required) The IDs of a requested stores (comma separated, max 50 IDs). Minimum length: 1. Maximum length: 256. * `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 ``` * `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 ``` * `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** Returned details for specific stores. Media type: `application/json`. Schema: `StoreResult`. _Example: StoresResult_ ``` { "data": [ { "address1": "1487 Bay St", "city": "Springfield", "countryCode": "US", "distance": 147.03, "distanceUnit": "km", "id": "store9", "name": "Springfield Media Store", "phone": "+1-413-413-6916", "posEnabled": false, "postalCode": "01109", "stateCode": "MA", "storeEvents": "Here are some store events.", "storeHours": "Here are the store hours", "storeLocatorEnabled": true }, { "address1": "70 Wood Ave", "city": "Bridgeport", "countryCode": "US", "distance": 198.36, "distanceUnit": "km", "email": "store1@company.com", "id": "store11", "name": "Electronics Super Store", "phone": "+1-203-965-7014", "posEnabled": false, "postalCode": "06605", "stateCode": "CT", "storeLocatorEnabled": true }, { "address1": "239 Bridge St", "city": "Manchester", "countryCode": "US", "distance": 219, "distanceUnit": "km", "id": "store8", "name": "Gardena Mart", "phone": "+1-603-715-9773", "posEnabled": false, "postalCode": "03104", "stateCode": "NH", "storeLocatorEnabled": true }, { "address1": "150 Winthrop Ave", "city": "Lawrence", "countryCode": "US", "distance": 242.77, "distanceUnit": "km", "id": "store6", "name": "Khale Street Electronics", "phone": "+1-978-580-2704", "posEnabled": false, "postalCode": "01843", "stateCode": "MA", "storeLocatorEnabled": true }, { "address1": "110 Smith St", "city": "Providence", "countryCode": "US", "distance": 245.02, "distanceUnit": "km", "email": "store2@company.com", "id": "store2", "name": "Super Electronics", "phone": "+1-401-312-6284", "posEnabled": false, "postalCode": "02903", "stateCode": "RI", "storeLocatorEnabled": true } ], "limit": 5, "total": 12 } ``` * **400** A value constraint for query parameters was violated. Or, a combination of latitude and longitude, a combination of country code and postal code, or an invalid distance\_unit was provided. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: MissingIds400_ ``` { "detail": "Missing required query parameter(s): 'ids'", "title": "Bad Request", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/missing-query-parameter" } ``` ### GET Retrieve a list of stores for the given site that are within a configured distance of a geolocation. `GET /organizations/{organizationId}/store-search` Operation ID: `searchStores`. Security: ShopperToken (sfcc.shopper-stores, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-stores, sfcc.shopper-standard). * The distance is interpreted either in miles or kilometers, depending on the `distanceUnit` input parameter. * The location is specified by either directly providing a latitude and longitude coordinate pair, or by providing a country and a postal code. If a postal code is passed, the resource looks in the system's geolocation mappings in Business Manager to find the coordinates for this postal code. If no matching geolocation is found, the resource returns an empty list of stores. If coordinates are passed, the values for country and postal code are ignored. To verify site latitude and longitude information in Business Manager: * Navigate to **Merchant Tools -> Online Marketing -> Stores**. * Select the applicable site. * In the **Address** tab, verify that valid information is provided in the following fields: **Address**, **City**, **Postal Code**, **State**, and **Country**. For latitude and longitude values, you can manually enter values or provide all field values to auto-populate **Latitude** and **Longitude**. You must provide valid values for all of the previous fields for latitude and longitude to auto-populate **Latitude** and **Longitude** values. #### 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 ``` * `countryCode` (query, CountryCode) The two letter ISO country code, such as "US". This value is required when a postalCode is provided. * `distanceUnit` (query, DistanceUnit) The distance unit. Supported values are "mi" (miles) and "km" (kilometers). The default is "km". * `latitude` (query, Latitude) The geographical latitude to search for stores (value range -90.00 .. 90.00). This value is required when a longitude is provided. * `longitude` (query, Longitude) The geographical longitude to search for stores (value range -180.00 .. 180.00). You must provide a longitude when a latitude is provided. * `maxDistance` (query, Distance) The area (radius) in distanceUnit where stores will be searched. * `postalCode` (query, PostalCode) The postal code, such as "84121". You must provide a countryCode when a postalCode is provided. * `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 ``` * `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 ``` * `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** Returned a list of stores for the given search parameters, up to the paging size, including their distance from the given geolocation and additional information on the pagination of objects. Media type: `application/json`. Schema: `Stores`. _Example: StoreSearchResult_ ``` { "data": [ { "address1": "1487 Bay St", "city": "Springfield", "countryCode": "US", "distance": 147.03, "distanceUnit": "km", "id": "store9", "name": "Springfield Media Store", "phone": "+1-413-413-6916", "posEnabled": false, "postalCode": "01109", "stateCode": "MA", "storeEvents": "Here are some store events.", "storeHours": "Here are the store hours", "storeLocatorEnabled": true }, { "address1": "70 Wood Ave", "city": "Bridgeport", "countryCode": "US", "distance": 198.36, "distanceUnit": "km", "email": "store1@company.com", "id": "store11", "name": "Electronics Super Store", "phone": "+1-203-965-7014", "posEnabled": false, "postalCode": "06605", "stateCode": "CT", "storeLocatorEnabled": true }, { "address1": "239 Bridge St", "city": "Manchester", "countryCode": "US", "distance": 219, "distanceUnit": "km", "id": "store8", "name": "Gardena Mart", "phone": "+1-603-715-9773", "posEnabled": false, "postalCode": "03104", "stateCode": "NH", "storeLocatorEnabled": true }, { "address1": "150 Winthrop Ave", "city": "Lawrence", "countryCode": "US", "distance": 242.77, "distanceUnit": "km", "id": "store6", "name": "Khale Street Electronics", "phone": "+1-978-580-2704", "posEnabled": false, "postalCode": "01843", "stateCode": "MA", "storeLocatorEnabled": true }, { "address1": "110 Smith St", "city": "Providence", "countryCode": "US", "distance": 245.02, "distanceUnit": "km", "email": "store2@company.com", "id": "store2", "name": "Super Electronics", "phone": "+1-401-312-6284", "posEnabled": false, "postalCode": "02903", "stateCode": "RI", "storeLocatorEnabled": true } ], "limit": 5, "offset": 0, "total": 12 } ``` * **400** A value constraint for query parameters was violated. Or, a combination of latitude and longitude, a combination of country code and postal code, or an invalid distance\_unit was provided. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: MissingPostalCode400_ ``` { "title": "Missing Postal Code", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/missing-postal-code", "detail": "The input parameter 'postal_code' is required when no coordinates are provided." } ``` ## 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`. ### 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`. ### 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`. ### StoreResult Result object containing an array of stores. Includes all fields of `ResultBase`. * `data` (_array of Store_) The list of stores in the search result. ### 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`. ### CountryCode A two letter uppercase country code conforming to the [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 standard. Type: `string`. Pattern: ^\[A-Z\]\[A-Z\]$. Example: `US`. ### DistanceUnit The unit the distance attribute is measured in (either in miles or kilometers). Type: `string`. Allowed values: `km`, `mi`. ### Latitude The latitude of the store. Type: `number (double)`. Minimum: -90. Maximum: 90. ### Longitude The longitude of the store. Type: `number (double)`. Minimum: -180. Maximum: 180. ### Distance The distance to the given geolocation where the stores will be searched, using the unit given in the attribute 'DistanceUnit' (miles or kilometers). Type: `number (double)`. Minimum: 0. Maximum: 20012. ### PostalCode The postal code of the store. Type: `string`. Minimum length: 3. Maximum length: 10. ### Stores Result object containing an paginated array of stores. Includes all fields of `PaginatedResultBase`. * `data` (_array of Store_) The list of stores in the search result. ### 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`. ### 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) ### Store Document representing a store. * `address1` (_string_) The primary address of the store. Minimum length: 1. * `address2` (_string_) The secondary address of the store. * `city` (_string_) The city of the store. * `countryCode` (_CountryCode_) * `distance` (_Distance_) * `distanceUnit` (_DistanceUnit_) * `email` (_string_) The email address of the store. * `fax` (_string_) The fax number of the store. * `id` (_string_, required) The id of the store. Minimum length: 1. Maximum length: 256. * `image` (_string_) The store image. * `inventoryId` (_string_) The inventory list id associated with this store. Maximum length: 256. * `latitude` (_Latitude_) * `longitude` (_Longitude_) * `name` (_string_) The store name. * `phone` (_string_) The phone number of the store. * `posEnabled` (_boolean_) Whether this store uses Store Point-of-Sale. * `postalCode` (_object_) The postal code of the store. Includes all fields of `PostalCode`. * `stateCode` (_string_) The state code of the store. * `storeEvents` (_string_) The store events. * `storeHours` (_string_) The opening hours of the store. * `storeLocatorEnabled` (_boolean_) Whether this store should show up in store locator results. ### 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) ### 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`. ### Offset The zero-based index of the first hit/data to include in the result. Type: `integer (int32)`. Default: `0`. Minimum: 0. Example: `0`.