Options
All
  • Public
  • Public/Protected
  • All
Menu

Class ShopperStores<ConfigParameters>

Shopper Stores

*Download API specification

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

Simple example:

  import { ShopperStores } from "commerce-sdk-isomorphic";

  const clientConfig = {
    parameters: {
      clientId: "XXXXXX",
      organizationId: "XXXX",
      shortCode: "XXX",
      siteId: "XX"
    }
  };
  const shopperStoresClient = new ShopperStores(clientConfig);
API Version: 0.0.33
Last Updated:

Type parameters

Hierarchy

  • ShopperStores

Index

Constructors

Properties

Methods

Object literals

Constructors

constructor

Properties

clientConfig

clientConfig: ClientConfig<ConfigParameters> & { baseUri: string }

Static Readonly defaultBaseUri

defaultBaseUri: "https://{shortCode}.api.commercecloud.salesforce.com/store/shopper-stores/v1" = currentBaseUri

Static Readonly paramKeys

paramKeys: { getStores: ["organizationId", "ids", "siteId", "locale", "personalized"]; getStoresRequired: ["organizationId", "ids", "siteId"]; searchStores: ["organizationId", "siteId", "countryCode", "distanceUnit", "latitude", "longitude", "maxDistance", "postalCode", "locale", "limit", "offset"]; searchStoresRequired: ["organizationId", "siteId"] } = {getStores: ['organizationId','ids','siteId','locale','personalized',],getStoresRequired: ['organizationId','ids','siteId',],searchStores: ['organizationId','siteId','countryCode','distanceUnit','latitude','longitude','maxDistance','postalCode','locale','limit','offset',],searchStoresRequired: ['organizationId','siteId',],} as const

Type declaration

  • getStores: ["organizationId", "ids", "siteId", "locale", "personalized"]
  • getStoresRequired: ["organizationId", "ids", "siteId"]
  • searchStores: ["organizationId", "siteId", "countryCode", "distanceUnit", "latitude", "longitude", "maxDistance", "postalCode", "locale", "limit", "offset"]
  • searchStoresRequired: ["organizationId", "siteId"]

Methods

getStores

  • If you would like to get a raw Response object use the other getStores function.

    Parameters

    Returns Promise<StoreResult>

    A promise of type StoreResult.

  • Type parameters

    • T: boolean

    Parameters

    Returns Promise<T extends true ? Response : StoreResult>

    A promise of type Response if rawResponse is true, a promise of type StoreResult otherwise.

searchStores

  • searchStores(options?: RequireParametersUnlessAllAreOptional<{ headers?: undefined | {}; parameters?: CompositeParameters<{ countryCode?: undefined | string; distanceUnit?: DistanceUnit; latitude?: undefined | number; limit?: undefined | number; locale?: LocaleCode; longitude?: undefined | number; maxDistance?: undefined | number; offset?: undefined | number; organizationId: string; postalCode?: undefined | string; siteId: string } & QueryParameters, ConfigParameters> }>): Promise<Stores>
  • searchStores<T>(options?: RequireParametersUnlessAllAreOptional<{ headers?: undefined | {}; parameters?: CompositeParameters<{ countryCode?: undefined | string; distanceUnit?: DistanceUnit; latitude?: undefined | number; limit?: undefined | number; locale?: LocaleCode; longitude?: undefined | number; maxDistance?: undefined | number; offset?: undefined | number; organizationId: string; postalCode?: undefined | string; siteId: string } & QueryParameters, ConfigParameters> }>, rawResponse?: T): Promise<T extends true ? Response : Stores>
    • 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.

    If you would like to get a raw Response object use the other searchStores function.

    Parameters

    • Optional options: RequireParametersUnlessAllAreOptional<{ headers?: undefined | {}; parameters?: CompositeParameters<{ countryCode?: undefined | string; distanceUnit?: DistanceUnit; latitude?: undefined | number; limit?: undefined | number; locale?: LocaleCode; longitude?: undefined | number; maxDistance?: undefined | number; offset?: undefined | number; organizationId: string; postalCode?: undefined | string; siteId: string } & QueryParameters, ConfigParameters> }>

      An object containing the options for this method.

    Returns Promise<Stores>

    A promise of type Stores.

    • 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.

    Type parameters

    • T: boolean

    Parameters

    • Optional options: RequireParametersUnlessAllAreOptional<{ headers?: undefined | {}; parameters?: CompositeParameters<{ countryCode?: undefined | string; distanceUnit?: DistanceUnit; latitude?: undefined | number; limit?: undefined | number; locale?: LocaleCode; longitude?: undefined | number; maxDistance?: undefined | number; offset?: undefined | number; organizationId: string; postalCode?: undefined | string; siteId: string } & QueryParameters, ConfigParameters> }>

      An object containing the options for this method.

    • Optional rawResponse: T

      Set to true to return entire Response object instead of DTO.

    Returns Promise<T extends true ? Response : Stores>

    A promise of type Response if rawResponse is true, a promise of type Stores otherwise.

Object literals

Static Readonly apiPaths

apiPaths: object

getStores

getStores: string = "/organizations/{organizationId}/stores"

searchStores

searchStores: string = "/organizations/{organizationId}/store-search"

Generated using TypeDoc