Options
All
  • Public
  • Public/Protected
  • All
Menu

Class ShopperExperience<ConfigParameters>

Shopper Experience

*Download API specification

API Overview

Use the Shopper Experience API to look up page information for pages that are created in Page Designer, content assets and to access content folders.

Authentication & Authorization

The Shopper Experience API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

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.

You must include sfcc.shopper-experience in the client ID used to generate the SLAS token. For a full list of required permissions, see the Authorization Scopes Catalog.

Important*: Currently, the Shopper Experience Pages endpoints can’t be used when the storefront password protection feature is enabled.

Use Cases

Access Content Folders

The API provides access to content folders, which are used to organize and manage content assets. Content folders support:

  • Hierarchical organization with nested subfolders
  • Localized metadata including names, descriptions, and SEO attributes
  • Custom attributes for extended functionality
  • Configurable depth levels for subfolder retrieval (0, 1, or 2 levels)

Only content folders that are marked as online are returned in the API responses.

Page Responses

Responses for pages include the following:

  • The entire component hierarchy of the page at design time.
  • All merchant data provided at design time.
  • Server-side scripting data provided at run time.

Both the page and components contain the values of all native and custom attributes that have been populated during page authoring.

Only visible pages are returned. Because the visibility of components is driven by rules (scheduling or customer groups, for example), these rules are subject to evaluation when assembling the component hierarchy in the response. Only components that are visible for the current customer context appear in the response. The same rules apply to the page itself, which is only be processed and returned if it is visible.

Content Asset Responses

Content asset responses include:

  • Rich content including text, HTML, and images
  • SEO metadata (title, description, keywords)
  • Template information for rendering
  • Folder organization structure
  • Custom attributes and properties

Only content assets that are marked as online are returned. Content assets provide flexible content management capabilities for storefronts.*

Simple example:

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

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

Type parameters

Hierarchy

  • ShopperExperience

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/experience/shopper-experience/v1" = currentBaseUri

Static Readonly paramKeys

paramKeys: { getContent: ["organizationId", "id", "siteId", "locale"]; getContentFolder: ["organizationId", "id", "siteId", "levels", "locale"]; getContentFolderRequired: ["organizationId", "id", "siteId"]; getContentFolders: ["organizationId", "ids", "siteId", "levels", "locale"]; getContentFoldersRequired: ["organizationId", "ids", "siteId"]; getContentRequired: ["organizationId", "id", "siteId"]; getMultipleContent: ["organizationId", "ids", "siteId", "locale"]; getMultipleContentRequired: ["organizationId", "ids", "siteId"]; getPage: ["pageId", "organizationId", "siteId", "aspectAttributes", "parameters", "locale"]; getPageRequired: ["pageId", "organizationId", "siteId"]; getPages: ["organizationId", "aspectTypeId", "siteId", "categoryId", "productId", "aspectAttributes", "parameters", "locale"]; getPagesRequired: ["organizationId", "aspectTypeId", "siteId"]; searchContent: ["organizationId", "siteId", "q", "refine", "sort", "locale", "limit", "offset"]; searchContentRequired: ["organizationId", "siteId"] } = {getContent: ['organizationId','id','siteId','locale',],getContentRequired: ['organizationId','id','siteId',],getContentFolder: ['organizationId','id','siteId','levels','locale',],getContentFolderRequired: ['organizationId','id','siteId',],getContentFolders: ['organizationId','ids','siteId','levels','locale',],getContentFoldersRequired: ['organizationId','ids','siteId',],getMultipleContent: ['organizationId','ids','siteId','locale',],getMultipleContentRequired: ['organizationId','ids','siteId',],getPage: ['pageId','organizationId','siteId','aspectAttributes','parameters','locale',],getPageRequired: ['pageId','organizationId','siteId',],getPages: ['organizationId','aspectTypeId','siteId','categoryId','productId','aspectAttributes','parameters','locale',],getPagesRequired: ['organizationId','aspectTypeId','siteId',],searchContent: ['organizationId','siteId','q','refine','sort','locale','limit','offset',],searchContentRequired: ['organizationId','siteId',],} as const

Type declaration

  • getContent: ["organizationId", "id", "siteId", "locale"]
  • getContentFolder: ["organizationId", "id", "siteId", "levels", "locale"]
  • getContentFolderRequired: ["organizationId", "id", "siteId"]
  • getContentFolders: ["organizationId", "ids", "siteId", "levels", "locale"]
  • getContentFoldersRequired: ["organizationId", "ids", "siteId"]
  • getContentRequired: ["organizationId", "id", "siteId"]
  • getMultipleContent: ["organizationId", "ids", "siteId", "locale"]
  • getMultipleContentRequired: ["organizationId", "ids", "siteId"]
  • getPage: ["pageId", "organizationId", "siteId", "aspectAttributes", "parameters", "locale"]
  • getPageRequired: ["pageId", "organizationId", "siteId"]
  • getPages: ["organizationId", "aspectTypeId", "siteId", "categoryId", "productId", "aspectAttributes", "parameters", "locale"]
  • getPagesRequired: ["organizationId", "aspectTypeId", "siteId"]
  • searchContent: ["organizationId", "siteId", "q", "refine", "sort", "locale", "limit", "offset"]
  • searchContentRequired: ["organizationId", "siteId"]

Methods

getContent

  • Get a content asset by its unique identifier. Only content assets that are marked as online are returned.

    Content assets contain rich content that can be displayed on storefronts, including text, HTML, images, and custom attributes.

    Important*:

    • Because this resource uses the GET method, you must not pass sensitive data and must not perform transactional processes.

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

    Parameters

    Returns Promise<Content>

    A promise of type Content.

  • Get a content asset by its unique identifier. Only content assets that are marked as online are returned.

    Content assets contain rich content that can be displayed on storefronts, including text, HTML, images, and custom attributes.

    Important*:

    • Because this resource uses the GET method, you must not pass sensitive data and must not perform transactional processes.

    Type parameters

    • T: boolean

    Parameters

    Returns Promise<T extends true ? Response : Content>

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

getContentFolder

  • To access a content folder, you construct a URL using the template shown below. This template requires you to specify a content folder id and a subfolder level. In response, the server returns a corresponding content folder document. Only content folders which are marked as online are returned.

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

    Parameters

    Returns Promise<ContentFolder>

    A promise of type ContentFolder.

  • To access a content folder, you construct a URL using the template shown below. This template requires you to specify a content folder id and a subfolder level. In response, the server returns a corresponding content folder document. Only content folders which are marked as online are returned.

    Type parameters

    • T: boolean

    Parameters

    Returns Promise<T extends true ? Response : ContentFolder>

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

getContentFolders

  • To access one or more content folders, you construct a URL using the template shown below. This template requires you to specify one or more content folder ids as a query parameter and a subfolder level. In response, the server returns a result set of corresponding content folder documents. Only content folders which are marked as online are returned.

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

    Parameters

    Returns Promise<ContentFolderResult>

    A promise of type ContentFolderResult.

  • To access one or more content folders, you construct a URL using the template shown below. This template requires you to specify one or more content folder ids as a query parameter and a subfolder level. In response, the server returns a result set of corresponding content folder documents. Only content folders which are marked as online are returned.

    Type parameters

    • T: boolean

    Parameters

    Returns Promise<T extends true ? Response : ContentFolderResult>

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

getMultipleContent

  • Get multiple content assets by their identifiers. Only content assets that are marked as online are returned.

    This endpoint allows you to retrieve multiple content assets in a single request, which is more efficient than making multiple individual requests.

    Important*:

    • Because this resource uses the GET method, you must not pass sensitive data and must not perform transactional processes.

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

    Parameters

    Returns Promise<ContentResult>

    A promise of type ContentResult.

  • Get multiple content assets by their identifiers. Only content assets that are marked as online are returned.

    This endpoint allows you to retrieve multiple content assets in a single request, which is more efficient than making multiple individual requests.

    Important*:

    • Because this resource uses the GET method, you must not pass sensitive data and must not perform transactional processes.

    Type parameters

    • T: boolean

    Parameters

    Returns Promise<T extends true ? Response : ContentResult>

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

getPage

  • Get a Page Designer page for a specific page ID. The results apply the visibility rules for the page's components, such as personalization or scheduled visibility.

    Important*:

    • Currently, you can't use the Shopper Experience Pages endpoints when the storefront password protection feature is enabled.
    • Because this resource uses the GET method, you must not pass sensitive data, for example: payment card information, and must not perform transactional processes within the server-side scripts that are run for the page and components.
    • Be aware that pagecache during fingerprint calculation will only be leveraged for pages and their components that don't use visibility rules. Furthermore the pagecaching of the actual response assembly solely depends on the response instrumentation with the serverside page type and component type script implementations. For more details also see the Page Designer Caching Guide.

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

    Parameters

    Returns Promise<Page>

    A promise of type Page.

  • Get a Page Designer page for a specific page ID. The results apply the visibility rules for the page's components, such as personalization or scheduled visibility.

    Important*:

    • Currently, you can't use the Shopper Experience Pages endpoints when the storefront password protection feature is enabled.
    • Because this resource uses the GET method, you must not pass sensitive data, for example: payment card information, and must not perform transactional processes within the server-side scripts that are run for the page and components.
    • Be aware that pagecache during fingerprint calculation will only be leveraged for pages and their components that don't use visibility rules. Furthermore the pagecaching of the actual response assembly solely depends on the response instrumentation with the serverside page type and component type script implementations. For more details also see the Page Designer Caching Guide.

    Type parameters

    • T: boolean

    Parameters

    • Optional options: RequireParametersUnlessAllAreOptional<{ headers?: undefined | {}; parameters?: CompositeParameters<{ aspectAttributes?: undefined | string; locale?: LocaleCode; organizationId: string; pageId: string; parameters?: 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 : Page>

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

getPages

  • Get Page Designer pages. The results apply the visibility rules for each page's components, such as personalization or scheduled visibility.

    You must provide the aspectTypeId along with either a categoryId or a productId. Since you can only create one page-to-product or page-to-category assignment per aspect type, the result contains at most one element.

    Important*:

    • Currently, you can't use the Shopper Experience Pages endpoints when the storefront password protection feature is enabled.
    • Because this resource uses the GET method, you must not pass sensitive data, for example: payment card information, and must not perform transactional processes within the server-side scripts that are run for the page and components.
    • Be aware that pagecache during fingerprint calculation will only be leveraged for pages and their components that don't use visibility rules. Furthermore the pagecaching of the actual response assembly solely depends on the response instrumentation with the serverside page type and component type script implementations. For more details also see the Page Designer Caching Guide.

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

    Parameters

    • Optional options: RequireParametersUnlessAllAreOptional<{ headers?: undefined | {}; parameters?: CompositeParameters<{ aspectAttributes?: undefined | string; aspectTypeId: string; categoryId?: undefined | string; locale?: LocaleCode; organizationId: string; parameters?: undefined | string; productId?: undefined | string; siteId: string } & QueryParameters, ConfigParameters> }>

      An object containing the options for this method.

    Returns Promise<PageResult>

    A promise of type PageResult.

  • Get Page Designer pages. The results apply the visibility rules for each page's components, such as personalization or scheduled visibility.

    You must provide the aspectTypeId along with either a categoryId or a productId. Since you can only create one page-to-product or page-to-category assignment per aspect type, the result contains at most one element.

    Important*:

    • Currently, you can't use the Shopper Experience Pages endpoints when the storefront password protection feature is enabled.
    • Because this resource uses the GET method, you must not pass sensitive data, for example: payment card information, and must not perform transactional processes within the server-side scripts that are run for the page and components.
    • Be aware that pagecache during fingerprint calculation will only be leveraged for pages and their components that don't use visibility rules. Furthermore the pagecaching of the actual response assembly solely depends on the response instrumentation with the serverside page type and component type script implementations. For more details also see the Page Designer Caching Guide.

    Type parameters

    • T: boolean

    Parameters

    • Optional options: RequireParametersUnlessAllAreOptional<{ headers?: undefined | {}; parameters?: CompositeParameters<{ aspectAttributes?: undefined | string; aspectTypeId: string; categoryId?: undefined | string; locale?: LocaleCode; organizationId: string; parameters?: undefined | string; productId?: 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 : PageResult>

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

searchContent

  • Provides keyword and refinement search functionality for content assets. The search result contains only content that is online and assigned to a folder.

    Refinement Parameters:* The following system refinement attribute IDs are supported:

    • fdid: Allows refinement per single content folder ID. Multiple folder IDs are not supported.

    Important*:

    • Because this resource uses the GET method, you must not pass sensitive data and must not perform transactional processes.

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

    Parameters

    • Optional options: RequireParametersUnlessAllAreOptional<{ headers?: undefined | {}; parameters?: CompositeParameters<{ limit?: undefined | number; locale?: LocaleCode; offset?: undefined | number; organizationId: string; q?: undefined | string; refine?: undefined | string; siteId: string; sort?: undefined | string } & QueryParameters, ConfigParameters> }>

      An object containing the options for this method.

    Returns Promise<ContentSearchResult>

    A promise of type ContentSearchResult.

  • Provides keyword and refinement search functionality for content assets. The search result contains only content that is online and assigned to a folder.

    Refinement Parameters:* The following system refinement attribute IDs are supported:

    • fdid: Allows refinement per single content folder ID. Multiple folder IDs are not supported.

    Important*:

    • Because this resource uses the GET method, you must not pass sensitive data and must not perform transactional processes.

    Type parameters

    • T: boolean

    Parameters

    • Optional options: RequireParametersUnlessAllAreOptional<{ headers?: undefined | {}; parameters?: CompositeParameters<{ limit?: undefined | number; locale?: LocaleCode; offset?: undefined | number; organizationId: string; q?: undefined | string; refine?: undefined | string; siteId: string; sort?: undefined | 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 : ContentSearchResult>

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

Object literals

Static Readonly apiPaths

apiPaths: object

getContent

getContent: string = "/organizations/{organizationId}/contents/{id}"

getContentFolder

getContentFolder: string = "/organizations/{organizationId}/folders/{id}"

getContentFolders

getContentFolders: string = "/organizations/{organizationId}/folders"

getMultipleContent

getMultipleContent: string = "/organizations/{organizationId}/contents"

getPage

getPage: string = "/organizations/{organizationId}/pages/{pageId}"

getPages

getPages: string = "/organizations/{organizationId}/pages"

searchContent

searchContent: string = "/organizations/{organizationId}/content-search"

Generated using TypeDoc