*# API Overview Available with B2C Commerce version 24.7.2, B2C Commerce teams must regularly configure site and environment-specific settings to support changing business needs and technical integrations. In many instances, Storefront Reference Architecture (SFRA)/SiteGenesis implementations rely on declarative Custom Site Preferences to alter these settings without the need for deployment or significant engineering support. Site preferences allow teams to adapt their sites with minimal effort.

The following Preferences API endpoints retrieve preference-related information:

• Global custom preferences: Retrieves all custom preferences at the organization level.

• Site custom prefererences: Retrieves all custom preferences at the site level.

The Preferences API first checks to see if custom values have been set, and if so, returns the custom settings. Otherwise, the Preferences API returns the default values provided in Business Manager.

Note: The Preferences API sets custom preferences. For details on working with non-custom preferences, see Global Preferences for B2C Commerce and Site Preferences in B2C Commerce.

Authentication & Authorization

The custom preference API requires a Account Manager token from the Admin APIs.

You must include the relevant scope(s) in the client ID used to generate the SLAS token. For details, see Authorization Scopes Catalog.

Use Cases

Global Custom Preference:

A prominent private equity firm manages a diverse portfolio of brands, each operating its own site. Despite the individuality of these brands, they leverage shared third-party integrations for critical functionalities, such as payments and content management. Through a centralized approach, the firm establishes specifications for key components like the payments portal, ensuring consistency and efficiency across all sites. These specifications are meticulously crafted and undergo infrequent modifications to accommodate evolving needs while maintaining operational stability.

Site Custom Preference:

Site operators might have numerous tests or features tailored to their specific site. To facilitate streamlined control over these functionalities, they need a user-friendly mechanism for their merchant team to effortlessly toggle them on or off as needed. The site Preference API provides this mechanism.

Caching

Caching capabilities are available for the Preferences APIs. For details, see Server-Side Web-Tier Caching.

Preferences

Global preferences

Site preferences*

For instructions on how to retrieve access token for admin APIs: https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html

Example with admin auth

import { Preferences, ClientConfig } from "commerce-sdk";
// or
const { Preferences, ClientConfig } = require("commerce-sdk");

const clientConfig: ClientConfig = {
  parameters: {
    clientId: "XXXXXX",
    organizationId: "XXXX",
    shortCode: "XXX",
    siteId: "XX"
  }
};

token = { access_token: 'INSERT_ACCESS_TOKEN_HERE' };

clientConfig.headers['authorization'] = `Bearer ${token.access_token}`;
const preferencesClient = new Preferences(clientConfig);

API Version: 1.4.4
Last Updated: