---
schema_version: "1"
id: 35f8a5a5f663fbd76cb1f89f3ba355451755f2908596a7b80fd267ddfb0f53e3
title: Shopper Experience
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-experience.md
canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-experience
source_site: developer.salesforce.com
content_type: documentation
content_hash: 200f05b4e0c95115be5b844e4eee6434c5953886f231a9144500c4d42b91f9be
products:
- B2C Commerce API
- Salesforce APIs
---
Shopper Experience
# Shopper Experience
[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-experience/shopper-experience-oas-v1-public.yaml)
## API Overview
Use the Shopper Experience API to look up page information for pages created in Page Designer, search and retrieve content assets, and 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html#guest-user) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html#guest-user) 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.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)
**Important**: Currently, the Shopper Experience Pages endpoints can’t be used when the [storefront password protection](https://help.salesforce.com/s/articleView?id=cc.b2c_storefront_password_protection.htm&type=5) feature is enabled.
### Response Details
#### Personalization
Responses from this API are not personalized via the Shopper Context API. Page Designer uses its own visibility rules (scheduling, customer groups) to control component visibility.
#### Caching
Caching is provided for the Shopper Experience API. For details, see [Server-Side Web-Tier Caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html) and [Page Designer Caching](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-dev-for-page-designer.html#page-designer-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.](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
#### Get a Page Designer Page
Retrieve a Page Designer page by ID.
```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/experience/shopper-experience/v1/organizations/{organizationId}/pages/{pageId}?siteId=RefArch" \
-H "Authorization: Bearer {access_token}"
```
#### 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.
#### Search Content Assets
Search for content assets using keywords and refinement filters. The search functionality supports:
* Keyword-based search across content assets
* Refinement attributes to filter results, for example, by folder or content type
* Sorting by configurable attributes
* Pagination for large result sets (up to 200 items per page)
Only content assets that are online and assigned to a folder are included in search results.
#### Batch Retrieval
Retrieve multiple content assets or content folders in a single API request for improved performance (up to 50 content assets or folders at once).
### 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.
* Tracking for each rendered component or fragment using a globally unique content link UUID.
* Support for reusable component fragments that can be shared across multiple pages.
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 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.
### Related APIs
* [Experiences (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/experiences?meta=Summary) — Manage Page Designer pages and content assets.
**Version:** 1.7.2
## Servers
* `https://{shortCode}.api.commercecloud.salesforce.com/experience/shopper-experience/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-experience: Shopper Experience scope READONLY
* Scope sfcc.shopper-experience.pages: Shopper Experience scope READONLY for pages
* Scope sfcc.shopper-experience.contents: Shopper Experience scope READONLY for contents
* Scope sfcc.shopper-experience.folders: Shopper Experience scope READONLY for folders
* Scope sfcc.shopper-experience.qualifiers: Shopper Experience scope for resolving qualifiers
* 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-experience: Shopper Experience scope READONLY
* Scope sfcc.shopper-experience.pages: Shopper Experience scope READONLY for pages
* Scope sfcc.shopper-experience.contents: Shopper Experience scope READONLY for contents
* Scope sfcc.shopper-experience.folders: Shopper Experience scope READONLY for folders
* Scope sfcc.shopper-experience.qualifiers: Shopper Experience scope for resolving qualifiers
* `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-experience: Shopper Experience scope READONLY
* Scope sfcc.shopper-experience.pages: Shopper Experience scope READONLY for pages
* Scope sfcc.shopper-experience.contents: Shopper Experience scope READONLY for contents
* Scope sfcc.shopper-experience.folders: Shopper Experience scope READONLY for folders
* Scope sfcc.shopper-experience.qualifiers: Shopper Experience scope for resolving qualifiers
## Operations
### GET Get Page Designer pages.
`GET /organizations/{organizationId}/pages`
Operation ID: `getPages`. Security: ShopperToken (sfcc.shopper-experience, sfcc.shopper-experience.pages, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-experience, sfcc.shopper-experience.pages, sfcc.shopper-standard).
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](https://help.salesforce.com/s/articleView?id=cc.b2c_storefront_password_protection.htm&type=5) 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](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-dev-for-page-designer.html#page-caching).
#### 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
```
* `categoryId` (query, string) Category identifier that is used for searching the page assignment. Must be provided if no `productId` is provided.
Maximum length: 256. Example: `home-clearance`.
* `productId` (query, string) Product identifier that is used for searching the page assignment. Must be provided if no `categoryId` is provided.
Maximum length: 100. Example: `iphone11`.
* `aspectTypeId` (query, string, required) Aspect type identifier that is used for searching the page assignment in conjunction with either the `productId` or `categoryId`.
Maximum length: 256. Example: `pdp`.
* `aspectAttributes` (query, string) A JSON representation of aspect attributes. Each aspect attribute is a key/value pair. Aspect attributes serve as a runtime parameter contract between caller (for example, this API or the DWScript API) and callee (the page). This parameter must not contain more than 256 characters after URL decoding.
Maximum length: 256. Example: `{ "product" : "iphone11", "breadcrumbCategory" : "home-clearance" }`.
* `parameters` (query, string) A free-form definition of parameters that influences the page rendering according to its implementation. This parameter must not contain more than 256 characters after URL decoding.
Maximum length: 256. Example: `refine=color,size;currency=USD;showNavigation=false`.
* `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** Success.
Media type: `application/json`. Schema: `PageResult`.
_Example: PageResult_
```
{
"data": [
{
"id": "homePpage",
"typeId": "storePage",
"aspectTypeId": "pdpAspect",
"name": "Homepage",
"description": "Home page of the storefront.",
"pageTitle": "Homepage - My Shop",
"pageDescription": "Get started shopping",
"pageKeywords": "fashion, my shop",
"data": {
"thumbnail": "myshop.jpg"
},
"custom": {
"thumbnail_full": "http://static.myshop.com/myshop.jpg"
},
"visible": true,
"localized": true,
"designMetadata": {
"id": "storePage",
"name": "Store Page",
"archType": "headless"
},
"regions": [
{
"id": "header",
"components": [
{
"id": "2192f5b9aac0f2af2385f6f6b7",
"typeId": "commerce_assets.banner",
"name": "Sale Banner",
"fragment": false,
"embedded": false,
"contentLinkUuid": "a7b2c4d8e1f9032a5b6c7d8e9f0",
"data": {
"title": "Products On Sale",
"bannerImage": "sale/topsellerPromo.jpg"
},
"localized": true,
"visible": true,
"custom": {
"thumbnail_full": "http://static.myshop.com/sale/topsellerPromo.jpg"
},
"designMetadata": {
"id": "commerce_assets.banner",
"name": "Banner Component",
"archType": "headless"
}
}
]
},
{
"id": "main",
"components": [
{
"id": "5c5ebbcd2aee1a67af519c83b5",
"typeId": "commerce_assets.carousel",
"name": "Topseller Carousel",
"fragment": false,
"embedded": false,
"contentLinkUuid": "3f8e2a1b5c9d7e4f0a2b3c6d8e1",
"data": {
"title": "Topseller",
"category": "topseller"
},
"localized": true,
"visible": true,
"custom": {
"detailUrl": "www.myshop.com/topseller"
},
"designMetadata": {
"id": "commerce_assets.carousel",
"name": "Carousel Component",
"archType": "headless"
},
"regions": [
{
"id": "tiles",
"components": [
{
"id": "d98a30dfe93715e3e6fc22a329",
"typeId": "commerce_assets.productTile",
"fragment": true,
"embedded": false,
"contentLinkUuid": "c4d6e8f0a2b4c6d8e0f2a4b6c8d",
"data": {
"product": "iphone6"
},
"localized": false,
"visible": true
},
{
"id": "43aa39896afb9292308181ce14",
"typeId": "commerce_assets.productTile",
"fragment": false,
"embedded": false,
"contentLinkUuid": "9e1a3c5d7f0b2e4a6c8d0f2b4e6",
"data": {
"product": "iphone7"
},
"localized": true,
"visible": false
}
]
}
]
}
]
}
]
},
{
"id": "detailpage",
"typeId": "storePage",
"name": "storepage",
"description": "A Store page",
"pageTitle": "A Store",
"pageDescription": "Buy in store",
"pageKeywords": "fashion, my shop, store",
"data": {
"thumbnail": "mystore.jpg"
},
"visible": true,
"localized": false,
"designMetadata": {
"id": "storePage",
"name": "Store Page",
"archType": "headless"
}
}
]
}
```
* **400** Business Object ID Invalid
Media type: `application/problem+json`. Schema: `ErrorResponse`.
_Example: BusinessObjectIDInvalid_
```
{
"title": "Business Object ID Invalid",
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/business-object-id-invalid",
"detail": "At least one provided business object identifier was invalid. This means either none was provided at all or exclusiveness of multiple identifiers wasn't honored or the referenced business object didn't exist."
}
```
* **404** Requested Aspect Type Not Found
Media type: `application/problem+json`. Schema: `ErrorResponse`.
_Example: AspectTypeNotFound_
```
{
"title": "Aspect Type Not Found",
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/aspect-type-not-found",
"detail": "No aspect type with ID 'pdp' was found in site 'RefArch'."
}
```
### GET Get a Page Designer page based on a single page ID.
`GET /organizations/{organizationId}/pages/{pageId}`
Operation ID: `getPage`. Security: ShopperToken (sfcc.shopper-experience, sfcc.shopper-experience.pages, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-experience, sfcc.shopper-experience.pages, sfcc.shopper-standard).
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](https://help.salesforce.com/s/articleView?id=cc.b2c_storefront_password_protection.htm&type=5) 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](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-dev-for-page-designer.html#page-caching).
#### Parameters
* `pageId` (path, string, required) Identifier for the requested page.
Maximum length: 256. Example: `homepage`.
* `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
```
* `aspectAttributes` (query, string) A JSON representation of aspect attributes. Each aspect attribute is a key/value pair. Aspect attributes serve as a runtime parameter contract between caller (for example, this API or the DWScript API) and callee (the page). This parameter must not contain more than 256 characters after URL decoding.
Maximum length: 256. Example: `{ "product" : "iphone11", "breadcrumbCategory" : "home-clearance" }`.
* `parameters` (query, string) A free-form definition of parameters that influences the page rendering according to its implementation. This parameter must not contain more than 256 characters after URL decoding.
Maximum length: 256. Example: `refine=color,size;currency=USD;showNavigation=false`.
* `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** Success.
Media type: `application/json`. Schema: `Page`.
_Example: Page_
```
{
"id": "homepage",
"typeId": "storePage",
"aspectTypeId": "pdpAspect",
"name": "Homepage",
"description": "Home page of the storefront.",
"pageTitle": "Homepage - My Shop",
"pageDescription": "Get started shopping",
"pageKeywords": "fashion, my shop",
"data": {
"thumbnail": "myshop.jpg"
},
"custom": {
"thumbnail_full": "http://static.myshop.com/myshop.jpg"
},
"visible": true,
"localized": true,
"designMetadata": {
"id": "storePage",
"name": "Store Page",
"archType": "headless"
},
"regions": [
{
"id": "header",
"components": [
{
"id": "375b9107b067902827083772f9",
"typeId": "commerce_assets.banner",
"name": "Sale Banner",
"fragment": false,
"embedded": false,
"contentLinkUuid": "2b4d6f8a0c2e4a6b8d0f2a4c6e8",
"data": {
"title": "Products On Sale",
"bannerImage": "sale/topsellerPromo.jpg"
},
"localized": true,
"visible": true,
"custom": {
"thumbnail_full": "http://static.myshop.com/sale/topsellerPromo.jpg"
},
"designMetadata": {
"id": "commerce_assets.banner",
"name": "Banner Component",
"archType": "headless"
}
}
]
},
{
"id": "main",
"components": [
{
"id": "be1f331b92d8ad7e38e440e35d",
"typeId": "commerce_assets.carousel",
"fragment": false,
"embedded": false,
"contentLinkUuid": "f0a2c4e6b8d0f2a4c6e8b0d2f4",
"data": {
"title": "Topseller",
"category": "topseller"
},
"localized": true,
"visible": true,
"custom": {
"detailUrl": "www.myshop.com/topseller"
},
"regions": [
{
"id": "tiles",
"components": [
{
"id": "45af07459684e6db78990c5d05",
"typeId": "commerce_assets.productTile",
"fragment": false,
"embedded": false,
"contentLinkUuid": "5d7f1a3b5c7e9f0a2c4d6e8f0a2",
"data": {
"product": "iphone6"
},
"localized": false,
"visible": true
},
{
"id": "df6e33766d90e7e205d109aa2f",
"typeId": "commerce_assets.productTile",
"fragment": false,
"embedded": false,
"contentLinkUuid": "e8b0d2f4a6c8e0b2d4f6a8c0e2b",
"data": {
"product": "iphone7"
},
"localized": true,
"visible": false
}
]
}
]
}
]
}
]
}
```
* **400** Invalid Query Parameter
Media type: `application/problem+json`. Schema: `ErrorResponse`.
_Example: AspectAttributeInvalid_
```
{
"title": "Aspect Attribute Invalid",
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/aspect-attribute-invalid",
"detail": "Aspect attribute value \"5555\" does not fulfill its respective definition {\"id\" : \"foobar\", \"type\" : \"string\",\"required\" : \"false\"}"
}
```
* **401** Unauthorized Access
Media type: `application/problem+json`. Schema: `ErrorResponse`.
* **404** Requested Page Not Found
Media type: `application/problem+json`. Schema: `ErrorResponse`.
_Example: PageNotFound_
```
{
"title": "Page Not Found",
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/page-not-found",
"detail": "No visible page with ID 'homepage' was found in site 'RefArch'."
}
```
### GET Get a component by ID.
`GET /organizations/{organizationId}/components/{componentId}`
Operation ID: `getComponent`. Security: ShopperToken (sfcc.shopper-experience, sfcc.shopper-experience.pages); ShopperClientContextToken (sfcc.shopper-experience, sfcc.shopper-experience.pages).
Get a Page Designer component by its unique identifier. The results apply the visibility rules for the component, such as personalization or scheduled visibility.
**Important**:
* 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 component.
#### 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
```
* `componentId` (path, string, required) Identifier for the requested component.
Maximum length: 256. Example: `be1f331b92d8ad7e38e440e35d`.
* `parameters` (query, string) A free-form definition of parameters that influences the page rendering according to its implementation. This parameter must not contain more than 256 characters after URL decoding.
Maximum length: 256. Example: `refine=color,size;currency=USD;showNavigation=false`.
* `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** Success.
Media type: `application/json`. Schema: `Component`.
_Example: Component_
```
{
"id": "be1f331b92d8ad7e38e440e35d",
"typeId": "commerce_assets.carousel",
"name": "Topseller Carousel",
"fragment": false,
"embedded": false,
"contentLinkUuid": "f0a2c4e6b8d0f2a4c6e8b0d2f4",
"data": {
"title": "Topseller",
"category": "topseller"
},
"localized": true,
"visible": true,
"custom": {
"detailUrl": "www.myshop.com/topseller"
},
"designMetadata": {
"id": "commerce_assets.carousel",
"name": "Carousel Component",
"archType": "headless"
},
"regions": [
{
"id": "tiles",
"components": [
{
"id": "45af07459684e6db78990c5d05",
"typeId": "commerce_assets.productTile",
"name": "iPhone 6 Tile",
"fragment": false,
"embedded": false,
"contentLinkUuid": "5d7f1a3b5c7e9f0a2c4d6e8f0a2",
"data": {
"product": "iphone6"
},
"localized": false,
"visible": true
},
{
"id": "df6e33766d90e7e205d109aa2f",
"typeId": "commerce_assets.productTile",
"name": "iPhone 7 Tile",
"fragment": false,
"embedded": false,
"contentLinkUuid": "e8b0d2f4a6c8e0b2d4f6a8c0e2b",
"data": {
"product": "iphone7"
},
"localized": true,
"visible": true
}
]
}
]
}
```
* **400** Invalid Parameter
Media type: `application/problem+json`. Schema: `ErrorResponse`.
_Example: ComponentBadRequest_
```
{
"title": "Bad Request",
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
"detail": "The provided 'componentId' is invalid or missing required query parameter 'siteId'."
}
```
* **401** Unauthorized Access
Media type: `application/problem+json`. Schema: `ErrorResponse`.
* **404** Component Not Found
Media type: `application/problem+json`. Schema: `ErrorResponse`.
_Example: ComponentNotFound_
```
{
"title": "Component Not Found",
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/component-not-found",
"detail": "No visible component with ID 'rfdvj4ojtltljw3' was found in site 'RefArch'."
}
```
* **500** Internal Server Error
Media type: `application/problem+json`. Schema: `ErrorResponse`.
_Example: ComponentInternalError_
```
{
"title": "Internal Server Error",
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/internal-server-error",
"detail": "An unexpected error occurred while processing the request."
}
```
### GET Get a content asset by ID.
`GET /organizations/{organizationId}/contents/{id}`
Operation ID: `getContent`. Security: ShopperToken (sfcc.shopper-experience.contents); ShopperClientContextToken (sfcc.shopper-experience.contents).
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.
#### 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
```
* `id` (path, ContentId, required) Identifier for the requested content asset.
* `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** Success.
Media type: `application/json`. Schema: `Content`.
_Example: Content_
```
{
"id": "homepage-banner",
"name": "Homepage Banner",
"description": "Main promotional banner for the homepage",
"pageTitle": "Homepage Banner - My Shop",
"pageDescription": "Discover amazing products at great prices",
"pageKeywords": "banner, promotion, homepage"
}
```
* **404** Content Asset Not Found
Media type: `application/problem+json`. Schema: `ErrorResponse`.
_Example: ContentNotFound_
```
{
"title": "Content Asset Not Found",
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/content-not-found",
"detail": "No visible content asset with ID 'homepage-banner' was found in site 'RefArch'."
}
```
### GET Get multiple content assets.
`GET /organizations/{organizationId}/contents`
Operation ID: `getMultipleContent`. Security: ShopperToken (sfcc.shopper-experience.contents); ShopperClientContextToken (sfcc.shopper-experience.contents).
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.
#### 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, array of ContentId, required, style: form, explode: false) Comma-separated list of content asset identifiers to retrieve.
Minimum items: 1. Maximum items: 50.
_Example_
```
homepage-banner,footer-content,sidebar-promo
```
_Example_
```
[
"homepage-banner",
"footer-content",
"sidebar-promo"
]
```
* `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** Success.
Media type: `application/json`. Schema: `ContentResult`.
_Example: ContentResult_
```
{
"data": [
{
"id": "homepage-banner",
"name": "Homepage Banner",
"description": "Main promotional banner for the homepage",
"pageTitle": "Homepage Banner - My Shop",
"pageDescription": "Discover amazing products at great prices",
"pageKeywords": "banner, promotion, homepage"
},
{
"id": "footer-content",
"name": "Footer Content",
"description": "Footer information and links",
"pageTitle": "Footer - My Shop",
"pageDescription": "Footer content with links and copyright information",
"pageKeywords": "footer, links, copyright"
}
],
"total": 2,
"limit": 2
}
```
* **400** Bad Request
Media type: `application/problem+json`. Schema: `ErrorResponse`.
_Example: GetContentsBadRequest_
```
{
"title": "Bad Request",
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
"detail": "'ids' violates the value constraint. The expected value is between '(0..50)'.",
"parameter": "ids",
"expected": "(0..50)"
}
```
### GET Search for content assets.
`GET /organizations/{organizationId}/content-search`
Operation ID: `searchContent`. Security: ShopperToken (sfcc.shopper-experience.contents); ShopperClientContextToken (sfcc.shopper-experience.contents).
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.
#### 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
```
* `q` (query, string) The query phrase to search for content assets. For example, to search for content with "banner", type q=banner.
Minimum length: 1. Maximum length: 50. Example: `banner`.
* `refine` (query, string, style: form, explode: true)
Parameter that represents a refinement attribute/value(s) pair. Refinement attribute ID and value(s) are separated by '='. Multiple values are supported by a subset of refinement attributes and can be provided by separating them using a pipe (URL encoded = "|"). Value ranges can be specified like this: refine=foo=(100..500). Multiple refine parameters can be provided by adding an underscore in combination with an integer counter right behind the parameter name and a counter range 1..9. I.e. refine\_1=c\_refinementType=type1|type2|type3.
The following system refinement attribute IDs are supported:
* `fdid`: Allows refinement per single content folder ID. Multiple folder IDs are not supported.
Maximum length: 256. Example: `fdid=homepage-folder`.
* `sort` (query, string, style: form, explode: true)
Parameter that represents a sorting attribute/value(s) pair. Sorting attribute ID and value are separated by '='. The value describes the sort direction. Possible values are 'asc' and 'desc', for ascending or descending sort direction. I.e. sort=c\_myAttribute=desc.
Precondition: You have to select your sorting attributes in Business Manager > YourSite > Search Indexes > Content Index > Sorting Attributes.
Maximum length: 256. Example: `name=asc`.
* `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 50.
Default: `50`. 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** Success.
Media type: `application/json`. Schema: `ContentSearchResult`.
_Example: ContentSearchResult_
```
{
"query": "banner",
"hits": [
{
"id": "homepage-banner",
"name": "Homepage Banner",
"description": "Main promotional banner for the homepage",
"pageTitle": "Homepage Banner - My Shop",
"pageDescription": "Discover amazing products at great prices",
"pageKeywords": "banner, promotion, homepage"
},
{
"id": "sidebar-banner",
"name": "Sidebar Banner",
"description": "Promotional banner for the sidebar",
"pageTitle": "Sidebar Banner - My Shop",
"pageDescription": "Check out our special offers",
"pageKeywords": "banner, sidebar, promotion"
}
],
"selectedRefinements": {
"fdid": "homepage-folder",
"c_contentType": "banner"
},
"refinements": [
{
"attributeId": "c_contentType",
"label": "Content Type",
"values": [
{
"value": "banner",
"label": "Banner",
"hitCount": 15
},
{
"value": "text",
"label": "Text Content",
"hitCount": 8
}
]
},
{
"attributeId": "fdid",
"label": "Content Folder",
"values": [
{
"value": "homepage-folder",
"label": "Homepage",
"hitCount": 5
},
{
"value": "promotions-folder",
"label": "Promotions",
"hitCount": 10
}
]
}
],
"total": 2,
"limit": 25,
"offset": 0
}
```
* **400** Bad Request
Media type: `application/problem+json`. Schema: `ErrorResponse`.
_Example: ContentSearchBadRequest_
```
{
"title": "Bad Request",
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
"detail": "Invalid refinement parameter format. Expected format: 'attribute=value'.",
"parameter": "refine"
}
```
### GET Get content folder
`GET /organizations/{organizationId}/folders/{id}`
Operation ID: `getContentFolder`. Security: ShopperToken (sfcc.shopper-experience.folders); ShopperClientContextToken (sfcc.shopper-experience.folders).
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.
#### 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
```
* `id` (path, FolderId, required) Identifier for the requested content folder.
* `levels` (query, integer) Specifies how many levels of nested subfolders you want the server to return. The default value is 1. Valid values are 0, 1, or 2.
Default: `1`. Minimum: 0. Maximum: 2. Example: `1`.
* `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** Success
Media type: `application/json`. Schema: `ContentFolder`.
_Example: ContentFolder_
```
{
"id": "homepage-folder",
"parentFolderId": "root-folder",
"name": "Homepage Folder",
"description": "Folder containing homepage content assets",
"pageTitle": "Homepage Folder - My Store",
"pageDescription": "SEO description for homepage folder",
"pageKeywords": "homepage, main, landing",
"folders": [
{
"id": "hero-section",
"parentFolderId": "homepage-folder",
"name": "Hero Section",
"description": "Hero section content folder",
"folders": []
},
{
"id": "featured-products",
"parentFolderId": "homepage-folder",
"name": "Featured Products",
"description": "Featured products content folder",
"folders": []
}
],
"c_customAttribute": "customValue"
}
```
* **400** Bad Request
Media type: `application/problem+json`. Schema: `ErrorResponse`.
_Example: InvalidLevelsParameter_
```
{
"title": "Bad Request",
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
"detail": "'levels' violates the value constraint. The expected value is between '(0..2)'."
}
```
* **401** Your access token is invalid or expired and can’t be used to identify a user.
Media type: `application/problem+json`. Schema: `ErrorResponse`.
_Example: UnauthorizedExample_
```
{
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
"title": "Unauthorized",
"detail": "Unauthorized request"
}
```
* **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
Media type: `application/problem+json`. Schema: `ErrorResponse`.
_Example: ForbiddenExample_
```
{
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
"title": "Forbidden",
"detail": "Access to requested resource forbidden"
}
```
* **404** Folder Not Found
Media type: `application/problem+json`. Schema: `ErrorResponse`.
_Example: ContentFolderNotFound_
```
{
"title": "Folder Not Found",
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/folder-not-found",
"detail": "No online content folder with ID 'non-existent-folder' for site 'RefArch' could be found."
}
```
### GET Get multiple content folders
`GET /organizations/{organizationId}/folders`
Operation ID: `getContentFolders`. Security: ShopperToken (sfcc.shopper-experience.folders); ShopperClientContextToken (sfcc.shopper-experience.folders).
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.
#### 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, array of object, required, style: form, explode: false) Comma-separated list of content folder identifiers.
Minimum items: 1. Maximum items: 50.
_Example_
```
homepage-folder,category-folder,product-folder
```
_Example_
```
[
"homepage-folder",
"category-folder",
"product-folder"
]
```
* `levels` (query, integer) Specifies how many levels of nested subfolders you want the server to return. The default value is 1. Valid values are 0, 1, or 2.
Default: `1`. Minimum: 0. Maximum: 2. Example: `1`.
* `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** Success
Media type: `application/json`. Schema: `ContentFolderResult`.
_Example: ContentFolderResult_
```
{
"limit": 2,
"total": 10,
"data": [
{
"id": "homepage-folder",
"parentFolderId": "root-folder",
"name": "Homepage Folder",
"description": "Folder containing homepage content assets",
"pageTitle": "Homepage Folder - My Store",
"pageDescription": "SEO description for homepage folder",
"pageKeywords": "homepage, main, landing",
"folders": [
{
"id": "hero-section",
"parentFolderId": "homepage-folder",
"name": "Hero Section",
"description": "Hero section content folder",
"folders": []
},
{
"id": "featured-products",
"parentFolderId": "homepage-folder",
"name": "Featured Products",
"description": "Featured products content folder",
"folders": []
}
],
"c_customAttribute": "customValue"
},
{
"id": "category-folder",
"parentFolderId": "root-folder",
"name": "Category Folder",
"description": "Folder containing category content assets",
"pageTitle": "Category Folder - My Store",
"pageDescription": "SEO description for category folder",
"pageKeywords": "category, products, listing",
"folders": []
}
]
}
```
* **400** Bad Request
Media type: `application/problem+json`. Schema: `ErrorResponse`.
_Example InvalidLevelsParameter: same as GET /organizations/{organizationId}/folders/{id} 400 response._
* **401** Your access token is invalid or expired and can’t be used to identify a user.
Media type: `application/problem+json`. Schema: `ErrorResponse`.
_Example: UnauthorizedExample_
```
{
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
"title": "Unauthorized",
"detail": "Unauthorized request"
}
```
* **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
Media type: `application/problem+json`. Schema: `ErrorResponse`.
_Example: ForbiddenExample_
```
{
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
"title": "Forbidden",
"detail": "Access to requested resource forbidden"
}
```
### POST Resolve qualifiers for customer groups, campaign promotions, and data binding contexts.
`POST /organizations/{organizationId}/qualifiers/resolve`
Operation ID: `resolveQualifiers`. Security: ShopperToken (sfcc.shopper-experience.qualifiers); ShopperClientContextToken (sfcc.shopper-experience.qualifiers).
Resolves a list of customer groups, campaigns, promotions, and data bindings for the given user.
The endpoint takes each value and determines whether the user is active for the item:
* Customer groups are verified against the user's qualification via the EffectiveContext.
* Campaign qualifiers are checked to determine if the user is applicable for each campaign and promotion.
* Data bindings are resolved by fetching the requested records from their respective data providers.
Returns a boolean result for each provided qualifier and resolved data binding objects grouped by provider type and record identifier. If a qualifier cannot be validated, `false` is returned for that item. If a data binding cannot be resolved, it is omitted from the response.
#### 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
```
* `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`.
* `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.
#### Request body (required)
Media type: `application/json`. Schema: `QualifierResolveRequest`.
_Example: QualifierResolveRequest_
```
{
"customerGroups": [
"VIP"
],
"campaignQualifiers": [
{
"campaignId": "my-campaign",
"promotionId": "my-promotion"
},
{
"campaignId": "winter-promo"
}
],
"dataBindings": [
{
"type": "content_asset",
"id": "homepage-banner"
}
]
}
```
#### Responses
* **200** Success. All qualifiers have been resolved.
Media type: `application/json`. Schema: `QualifierResolveResponse`.
_Example: QualifierResolveResponse_
```
{
"customerGroups": {
"VIP": true
},
"campaignQualifiers": {
"my-campaign": {
"my-promotion": false
}
},
"campaigns": {
"winter-promo": false
},
"dataBindings": {
"content_asset": {
"homepage-banner": {
"title": "Winter Sale",
"body": "Shop our winter collection
",
"showCountdown": true,
"endDate": "2026-03-31T23:59:59Z"
}
}
}
}
```
* **400** Bad Request
Media type: `application/problem+json`. Schema: `ErrorResponse`.
_Example: QualifierResolveBadRequest_
```
{
"title": "Bad Request",
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
"detail": "Invalid request body. The 'campaignQualifiers' array contains entries missing the required field 'campaignId'."
}
```
_Example: QualifierResolveTooManyItems_
```
{
"title": "Bad Request",
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
"detail": "'campaignQualifiers' violates the value constraint. The expected value is between '(0..50)'."
}
```
_Example: QualifierResolveInvalidIdentifier_
```
{
"title": "Bad Request",
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
"detail": "Invalid request body. The 'customerGroups' array contains empty or invalid identifiers."
}
```
_Example: QualifierResolveInvalidDataBindingType_
```
{
"title": "Bad Request",
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
"detail": "Invalid request body. The 'dataBindings' array contains entries missing the required 'type' field."
}
```
_Example: QualifierResolveInvalidDataBindingId_
```
{
"title": "Bad Request",
"type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
"detail": "Invalid request body. The 'dataBindings' array contains entries missing the required 'id' field."
}
```
## 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`.
### PageResult
* `data` (_array of Page_, required)
Data
List of pages.
### 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`.
### Page
* `id` (_string_, required)
ID
Page identifier.
Maximum length: 256. Example: `homepage`.
* `typeId` (_string_, required)
Page Type ID
Page type identifier.
Maximum length: 256. Example: `storePage`.
* `aspectTypeId` (_string_)
Aspect Type ID
The aspect type assigned to the page.
Maximum length: 256. Example: `pdpAspect`.
* `name` (_string_)
Page Name
Display name of the page.
Maximum length: 4000. Example: `Homepage`.
* `description` (_string_)
Page Description
Description of the page.
Maximum length: 4000. Example: `Home page of the storefront.`.
* `pageTitle` (_string_)
SEO Title
The SEO title of the page.
Maximum length: 4000. Example: `Homepage - My Shop`.
* `pageDescription` (_string_)
SEO Description
The SEO description of the page.
Maximum length: 4000. Example: `Get started shopping`.
* `pageKeywords` (_string_)
SEO Keywords
The SEO keywords of the page.
Maximum length: 4000. Example: `fashion, my shop`.
* `data` (_object_)
Page Data
The configuration data assigned to the page.
_Example_
```
{
"thumbnail": "myshop.jpg"
}
```
* `custom` (_object_)
Custom Page Data
Any custom data added by the custom code for the page type.
_Example_
```
{
"thumbnail_full": "http://static.myshop.com/myshop.jpg"
}
```
* `visible` (_boolean_)
Visibility
Whether the page is visible based on the current visiblity rules and context.
Example: `true`.
* `localized` (_boolean_)
Localized
Whether the page has been localized with content in the current locale. If false, the page content will fallback to the default locale.
Example: `true`.
* `designMetadata` (_object_)
Design Metadata
Design metadata of the page. This includes information about the page type definition needed by the page designer for design-time functionality.
_Example_
```
{
"id": "storePage",
"name": "Store Page",
"archType": "headless"
}
```
* `regions` (_array of Region_)
Regions
The regions (and their assigned components) for the page.
_Example_
```
[
{
"id": "header",
"components": [
{
"id": "iofwj38fhw3f",
"typeId": "commerce_assets.banner",
"data": {
"title": "Products On Sale",
"bannerImage": "sale/topsellerPromo.jpg"
},
"custom": {
"thumbnail_full": "http://static.myshop.com/sale/topsellerPromo.jpg"
}
}
]
},
{
"id": "main",
"components": [
{
"id": "rfdvj4ojtltljw3",
"typeId": "commerce_assets.carousel",
"data": {
"title": "Topseller",
"category": "topseller"
},
"custom": {
"detailUrl": "www.myshop.com/topseller"
},
"regions": [
{
"id": "tiles",
"components": [
{
"id": "w3reö9wsjf3",
"typeId": "commerce_assets.productTile",
"data": {
"product": "iphone6"
}
},
{
"id": "cgn8d4ngdl4n",
"typeId": "commerce_assets.productTile",
"data": {
"product": "iphone7"
}
}
]
}
]
}
]
},
{
"id": "footer",
"components": []
}
]
```
### Component
* `id` (_string_, required)
ID
Component identifier.
Maximum length: 256. Example: `rfdvj4ojtltljw3`.
* `typeId` (_string_, required)
Component Type ID
Component type identifier.
Maximum length: 256. Example: `commerce_assets.carousel`.
* `name` (_string_)
Component Name
Display name of the component.
Maximum length: 256. Example: `Topseller Carousel`.
* `fragment` (_boolean_)
Fragment
Indicates whether the component is a fragment. True if the component is a fragment, otherwise false.
Example: `false`.
* `embedded` (_boolean_)
Embedded
Indicates whether the component is embedded in another component. True if the component is embedded, otherwise false.
Example: `false`.
* `contentLinkUuid` (_string_)
Content Link UUID
Represents a globally unique identifier for every instance of a content component (or fragment) rendered on a page.
Maximum length: 256. Example: `0e1f329d4ac66ff2c3bbf70301`.
* `data` (_object_)
Component Data
The configuration data assigned to the component.
_Example_
```
{
"title": "Topseller",
"category": "topseller"
}
```
* `localized` (_boolean_)
Localized
Whether the component has been localized with content in the current locale. If false, the components content will fallback to the default locale.
Example: `true`.
* `visible` (_boolean_)
Visibility
Whether the component is visible based on the current visiblity rules and context.
Example: `true`.
* `custom` (_object_)
Custom Component Data
Any custom data added by the custom code for this component.
_Example_
```
{
"detailUrl": "www.myshop.com/topseller"
}
```
* `designMetadata` (_object_)
Design Metadata
Design metadata of the component. This includes information about the component type definition needed by the page designer for design-time functionality.
_Example_
```
{
"id": "commerce_assets.carousel",
"name": "Carousel Component",
"archType": "headless"
}
```
* `regions` (_array of Region_)
Regions
The regions (and their assigned components) for the component.
_Example_
```
[
{
"id": "tiles",
"components": [
{
"id": "w3reö9wsjf3",
"typeId": "commerce_assets.productTile",
"data": {
"product": "iphone6"
}
},
{
"id": "cgn8d4ngdl4n",
"typeId": "commerce_assets.productTile",
"data": {
"product": "iphone7"
}
}
]
}
]
```
### ContentId
The id of the content asset.
Type: `string`.
Minimum length: 1. Maximum length: 256. Example: `homepage-banner`.
### Content
* `id` (_object_, required) ID
Includes all fields of `ContentId`.
* `name` (_string_)
Name
The localized content asset name.
Maximum length: 4000. Example: `Homepage Banner`.
* `description` (_string_)
Description
The localized content asset description.
Maximum length: 4000. Example: `Main banner displayed on the homepage`.
* `pageDescription` (_string_)
Page Description
The localized content asset page description for SEO.
Maximum length: 4000. Example: `Discover our latest products and offers`.
* `pageKeywords` (_string_)
Page Keywords
The localized content asset page keywords for SEO.
Maximum length: 4000. Example: `products, offers, sale, fashion`.
* `pageTitle` (_string_)
Page Title
The localized content asset page title for SEO
Maximum length: 4000. Example: `Shop Now - Best Deals`.
Additional properties: `any`.
Additional Property Support
This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.
Example: `c_trackingId`.
### ContentResult
Includes all fields of `ResultBase`.
* `data` (_array of Content_, required)
Data
List of content assets.
### ContentSearchResult
Includes all fields of `PaginatedResultBase`.
* `query` (_string_)
Query
The query String that was searched for.
Maximum length: 256. Example: `banner`.
* `hits` (_array of Content_, required)
Content Hits
The sorted array of search hits. Can be empty.
* `selectedRefinements` (_object_)
Selected Refinements
Map of selected refinement attribute id/value(s) pairs. The sorting order is the same like in request URL.
Additional properties: `string`.
Maximum length: 256. Example: `homepage-folder`.
_Example_
```
{
"fdid": "homepage-folder",
"c_contentType": "banner"
}
```
* `refinements` (_array of ContentSearchRefinement_)
Refinements
The sorted array of search refinements. Can be empty.
### FolderId
Type: `string`.
Maximum length: 256. Example: `homepage-folder`.
### ContentFolder
* `id` (_string_, required)
ID
The id of the content folder.
Maximum length: 256. Example: `homepage-folder`.
* `parentFolderId` (_string_)
Parent Folder ID
The id of the parent content folder.
Maximum length: 256. Example: `root-folder`.
* `name` (_string_)
Name
The localized content folder name.
Maximum length: 4000. Example: `Homepage Folder`.
* `description` (_string_)
Description
The localized content folder description.
Maximum length: 4000. Example: `Folder containing homepage content assets`.
* `pageDescription` (_string_)
Page Description
The localized content folder page description.
Maximum length: 4000. Example: `SEO description for homepage folder`.
* `pageKeywords` (_string_)
Page Keywords
The localized content folder page keywords.
Maximum length: 4000. Example: `homepage, main, landing`.
* `pageTitle` (_string_)
Page Title
The localized content folder page title.
Maximum length: 4000. Example: `Homepage Folder - My Store`.
* `folders` (_array of ContentFolder_)
Folders
The array of content subfolders. This array can be empty.
Additional properties: `any`.
Additional Property Support
This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.
Example: `c_trackingId`.
### ContentFolderResult
Includes all fields of `ResultBase`.
* `data` (_array of ContentFolder_, required)
Data
List of content folders.
### QualifierResolveRequest
Request body for resolving customer group qualifications, campaign promotion eligibility, and data bindings. All fields are optional. An empty body is valid and returns an empty response.
* `customerGroups` (_array of string_)
Customer Groups
List of customer group identifiers to resolve qualification for.
Items: Minimum length: 1. Maximum length: 256. Example: `VIP`. Maximum items: 50.
_Example_
```
[
"VIP"
]
```
* `campaignQualifiers` (_array of CampaignQualifier_)
Campaign Qualifiers
List of campaign qualifiers to resolve. Each qualifier must include a campaignId and may optionally include a promotionId.
Maximum items: 50.
* `dataBindings` (_array of DataBindingRequirement_)
Data Bindings
List of data binding requirements to resolve, each specifying a provider type and record identifier.
Maximum items: 50.
### QualifierResolveResponse
Response containing the resolved qualification results for customer groups, campaign qualifiers, and data bindings.
* `customerGroups` (_object_)
Customer Groups
Map of customer group identifiers to their qualification status. True if the user is qualified, false otherwise.
Additional properties: `boolean`.
Example: `true`.
_Example_
```
{
"VIP": true
}
```
* `campaignQualifiers` (_object_)
Campaign Qualifiers
Map of campaign ID to promotion qualification results. Each value is a map of promotion ID to qualification result. Only contains entries for request qualifiers that included a promotionId.
Additional properties: `object`.
Additional properties: `boolean`.
Example: `false`.
_Example_
```
{
"my-campaign": {
"my-promotion": false
}
}
```
* `campaigns` (_object_)
Campaigns
Map of campaign ID to qualification result for request qualifiers that did not include a promotionId. A value of true means the campaign is active and its scenario rule applies to the shopper context.
Additional properties: `boolean`.
Example: `false`.
_Example_
```
{
"winter-promo": false
}
```
* `dataBindings` (_object_)
Data Bindings
Resolved data binding objects grouped by provider type, then by record identifier. Used by the expression resolver to evaluate attribute expressions.
Additional properties: `object`.
Additional properties: `object`.
_Example_
```
{
"content_asset": {
"homepage-banner": {
"title": "Winter Sale",
"body": "Shop our winter collection
",
"showCountdown": true,
"endDate": "2026-03-31T23:59:59Z"
}
}
}
```
### 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`.
### Region
* `id` (_string_, required)
ID
Region identifier.
Maximum length: 256. Example: `header`.
* `components` (_array of Component_)
Components
The components in the region.
_Example_
```
[
{
"id": "iofwj38fhw3f",
"typeId": "commerce_assets.banner",
"data": {
"title": "Products On Sale",
"bannerImage": "sale/topsellerPromo.jpg"
},
"custom": {
"thumbnail_full": "http://static.myshop.com/sale/topsellerPromo.jpg"
}
}
]
```
### 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)
### 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)
### ContentSearchRefinement
* `attributeId` (_string_, required)
Attribute ID
The ID of the refinement attribute.
Maximum length: 256. Example: `c_contentType`.
* `label` (_string_)
Label
The localized label of the refinement attribute.
Maximum length: 4000. Example: `Content Type`.
* `values` (_array of ContentSearchRefinementValue_)
Values
The array of refinement values.
### CampaignQualifier
A campaign qualifier, optionally scoped to a specific promotion within the campaign. When promotionId is omitted, the qualifier matches if the campaign itself is active and its scenario rule applies.
* `campaignId` (_string_, required)
Campaign ID
The campaign identifier.
Minimum length: 1. Maximum length: 256. Example: `my-campaign`.
* `promotionId` (_string_)
Promotion ID
Optional promotion identifier. When provided, qualification requires both the campaign and the specific promotion-campaign assignment to apply.
Minimum length: 1. Maximum length: 256. Example: `my-promotion`.
### DataBindingRequirement
A data binding requirement specifying a provider type and record identifier to resolve.
* `type` (_string_, required)
Type
The data provider type identifier.
Minimum length: 1. Maximum length: 256. Example: `content_asset`.
* `id` (_string_, required)
ID
The record identifier to resolve from the data provider.
Minimum length: 1. Maximum length: 256. Example: `homepage-banner`.
### 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`.
### ContentSearchRefinementValue
* `label` (_string_)
Label
The localized label of the refinement value.
Maximum length: 4000. Example: `Banner`.
* `value` (_string_, required)
Value
The refinement value.
Maximum length: 256. Example: `banner`.
* `hitCount` (_integer_)
Hit Count
The number of search hits when this refinement value is applied.
Minimum: 0. Example: `5`.