--- schema_version: "1" id: 713fefbbb8b3c7a932bf609c10f1548373cfed9e65cee8aead85803ce2a4ea42 title: Experiences 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/experiences.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/experiences source_site: developer.salesforce.com content_type: documentation content_hash: 78613b67a096cdf15f69cd8805106a31804c73b32b4ec5f5c4146ea047d7a30e products: - B2C Commerce API - Salesforce APIs --- Experiences # Experiences [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/experiences/experiences-oas-v1-public.yaml) ## API Overview The Experiences API provides a unified endpoint for creating and updating Page Designer pages in B2C Commerce Cloud. Use this API to programmatically create new pages or update existing pages with comprehensive configuration options. ### Authentication & Authorization For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request. You must include `sfcc.experience.rw` in the client ID used to generate the 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) For detailed setup instructions, see [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html). ### Use Cases #### Unified Create/Update Create new pages or update existing Page Designer pages with comprehensive configuration. #### Component configuration Define and configure page components with their associated data. #### Region Setup Set up page regions and assign components to them. #### Custom Properties Create custom attributes using the c\_\* property pattern. #### SEO Support Configure page-level SEO metadata including titles, descriptions, and keywords. ### Usage Guidelines This API is specifically designed for single page creation operations. * The Page ID must be unique within the site. * Newly created pages are in draft status by default. * Existing pages are updated with provided data (partial updates supported). * Page Activation: To make a page active/published, use the Business Manager UI to change the page status from draft to active. * Custom properties (c\_\*) are supported through the open object pattern. * All text fields support localization through the Commerce Cloud localization framework. * This API supports both create and update operations using PUT semantics. ### Related APIs * [Shopper Experience](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-experience?meta=Summary) — Retrieve Page Designer pages and content for shoppers. **Version:** 1.4.0 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/experience/experiences/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 * `AmOAuth2` (oauth2) OAuth 2.0 authentication for admin operations * OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/oauth2/token) * Scope sfcc.experiences: Read-only access to merchandiser experiences * Scope sfcc.experiences.rw: Read and write access to merchandiser experiences ## Operations ### PUT Create or update a Page Designer page. `PUT /organizations/{organizationId}/pages/{pageId}` Operation ID: `createOrUpdatePage`. Security: AmOAuth2 (sfcc.experiences.rw). This API is designed specifically for single page creation or updating existing pages with all necessary metadata, regions, and components. **Important**: * This is an admin-only operation requiring appropriate permissions. * By default, the created page is in draft status. * Page ID in URL must match the page ID in the request body. * All required fields must be provided in the request body. * This API supports both create and update operations using PUT semantics. #### 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 ``` * `pageId` (path, string, required) Identifier for the requested page. Maximum length: 256. Example: `homepage`. * `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 ``` #### Request body (required) Media type: `application/json`. Schema: `PageRequest`. _Example: CreatePageRequest_ Example request to create a new page ``` { "id": "new-homepage", "typeId": "storePage", "aspectTypeId": "pdpAspect", "name": "New Homepage", "description": "New home page for the storefront", "pageTitle": "New Homepage - My Shop", "pageDescription": "Welcome to our new homepage", "pageKeywords": "homepage, fashion, my shop", "thumbnail": "new-homepage.jpg", "data": { "site_map_priority": 0.8, "layout": "default" }, "regions": [ { "id": "header", "components": [ { "id": "welcome-banner", "typeId": "commerce_assets.banner", "data": { "title": "Welcome to Our New Store", "bannerImage": "welcome-banner.jpg" } } ] }, { "id": "main", "components": [ { "id": "featured-products", "typeId": "commerce_assets.carousel", "data": { "title": "Featured Products", "category": "featured" } } ] }, { "id": "footer", "components": [] } ] } ``` _Example: UpdatePageRequest_ Example request to update an existing page ``` { "id": "new-homepage", "typeId": "storePage", "name": "Updated Homepage", "description": "Updated home page for the storefront", "pageTitle": "Updated Homepage - My Shop", "pageDescription": "Welcome to our updated homepage", "data": { "thumbnail": "updated-homepage.jpg", "priority": 1 }, "regions": [ { "id": "header", "components": [ { "id": "welcome-banner", "typeId": "commerce_assets.banner", "data": { "title": "Updated Welcome Banner", "bannerImage": "updated-welcome-banner.jpg" } } ] } ] } ``` #### Responses * **200** Page updated successfully Media type: `application/json`. Schema: `Page`. _Example: UpdatedPage_ Example response for a successfully updated page ``` { "id": "new-homepage", "typeId": "storePage", "aspectTypeId": "pdpAspect", "name": "Updated Homepage", "description": "Updated home page for the storefront", "pageTitle": "Updated Homepage - My Shop", "pageDescription": "Welcome to our updated homepage", "data": { "thumbnail": "updated-homepage.jpg", "priority": 1 }, "custom": { "thumbnail_full": "http://static.myshop.com/updated-homepage.jpg" }, "regions": [ { "id": "header", "components": [ { "id": "welcome-banner", "typeId": "commerce_assets.banner", "data": { "title": "Updated Welcome to Our New Store", "bannerImage": "updated-welcome-banner.jpg" }, "custom": { "banner_url": "http://static.myshop.com/updated-welcome-banner.jpg" } } ] } ], "creationDate": "2024-01-15T10:30:00.000Z", "lastModified": "2024-01-15T11:00:00.000Z", "online": true } ``` * **201** Page created successfully Media type: `application/json`. Schema: `Page`. _Example: CreatedPage_ Example response for a successfully created page ``` { "id": "new-homepage", "typeId": "storePage", "aspectTypeId": "pdpAspect", "name": "New Homepage", "description": "New home page for the storefront", "pageTitle": "New Homepage - My Shop", "pageDescription": "Welcome to our new homepage", "pageKeywords": "homepage, fashion, my shop", "thumbnail": "new-homepage.jpg", "data": { "site_map_priority": 0.8, "layout": "default" }, "custom": { "thumbnail_full": "http://static.myshop.com/new-homepage.jpg" }, "regions": [ { "id": "header", "components": [ { "id": "welcome-banner", "typeId": "commerce_assets.banner", "data": { "title": "Welcome to Our New Store", "bannerImage": "welcome-banner.jpg" }, "custom": { "banner_url": "http://static.myshop.com/welcome-banner.jpg" } } ] }, { "id": "main", "components": [ { "id": "featured-products", "typeId": "commerce_assets.carousel", "data": { "title": "Featured Products", "category": "featured" }, "custom": { "carousel_url": "http://static.myshop.com/featured" } } ] }, { "id": "footer", "components": [] } ], "creationDate": "2024-01-15T10:30:00.000Z", "lastModified": "2024-01-15T10:30:00.000Z", "online": false } ``` * **400** Invalid page data provided. Media type: `application/json`. Schema: `ErrorResponse`. _Example: InvalidPageData_ Example error response for invalid page data ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "The request body contains invalid page data", "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages", "issues": [ { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/required-field-missing", "detail": "Required field 'id' is missing", "field": "id" } ] } ``` _Example: MissingSiteId_ Example error response for missing site ID ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "The siteId query parameter is required", "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage", "issues": [ { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/required-parameter-missing", "detail": "The siteId query parameter is required", "field": "siteId" } ] } ``` _Example: PageIdMismatch_ Example error response for page ID mismatch between path and body ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/page-id-mismatch", "title": "Page Id Mismatch", "detail": "The page ID in the request path ('path-id') doesn't match the page ID in the request body ('body-id').", "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/path-id", "issues": [ { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/page-id-mismatch", "detail": "The page ID in the request path ('path-id') doesn't match the page ID in the request body ('body-id').", "pathPageId": "path-id", "bodyPageId": "body-id" } ] } ``` _Example: MissingTypeId_ Example error response for missing typeId field ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "Field 'typeId' cannot be empty", "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage", "issues": [ { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-field-value", "detail": "Field 'typeId' cannot be empty.", "field": "typeId" } ] } ``` _Example: InvalidPageType_ Example error response for invalid page type ID during page creation ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "No page type with ID 'invalidPageType' was found in site 'RefArch'.", "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage", "issues": [ { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-field-value", "detail": "No page type with ID 'invalidPageType' was found in site 'RefArch'.", "field": "typeId", "pageTypeId": "invalidPageType", "site": "RefArch" } ] } ``` _Example: InvalidPageId_ Example error response for invalid page ID format ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/content-id-invalid", "title": "Content Id Invalid", "detail": "The ID 'test page' is invalid. The ID can't have leading or trailing whitespaces. It can only contain alphanumeric characters and the following special characters: _-~:[]@!'*,;=", "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/test page", "issues": [ { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/content-id-invalid", "detail": "The ID 'test page' is invalid. The ID can't have leading or trailing whitespaces. It can only contain alphanumeric characters and the following special characters: _-~:[]@!'*,;=", "id": "test page", "field": "id" } ] } ``` _Example: UnsupportedAspectType_ Example error response for unsupported aspect type ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unsupported-aspect-type", "title": "Unsupported Aspect Type", "detail": "The aspect type 'invalidAspectType' isn't supported for page type 'storePage'.", "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage", "issues": [ { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unsupported-aspect-type", "detail": "The aspect type 'invalidAspectType' isn't supported for page type 'storePage'.", "aspectType": "invalidAspectType", "pageType": "storePage", "field": "aspectTypeId" } ] } ``` _Example: InvalidCustomDataFormat_ Example error response for invalid custom data format ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "Field 'data' must be an object", "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage", "issues": [ { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-field-value", "detail": "Field 'data' must be an object", "field": "data" } ] } ``` _Example: InvalidVisibilityRule_ Example error response for invalid visibility rule format ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "Field 'customerGroups' must be an array/list, but was: String", "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage", "issues": [ { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-field-value", "detail": "Field 'customerGroups' must be an array/list, but was: String", "field": "data.visibilityRule.customerGroups" } ] } ``` * **404** The requested resource was not found. This can occur when: * The specified site ID does not exist. * An existing page's page type is missing or invalid. Media type: `application/json`. Schema: `ErrorResponse`. _Example: SiteNotFound_ Example error response for site not found ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-found", "title": "Not Found", "detail": "The specified site does not exist", "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages", "issues": [ { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found", "detail": "Site with ID 'invalid-site' does not exist", "field": "siteId" } ] } ``` _Example: PageTypeNotFound_ Example error response for page type not found when retrieving an existing page. ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/page-type-not-found", "title": "Page Type Not Found", "detail": "No page type with ID 'invalidPageType' was found for page 'test-page' in site 'RefArch'.", "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/test-page", "issues": [ { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/page-type-not-found", "detail": "No page type with ID 'invalidPageType' was found for page 'test-page' in site 'RefArch'.", "pageTypeId": "invalidPageType", "pageId": "test-page", "site": "RefArch" } ] } ``` * **409** Page ID mismatch or validation error. Media type: `application/json`. Schema: `ErrorResponse`. _Example: PageIdConflict_ Example error response for page ID conflict ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/content-id-already-in-use", "title": "Conflict", "detail": "A Page with the specified ID already exists.", "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage", "issues": [ { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/content-id-already-in-use", "detail": "Page with ID 'new-homepage' already exists in the site.", "field": "id" } ] } ``` ### GET Get a content folder `GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId}` Operation ID: `getContentFolder`. Security: AmOAuth2 (sfcc.experiences.rw). Retrieves detailed information about a specific content folder within a library. **Important**: * This is an admin-only operation requiring appropriate permissions. * The folder must exist in the specified library. * Returns localized content if available. #### 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 ``` * `libraryId` (path, string, required) Identifier for the content library. Maximum length: 256. Example: `SiteLibrary`. * `folderId` (path, string, required) Identifier for the content folder. Maximum length: 256. Example: `seasonal-content`. #### Responses * **200** Content folder retrieved successfully Media type: `application/json`. Schema: `ContentFolder`. _Example: RetrievedFolder_ Example response for a successfully retrieved content folder ``` { "id": "seasonal-content", "description": { "default": "Localized seasonal folder (Default)" }, "name": { "default": "Localized folder (Default)" }, "online": true, "parentFolderId": "root", "creationDate": "2024-01-15T10:30:00.000Z", "lastModified": "2024-01-15T11:00:00.000Z" } ``` * **404** The requested resource was not found. This can occur when: * The specified library does not exist. * The specified folder does not exist in the library. Media type: `application/json`. Schema: `ErrorResponse`. _Example: FolderNotFound_ Example error response for folder not found ``` { "title": "Folder Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/folder-not-found", "detail": "No content folder with ID 'unknown-folder' in library 'SiteLibrary' could be found." } ``` _Example: LibraryNotFound_ Example error response for library not found ``` { "title": "Library Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/library-not-found", "detail": "No library with ID 'unknown-library' could be found." } ``` ### PUT Create or update a content folder `PUT /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId}` Operation ID: `createOrUpdateContentFolder`. Security: AmOAuth2 (sfcc.experiences.rw). Creates a new content folder or updates an existing one in the specified library. **Important**: * This is an admin-only operation requiring appropriate permissions. * If the folder doesn't exist, it will be created (201). * If the folder exists, it will be updated (200). * Folder ID in URL must match the folder ID in the request body. * The library must exist before creating folders. #### 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 ``` * `libraryId` (path, string, required) Identifier for the content library. Maximum length: 256. Example: `SiteLibrary`. * `folderId` (path, string, required) Identifier for the content folder. Maximum length: 256. Example: `seasonal-content`. #### Request body (required) Media type: `application/json`. Schema: `ContentFolder`. _Example: CreateFolderRequest_ Example request to create a new content folder ``` { "id": "seasonal-content", "pageDescription": { "default": "Page Descr. (Default)", "en": "Page Descr. (en)", "en-US": "Page Descr. (en_us)" }, "pageKeywords": { "default": "Page Keywords (Default)", "en": "Page Keywords (en)", "en-US": "Page Keywords (en_us)" }, "parentFolderId": "root", "online": false } ``` _Example: UpdateFolderRequest_ Example request to update an existing content folder ``` { "id": "seasonal-content", "name": { "default": "Localized folder (Default)", "en": "Localized folder (en)", "en-US": "Localized folder (en_us)" }, "parentFolderId": "root", "online": true } ``` #### Responses * **200** Content folder updated successfully Media type: `application/json`. Schema: `ContentFolder`. _Example: UpdatedFolder_ Example response for a successfully updated content folder ``` { "id": "seasonal-content", "name": { "default": "Localized folder (Default)", "en": "Localized folder (en)", "en-US": "Localized folder (en_us)" }, "parentFolderId": "root", "online": true, "creationDate": "2024-01-15T10:30:00.000Z", "lastModified": "2024-01-15T11:00:00.000Z" } ``` * **201** Content folder created successfully Media type: `application/json`. Schema: `ContentFolder`. _Example: CreatedFolder_ Example response for a successfully created content folder ``` { "id": "seasonal-content", "pageDescription": { "default": "Page Descr. (Default)", "en": "Page Descr. (en)", "en-US": "Page Descr. (en_us)" }, "pageKeywords": { "default": "Page Keywords (Default)", "en": "Page Keywords (en)", "en-US": "Page Keywords (en_us)" }, "parentFolderId": "root", "online": false, "creationDate": "2024-01-15T10:30:00.000Z", "lastModified": "2024-01-15T10:30:00.000Z" } ``` * **400** Invalid folder data provided. Media type: `application/json`. Schema: `ErrorResponse`. _Example: ContentIdInvalid_ Example error response for invalid folder ID format ``` { "title": "Content Id Invalid", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/content-id-invalid", "detail": "The ID 'test folder' is invalid. The ID can't have leading or trailing whitespaces. It can only contain alphanumeric characters and the following special characters: _-~:[]@!'*,;=" } ``` * **404** The specified library does not exist. Media type: `application/json`. Schema: `ErrorResponse`. _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found _Example: LibraryNotFound_ Example error response for library not found ### DELETE Delete a content folder `DELETE /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId}` Operation ID: `deleteContentFolder`. Security: AmOAuth2 (sfcc.experiences.rw). Deletes a content folder from the specified library. **Important**: * This is an admin-only operation requiring appropriate permissions. * The folder must exist to be deleted. * This operation cannot be undone. * Child folders and content may need to be handled separately. #### 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 ``` * `libraryId` (path, string, required) Identifier for the content library. Maximum length: 256. Example: `SiteLibrary`. * `folderId` (path, string, required) Identifier for the content folder. Maximum length: 256. Example: `seasonal-content`. #### Responses * **204** Content folder deleted successfully * **404** The requested resource was not found. Media type: `application/json`. Schema: `ErrorResponse`. _Example FolderNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for folder not found _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found _Example: FolderNotFound_ Example error response for folder not found _Example: LibraryNotFound_ Example error response for library not found ### PATCH Partially update a content folder `PATCH /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId}` Operation ID: `patchContentFolder`. Security: AmOAuth2 (sfcc.experiences.rw). Updates specific properties of an existing content folder without replacing the entire resource. **Important**: * This is an admin-only operation requiring appropriate permissions. * Only the properties provided in the request body will be updated. * The folder must already exist. * Useful for updating custom attributes without affecting other properties. #### 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 ``` * `libraryId` (path, string, required) Identifier for the content library. Maximum length: 256. Example: `SiteLibrary`. * `folderId` (path, string, required) Identifier for the content folder. Maximum length: 256. Example: `seasonal-content`. #### Request body (required) Media type: `application/json`. Schema: `ContentFolder`. _Example: PatchFolderRequest_ Example request to partially update a content folder ``` { "id": "winter-content", "name": { "default": "Localized winter content folder (Default)", "en": "Localized winter content folder (en)", "en-US": "Localized winter content folder (en_us)" }, "parentFolderId": "root", "online": false } ``` #### Responses * **200** Content folder updated successfully Media type: `application/json`. Schema: `ContentFolder`. _Example UpdatedFolder: same as PUT /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 200 response._ Example response for a successfully updated content folder _Example: UpdatedFolder_ Example response for a successfully updated content folder * **400** Invalid folder data provided. Media type: `application/json`. Schema: `ErrorResponse`. _Example ContentIdInvalid: same as PUT /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 400 response._ Example error response for invalid folder ID format _Example: ContentIdInvalid_ Example error response for invalid folder ID format * **404** The requested resource was not found. Media type: `application/json`. Schema: `ErrorResponse`. _Example FolderNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for folder not found _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found _Example: FolderNotFound_ Example error response for folder not found _Example: LibraryNotFound_ Example error response for library not found ### GET Get sub-folders of a content folder `GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId}/sub-folders` Operation ID: `getSubFolders`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw). Retrieves a list of sub-folders (child folders) within a specific content folder. **Important**: * This is an admin-only operation requiring appropriate permissions. * Returns only direct children of the specified folder. * Results can be paginated using limit and offset parameters. * Only folders within the specified library are included. #### 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 ``` * `libraryId` (path, string, required) Identifier for the content library. Maximum length: 256. Example: `SiteLibrary`. * `folderId` (path, string, required) Identifier for the content folder. Maximum length: 256. Example: `seasonal-content`. * `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25. Default: `25`. Minimum: 1. Maximum: 200. * `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset. Default: `0`. Minimum: 0. #### Responses * **200** Sub-folders retrieved successfully Media type: `application/json`. Schema: `ContentSubFolderResult`. _Example: SubFoldersResult_ Example response for successfully retrieved sub-folders ``` { "limit": 3, "offset": 3, "total": 30, "hits": [ { "id": "winter-2024", "name": { "default": "Winter 2024 Collection", "en": "Winter 2024 Collection", "en-US": "Winter 2024 Collection" }, "description": { "default": "Content for winter 2024 season", "en": "Content for winter 2024 season" }, "parentFolderId": "seasonal-content", "online": true, "pageTitle": { "default": "Winter 2024", "en": "Winter 2024" }, "pageDescription": { "default": "Explore our winter collection", "en": "Explore our winter collection" }, "pageKeywords": { "default": "winter, 2024, seasonal", "en": "winter, 2024, seasonal" }, "template": "rendering/folder/seasonal", "creationDate": "2024-01-10T09:00:00.000Z", "lastModified": "2024-01-10T09:00:00.000Z" }, { "id": "spring-2024", "name": { "default": "Spring 2024 Collection", "en": "Spring 2024 Collection" }, "description": { "default": "Content for spring 2024 season", "en": "Content for spring 2024 season" }, "parentFolderId": "seasonal-content", "online": false, "pageTitle": { "default": "Spring 2024", "en": "Spring 2024" }, "pageDescription": { "default": "Explore our spring collection", "en": "Explore our spring collection" }, "pageKeywords": { "default": "spring, 2024, seasonal", "en": "spring, 2024, seasonal" }, "template": "rendering/folder/seasonal" }, { "id": "summer-2024", "name": { "default": "Summer 2024 Collection", "en": "Summer 2024 Collection" }, "description": { "default": "Content for summer 2024 season", "en": "Content for summer 2024 season" }, "parentFolderId": "seasonal-content", "online": false, "pageTitle": { "default": "Summer 2024", "en": "Summer 2024" }, "pageDescription": { "default": "Explore our summer collection", "en": "Explore our summer collection" }, "pageKeywords": { "default": "summer, 2024, seasonal", "en": "summer, 2024, seasonal" }, "template": "rendering/folder/seasonal" } ] } ``` * **400** Invalid request parameters provided. Media type: `application/json`. Schema: `ErrorResponse`. _Example: InvalidLimitParameter_ Example error response for invalid limit parameter ``` { "title": "Bad Request", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "detail": "The limit parameter must be between 1 and 200." } ``` * **404** The requested resource was not found. This can occur when: * The specified library does not exist. * The specified parent folder does not exist in the library. Media type: `application/json`. Schema: `ErrorResponse`. _Example FolderNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for folder not found _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found _Example: FolderNotFound_ Example error response for folder not found _Example: LibraryNotFound_ Example error response for library not found ### GET Get a content asset `GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId}` Operation ID: `getContent`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw). Retrieves detailed information about a specific content asset within a library. **Important**: * This is an admin-only operation requiring appropriate permissions. * The content asset must exist in the specified library. * Returns localized content if available. * Content assets can contain rich text, HTML, images, and custom attributes. #### 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 ``` * `libraryId` (path, string, required) Identifier for the content library. Maximum length: 256. Example: `SiteLibrary`. * `contentId` (path, string, required) Identifier for the content asset. Maximum length: 256. Example: `homepage-banner`. #### Responses * **200** Content asset retrieved successfully Media type: `application/json`. Schema: `ContentAsset`. _Example: RetrievedContent_ Example response for a successfully retrieved content asset ``` { "id": "homepage-banner", "name": { "default": "Homepage Banner", "en": "Homepage Banner" }, "description": { "default": "Main promotional banner for the homepage", "en": "Main promotional banner for the homepage" }, "pageDescription": { "default": "Discover amazing products at great prices", "en": "Discover amazing products at great prices" }, "pageKeywords": { "default": "banner, promotion, homepage", "en": "banner, promotion, homepage" }, "pageTitle": { "default": "Homepage Banner - My Shop", "en": "Homepage Banner - My Shop" }, "folderId": "homepage-folder", "online": { "default": true }, "template": "rendering/content/banner" } ``` * **404** The requested resource was not found. This can occur when: * The specified library does not exist. * The specified content asset does not exist in the library. Media type: `application/json`. Schema: `ErrorResponse`. _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found _Example: ContentNotFound_ Example error response for content asset not found ``` { "title": "Content Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/content-not-found", "detail": "No content asset with ID 'unknown-content' in library 'SiteLibrary' was found." } ``` _Example: LibraryNotFound_ Example error response for library not found ### PUT Create or update a content asset `PUT /organizations/{organizationId}/libraries/{libraryId}/content/{contentId}` Operation ID: `createOrUpdateContent`. Security: AmOAuth2 (sfcc.experiences.rw). Creates a new content asset or updates an existing one in the specified library. **Important**: * This is an admin-only operation requiring appropriate permissions. * If the content asset doesn't exist, it will be created (201). * If the content asset exists, it will be updated (200). * Content ID in URL must match the content ID in the request body. * The library must exist before creating content assets. #### 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 ``` * `libraryId` (path, string, required) Identifier for the content library. Maximum length: 256. Example: `SiteLibrary`. * `contentId` (path, string, required) Identifier for the content asset. Maximum length: 256. Example: `homepage-banner`. #### Request body (required) Media type: `application/json`. Schema: `ContentAsset`. _Example: CreateContentRequest_ Example request to create a new content asset ``` { "id": "homepage-banner", "name": { "default": "Homepage Banner", "en": "Homepage Banner", "en-US": "Homepage Banner" }, "description": { "default": "Main promotional banner", "en": "Main promotional banner" }, "pageDescription": { "default": "Discover amazing products", "en": "Discover amazing products" }, "pageKeywords": { "default": "banner, promotion, homepage", "en": "banner, promotion, homepage" }, "pageTitle": { "default": "Homepage Banner - My Shop", "en": "Homepage Banner - My Shop" }, "folderId": "homepage-folder", "online": { "default": true }, "template": "rendering/content/banner" } ``` _Example: UpdateContentRequest_ Example request to update an existing content asset ``` { "id": "homepage-banner", "name": { "default": "Updated Homepage Banner", "en": "Updated Homepage Banner" }, "description": { "default": "Updated promotional banner", "en": "Updated promotional banner" }, "folderId": "homepage-folder", "online": { "default": true } } ``` #### Responses * **200** Content asset updated successfully Media type: `application/json`. Schema: `ContentAsset`. _Example: UpdatedContent_ Example response for a successfully updated content asset ``` { "id": "homepage-banner", "name": { "default": "Updated Homepage Banner", "en": "Updated Homepage Banner" }, "description": { "default": "Updated promotional banner", "en": "Updated promotional banner" }, "pageTitle": { "default": "Homepage Banner - My Shop", "en": "Homepage Banner - My Shop" }, "folderId": "homepage-folder", "online": { "default": true } } ``` * **201** Content asset created successfully Media type: `application/json`. Schema: `ContentAsset`. _Example: CreatedContent_ Example response for a successfully created content asset ``` { "id": "homepage-banner", "name": { "default": "Homepage Banner", "en": "Homepage Banner" }, "description": { "default": "Main promotional banner", "en": "Main promotional banner" }, "pageDescription": { "default": "Discover amazing products", "en": "Discover amazing products" }, "pageKeywords": { "default": "banner, promotion, homepage", "en": "banner, promotion, homepage" }, "pageTitle": { "default": "Homepage Banner - My Shop", "en": "Homepage Banner - My Shop" }, "folderId": "homepage-folder", "online": { "default": false }, "template": "rendering/content/banner" } ``` * **400** Invalid content data provided. Media type: `application/json`. Schema: `ErrorResponse`. _Example: UnknownSiteId_ Example error response for unknown site id ``` { "title": "Unknown Site Id", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unknown-site-id", "detail": "The site ID 'NotExistingSite' is unknown." } ``` * **404** The specified library does not exist. Media type: `application/json`. Schema: `ErrorResponse`. _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found _Example: LibraryNotFound_ Example error response for library not found ### DELETE Delete a content asset `DELETE /organizations/{organizationId}/libraries/{libraryId}/content/{contentId}` Operation ID: `deleteContent`. Security: AmOAuth2 (sfcc.experiences.rw). Deletes a content asset from the specified library. **Important**: * This is an admin-only operation requiring appropriate permissions. * The content asset must exist to be deleted. * This operation cannot be undone. * Any references to this content asset in slots or other resources may need to be updated. #### 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 ``` * `libraryId` (path, string, required) Identifier for the content library. Maximum length: 256. Example: `SiteLibrary`. * `contentId` (path, string, required) Identifier for the content asset. Maximum length: 256. Example: `homepage-banner`. #### Responses * **204** Content asset deleted successfully * **404** The requested resource was not found. Media type: `application/json`. Schema: `ErrorResponse`. _Example ContentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 404 response._ Example error response for content asset not found _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found _Example: ContentNotFound_ Example error response for content asset not found _Example: LibraryNotFound_ Example error response for library not found ### PATCH Partially update a content asset `PATCH /organizations/{organizationId}/libraries/{libraryId}/content/{contentId}` Operation ID: `patchContent`. Security: AmOAuth2 (sfcc.experiences.rw). Updates specific properties of an existing content asset without replacing the entire resource. **Important**: * This is an admin-only operation requiring appropriate permissions. * Only the properties provided in the request body will be updated. * The content asset must already exist. * Useful for updating specific attributes without affecting other properties. #### 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 ``` * `libraryId` (path, string, required) Identifier for the content library. Maximum length: 256. Example: `SiteLibrary`. * `contentId` (path, string, required) Identifier for the content asset. Maximum length: 256. Example: `homepage-banner`. #### Request body (required) Media type: `application/json`. Schema: `ContentAsset`. _Example: PatchContentRequest_ Example request to partially update a content asset ``` { "id": "homepage-banner", "online": { "default": true }, "pageTitle": { "default": "Updated Homepage Banner - My Shop", "en": "Updated Homepage Banner - My Shop" } } ``` #### Responses * **200** Content asset updated successfully Media type: `application/json`. Schema: `ContentAsset`. _Example UpdatedContent: same as PUT /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 200 response._ Example response for a successfully updated content asset _Example: UpdatedContent_ Example response for a successfully updated content asset * **404** The requested resource was not found. Media type: `application/json`. Schema: `ErrorResponse`. _Example ContentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 404 response._ Example error response for content asset not found _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found _Example: ContentNotFound_ Example error response for content asset not found _Example: LibraryNotFound_ Example error response for library not found ### GET Get folder information for a content asset `GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId}/folders` Operation ID: `getContentFolders`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw). Retrieves folder information associated with a specific content asset, including the parent folder and folder hierarchy. **Important**: * This is an admin-only operation requiring appropriate permissions. * The content asset must exist in the specified library. * Returns the folder path and hierarchy information. * Useful for understanding where a content asset is located within the library structure. #### 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 ``` * `libraryId` (path, string, required) Identifier for the content library. Maximum length: 256. Example: `SiteLibrary`. * `contentId` (path, string, required) Identifier for the content asset. Maximum length: 256. Example: `homepage-banner`. * `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25. Default: `25`. Minimum: 1. Maximum: 200. * `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset. Default: `0`. Minimum: 0. #### Responses * **200** Folder information retrieved successfully Media type: `application/json`. Schema: `ContentFolderResult`. _Example: ContentFolderInfo_ Example response for content asset folder information ``` { "limit": 4, "offset": 5, "total": 20, "hits": [ { "id": "homepage-folder", "name": { "default": "Homepage Folder", "en": "Homepage Folder" }, "description": { "default": "Folder containing homepage content assets", "en": "Folder containing homepage content assets" }, "parentFolderId": "seasonal-content", "online": true, "pageTitle": { "default": "Homepage Folder - My Store", "en": "Homepage Folder - My Store" }, "pageDescription": { "default": "SEO description for homepage folder" }, "en": "SEO description for homepage folder", "pageKeywords": { "default": "homepage, main, landing", "en": "homepage, main, landing" }, "template": "rendering/folder/homepage" }, { "id": "root", "name": { "default": "Root Folder", "en": "Root Folder" }, "online": true }, { "id": "seasonal-content", "name": { "default": "Seasonal Content", "en": "Seasonal Content" }, "description": { "default": "Folder for seasonal content", "en": "Folder for seasonal content" }, "parentFolderId": "root", "online": true, "pageTitle": { "default": "Seasonal Content - My Store", "en": "Seasonal Content - My Store" }, "template": "rendering/folder/seasonal", "creationDate": "2024-01-05T08:00:00.000Z", "lastModified": "2024-01-05T08:00:00.000Z" }, { "id": "homepage-folder", "name": { "default": "Homepage Folder", "en": "Homepage Folder" }, "description": { "default": "Folder containing homepage content assets", "en": "Folder containing homepage content assets" }, "parentFolderId": "seasonal-content", "online": true, "pageTitle": { "default": "Homepage Folder - My Store", "en": "Homepage Folder - My Store" }, "pageDescription": { "default": "SEO description for homepage folder", "en": "SEO description for homepage folder" }, "pageKeywords": { "default": "homepage, main, landing", "en": "homepage, main, landing" }, "template": "rendering/folder/homepage" } ] } ``` * **404** The requested resource was not found. This can occur when: * The specified library does not exist. * The specified content asset does not exist in the library. Media type: `application/json`. Schema: `ErrorResponse`. _Example ContentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 404 response._ Example error response for content asset not found _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found _Example: ContentNotFound_ Example error response for content asset not found _Example: LibraryNotFound_ Example error response for library not found ### GET Get a folder assignment for a content asset `GET /organizations/{organizationId}/libraries/{libraryId}/folder-assignments/{contentId}/{folderId}` Operation ID: `getFolderAssignment`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw). Retrieves information about the assignment relationship between a content asset and a folder. **Important**: * This is an admin-only operation requiring appropriate permissions. * Returns the assignment details including when it was created and last modified. * The content asset must be assigned to the specified folder. #### 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 ``` * `libraryId` (path, string, required) Identifier for the content library. Maximum length: 256. Example: `SiteLibrary`. * `contentId` (path, string, required) Identifier for the content asset. Maximum length: 256. Example: `homepage-banner`. * `folderId` (path, string, required) Identifier for the content folder. Maximum length: 256. Example: `seasonal-content`. #### Responses * **200** Folder assignment retrieved successfully Media type: `application/json`. Schema: `ContentFolderAssignment`. _Example: FolderAssignment_ Example response for a successfully retrieved folder assignment ``` { "contentId": "homepage-banner", "folderId": "homepage-folder", "position": 0, "default": true } ``` * **404** The requested resource was not found. This can occur when: * The specified library does not exist. * The specified content asset does not exist in the library. * The specified folder does not exist in the library. * The assignment between the content asset and folder does not exist. Media type: `application/json`. Schema: `ErrorResponse`. _Example ContentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 404 response._ Example error response for content asset not found _Example FolderNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for folder not found _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found _Example: AssignmentNotFound_ Example error response for folder assignment not found ``` { "title": "Assignment Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/assignment-not-found", "detail": "No assignment from content asset with ID 'homepage-banner' to content folder with ID 'homepage-folder' in library 'SiteLibrary' could be found." } ``` _Example: ContentNotFound_ Example error response for content asset not found _Example: FolderNotFound_ Example error response for folder not found _Example: LibraryNotFound_ Example error response for library not found ### PUT Create a content folder assignment for a content asset `PUT /organizations/{organizationId}/libraries/{libraryId}/folder-assignments/{contentId}/{folderId}` Operation ID: `createOrUpdateFolderAssignment`. Security: AmOAuth2 (sfcc.experiences.rw). Creates a new assignment assignment between a content asset and a folder. **Important**: * This is an admin-only operation requiring appropriate permissions. * If the assignment doesn't exist, it will be created (201). * If the assignment exists, it will be updated (200). * Both the content asset and folder must exist before creating the assignment. * A content asset can be assigned to multiple folders. #### 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 ``` * `libraryId` (path, string, required) Identifier for the content library. Maximum length: 256. Example: `SiteLibrary`. * `contentId` (path, string, required) Identifier for the content asset. Maximum length: 256. Example: `homepage-banner`. * `folderId` (path, string, required) Identifier for the content folder. Maximum length: 256. Example: `seasonal-content`. #### Request body (required) Media type: `application/json`. Schema: `ContentFolderAssignment`. _Example: CreateAssignmentRequest_ Example request to create a new folder assignment ``` { "contentId": "homepage-banner", "folderId": "homepage-folder", "position": 3, "default": true } ``` _Example: UpdateAssignmentRequest_ Example request to update an existing folder assignment ``` { "contentId": "homepage-banner", "folderId": "homepage-folder", "position": 2, "default": false } ``` #### Responses * **200** Content Folder assignment updated successfully Media type: `application/json`. Schema: `ContentFolderAssignment`. _Example: UpdatedAssignment_ Example response for a successfully updated folder assignment ``` { "contentId": "homepage-banner", "folderId": "homepage-folder", "position": 8, "default": false } ``` * **201** Content Folder assignment created successfully Media type: `application/json`. Schema: `ContentFolderAssignment`. _Example: CreatedAssignment_ Example response for a successfully created folder assignment ``` { "contentId": "homepage-banner", "folderId": "homepage-folder", "position": 0, "default": true } ``` * **404** The specified resource does not exist. Media type: `application/json`. Schema: `ErrorResponse`. _Example ContentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 404 response._ Example error response for content asset not found _Example FolderNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for folder not found _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found _Example: ContentNotFound_ Example error response for content asset not found _Example: FolderNotFound_ Example error response for folder not found _Example: LibraryNotFound_ Example error response for library not found ### DELETE Delete a content folder assignment for a content asset `DELETE /organizations/{organizationId}/libraries/{libraryId}/folder-assignments/{contentId}/{folderId}` Operation ID: `deleteFolderAssignment`. Security: AmOAuth2 (sfcc.experiences.rw). Removes the assignment relationship between a content asset and a folder. **Important**: * This is an admin-only operation requiring appropriate permissions. * The assignment must exist to be deleted. * This operation cannot be undone. * The content asset and folder themselves are not deleted, only their assignment relationship. #### 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 ``` * `libraryId` (path, string, required) Identifier for the content library. Maximum length: 256. Example: `SiteLibrary`. * `contentId` (path, string, required) Identifier for the content asset. Maximum length: 256. Example: `homepage-banner`. * `folderId` (path, string, required) Identifier for the content folder. Maximum length: 256. Example: `seasonal-content`. #### Responses * **204** Content folder assignment deleted successfully * **404** The requested resource was not found. Media type: `application/json`. Schema: `ErrorResponse`. _Example AssignmentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folder-assignments/{contentId}/{folderId} 404 response._ Example error response for folder assignment not found _Example ContentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 404 response._ Example error response for content asset not found _Example FolderNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for folder not found _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found _Example: AssignmentNotFound_ Example error response for folder assignment not found _Example: ContentNotFound_ Example error response for content asset not found _Example: FolderNotFound_ Example error response for folder not found _Example: LibraryNotFound_ Example error response for library not found ### PATCH Update a content folder assignment for a content asset `PATCH /organizations/{organizationId}/libraries/{libraryId}/folder-assignments/{contentId}/{folderId}` Operation ID: `updateFolderAssignment`. Security: AmOAuth2 (sfcc.experiences.rw). Updates an existing assignment between a content asset and a folder. **Important**: * This is an admin-only operation requiring appropriate permissions. * If the assignment doesn't exist, it will be created (201). * If the assignment exists, it will be updated (200). * Both the content asset and folder must exist before creating the assignment. * A content asset can be assigned to multiple folders. #### 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 ``` * `libraryId` (path, string, required) Identifier for the content library. Maximum length: 256. Example: `SiteLibrary`. * `contentId` (path, string, required) Identifier for the content asset. Maximum length: 256. Example: `homepage-banner`. * `folderId` (path, string, required) Identifier for the content folder. Maximum length: 256. Example: `seasonal-content`. #### Request body (required) Media type: `application/json`. Schema: `ContentFolderAssignment`. _Example: CreateAssignmentRequest_ Example request to create a new folder assignment ``` { "contentId": "homepage-banner", "folderId": "homepage-folder", "position": 3, "default": true } ``` _Example: UpdateAssignmentRequest_ Example request to update an existing folder assignment ``` { "contentId": "homepage-banner", "folderId": "homepage-folder", "position": 2, "default": false } ``` #### Responses * **200** Content folder assignment updated successfully Media type: `application/json`. Schema: `ContentFolderAssignment`. _Example: UpdatedAssignment_ Example response for a successfully updated folder assignment ``` { "contentId": "homepage-banner", "folderId": "homepage-folder", "position": 8, "default": false } ``` * **404** The specified resource does not exist. Media type: `application/json`. Schema: `ErrorResponse`. _Example ContentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 404 response._ Example error response for content asset not found _Example FolderNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for folder not found _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found _Example: ContentNotFound_ Example error response for content asset not found _Example: FolderNotFound_ Example error response for folder not found _Example: LibraryNotFound_ Example error response for library not found ### GET Get content assets in a folder `GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId}/content` Operation ID: `getFolderContent`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw). Retrieves a list of content assets within a specific folder. **Important**: * This is an admin-only operation requiring appropriate permissions. * Returns all content assets directly assigned to the specified folder. * Results can be paginated using limit and offset parameters. * Content assets are returned with their assignment metadata including sort order. * Only content assets assigned to this specific folder are included (not sub-folders). #### 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 ``` * `libraryId` (path, string, required) Identifier for the content library. Maximum length: 256. Example: `SiteLibrary`. * `folderId` (path, string, required) Identifier for the content folder. Maximum length: 256. Example: `seasonal-content`. * `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25. Default: `25`. Minimum: 1. Maximum: 200. * `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset. Default: `0`. Minimum: 0. #### Responses * **200** Content assets retrieved successfully Media type: `application/json`. Schema: `ContentAssetResult`. _Example: FolderContentResult_ Example response for content assets in a folder ``` { "limit": 3, "offset": 0, "total": 10, "hits": [ { "id": "homepage-banner", "name": { "default": "Homepage Banner", "en": "Homepage Banner" }, "description": { "default": "Main promotional banner for the homepage", "en": "Main promotional banner for the homepage" }, "online": { "default": true }, "pageTitle": { "default": "Homepage Banner - My Shop", "en": "Homepage Banner - My Shop" }, "pageDescription": { "default": "Discover amazing products at great prices", "en": "Discover amazing products at great prices" }, "pageKeywords": { "default": "banner, promotion, homepage", "en": "banner, promotion, homepage" }, "folderId": "homepage-folder", "template": "rendering/content/banner" }, { "id": "hero-image", "name": { "default": "Hero Image", "en": "Hero Image" }, "description": { "default": "Hero section image", "en": "Hero section image" }, "online": { "default": true }, "pageTitle": { "default": "Hero Image - My Shop", "en": "Hero Image - My Shop" }, "classificationFolderId": "homepage-folder", "template": "rendering/content/image" }, { "id": "cta-section", "name": { "default": "Call to Action Section", "en": "Call to Action Section" }, "description": { "default": "Homepage call to action content", "en": "Homepage call to action content" }, "online": { "default": true }, "pageTitle": { "default": "CTA Section - My Shop", "en": "CTA Section - My Shop" }, "classificationFolderId": "homepage-folder", "template": "rendering/content/cta" } ] } ``` * **400** Invalid request parameters provided. Media type: `application/json`. Schema: `ErrorResponse`. _Example: InvalidLimitParameter_ Example error response for invalid limit parameter ``` { "title": "Bad Request", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "detail": "The limit parameter must be between 1 and 200." } ``` * **404** The requested resource was not found. This can occur when: * The specified library does not exist. * The specified folder does not exist in the library. Media type: `application/json`. Schema: `ErrorResponse`. _Example FolderNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for folder not found _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found _Example: FolderNotFound_ Example error response for folder not found _Example: LibraryNotFound_ Example error response for library not found ### GET Get a slot `GET /organizations/{organizationId}/slots/{slotId}/{contextType}` Operation ID: `getSlot`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw). Retrieves detailed information about a specific slot including its configurations. **Important**: * This is an admin-only operation requiring appropriate permissions. * The slot must exist in the specified context. * Returns the slot with all associated slot configurations. * Context type can be global, category, or folder. #### 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 ``` * `slotId` (path, string, required) Identifier for the slot Maximum length: 256. Example: `homepage-banner-slot`. * `contextType` (path, string, required) Context type for the slot (global, category, or folder) Allowed values: `global`, `category`, `folder`. Example: `global`. * `select` (query, Select) _Example: select_ ``` (**) ``` #### Responses * **200** Slot retrieved successfully Media type: `application/json`. Schema: `Slot`. _Example: RetrievedSlot_ Example response for a successfully retrieved slot ``` { "slotId": "homepage-banner-slot", "description": "Main banner slot on homepage", "previewUrl": "https://example.com/preview/slot/homepage-banner-slot", "contextType": "global", "slotConfigurations": [ { "configurationId": "homepage-banner-config", "slotId": "homepage-banner-slot", "uuid": "abc123def456ghi789jkl012", "enabled": true, "default": false, "description": "Default banner configuration", "rank": 1, "context": "global", "slotContent": { "type": "contentAssets", "contentAssetIds": [ "homepage-banner", "promo-banner" ] } } ], "creationDate": "2024-01-15T10:30:00.000Z", "lastModified": "2024-01-15T10:30:00.000Z" } ``` * **404** The requested resource was not found. This can occur when: * The specified site does not exist. * The specified slot does not exist in the given context. Media type: `application/json`. Schema: `ErrorResponse`. _Example SiteNotFound: same as PUT /organizations/{organizationId}/pages/{pageId} 404 response._ Example error response for site not found _Example: SlotNotFound_ Example error response for slot not found ``` { "title": "Slot Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/slot-not-found", "detail": "Slot with ID 'homepage-banner-slot' in context 'global' could not be found for site 'RefArch'." } ``` _Example: SiteNotFound_ Example error response for site not found ### POST Search for slots `POST /organizations/{organizationId}/slot-search` Operation ID: `searchSlots`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw). This API allows searching for slots based on various criteria such as slot ID, description, and context type. **Important**: * This is an admin-only operation requiring appropriate permissions. * The search uses POST method to support complex query structures. * Results are paginated and can be sorted. * Searchable fields include: slotId (String), description (String), contextType (String). * Only searchable attributes can be used in sorting. * Context type value is restricted to Global/Folder/Category. #### 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 ``` #### Request body (required) Media type: `application/json`. Schema: `SlotSearchRequest`. _Example: SearchBySlotId_ Example search request by slot ID ``` { "query": { "textQuery": { "fields": [ "slotId" ], "searchPhrase": "homepage" } }, "limit": 25, "offset": 0 } ``` _Example: SearchByContext_ Example search request by context type ``` { "query": { "filteredQuery": { "query": { "matchAllQuery": {} }, "filter": { "termFilter": { "field": "contextType", "operator": "is", "values": [ "global" ] } } } }, "limit": 2, "offset": 0 } ``` #### Responses * **200** Search completed successfully Media type: `application/json`. Schema: `SlotSearchResult`. _Example: SearchResults_ Example response for slot search ``` { "query": { "textQuery": { "fields": [ "slotId" ], "searchPhrase": "homepage" } }, "limit": 2, "offset": 0, "total": 25, "hits": [ { "slotId": "homepage-banner-slot", "description": "Main banner slot on homepage", "contextType": "global", "creationDate": "2024-01-15T10:30:00.000Z", "lastModified": "2024-01-15T10:30:00.000Z" }, { "slotId": "category-promo-slot", "description": "Category promotional slot", "contextType": "category", "creationDate": "2024-01-16T14:20:00.000Z", "lastModified": "2024-01-16T14:20:00.000Z" } ] } ``` * **400** Invalid search query provided. Media type: `application/json`. Schema: `ErrorResponse`. _Example: SqlQueryMalformedJoin_ Example error response for malformed SQL query ``` { "title": "SQL Query Malformed Join", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/sql-query-malformed-join", "detail": "One or more attributes 'slotId' are in a different bucket and therefore must be joined with an AND operator.", "field": "slotId" } ``` _Example: UnqueryableField_ Example error response for unqueryable field ``` { "title": "Unqueryable Field", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unqueryable-field", "detail": "The field 'uuid' can't be queried.", "field": "uuid" } ``` * **404** The requested resource was not found. This can occur when: * The specified site does not exist. Media type: `application/json`. Schema: `ErrorResponse`. _Example SiteNotFound: same as PUT /organizations/{organizationId}/pages/{pageId} 404 response._ Example error response for site not found _Example: SiteNotFound_ Example error response for site not found ### GET Get a slot configuration `GET /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId}` Operation ID: `getSlotConfiguration`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw). Retrieves detailed information about a specific slot configuration. **Important**: * This is an admin-only operation requiring appropriate permissions. * The slot configuration must exist. * Returns the configuration with all properties including schedule, content, and assignment information. * Requires siteId query parameter to identify the site context. #### 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 ``` * `slotId` (path, string, required) Identifier for the slot Maximum length: 256. Example: `homepage-banner-slot`. * `configurationId` (path, string, required) Identifier for the slot configuration Maximum length: 256. Example: `homepage-banner-config`. * `context` (query, string) The context for the slot configuration (global, category, or folder) Allowed values: `global`, `category`, `folder`. Example: `global`. #### Responses * **200** Slot configuration retrieved successfully Media type: `application/json`. Schema: `SlotConfiguration`. _Example: RetrievedSlotConfiguration_ Example response for a successfully retrieved slot configuration ``` { "configurationId": "homepage-banner-config", "slotId": "homepage-banner-slot", "uuid": "abc123def456ghi789jkl012", "enabled": true, "default": false, "description": "Default banner configuration for homepage", "callout": { "default": { "source": "Limited Time Offer!", "markup": "

Limited Time Offer!

" } }, "customerGroups": [ "registered-customers", "vip-customers" ], "rank": 1, "template": "slots/banner/homepage", "context": "global", "schedule": { "startDate": "2024-01-01T00:00:00.000Z", "endDate": "2024-12-31T23:59:59.000Z" }, "slotContent": { "type": "products", "productIds": [ "product-001", "product-002" ] }, "creationDate": "2024-01-15T10:30:00.000Z", "lastModified": "2024-01-15T10:30:00.000Z" } ``` * **400** Invalid request parameters. This can occur when: * The specified context type is invalid. * The context ID is missing for category or folder context. Media type: `application/json`. Schema: `ErrorResponse`. _Example: InvalidContextType_ Example error response for invalid context type ``` { "title": "Invalid Context Type", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-context-type", "detail": "The specified context type is invalid. Valid values are: global, category, folder." } ``` _Example: MissingContextId_ Example error response for missing context ID ``` { "title": "Missing Context ID", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/missing-context-id", "detail": "Context ID is required when context type is 'category' or 'folder'." } ``` * **404** The requested resource was not found. This can occur when: * The specified slot does not exist. * The specified slot configuration does not exist. * The specified site does not exist. Media type: `application/json`. Schema: `ErrorResponse`. _Example SlotNotFound: same as GET /organizations/{organizationId}/slots/{slotId}/{contextType} 404 response._ Example error response for slot not found _Example SiteNotFound: same as PUT /organizations/{organizationId}/pages/{pageId} 404 response._ Example error response for site not found _Example: SlotNotFound_ Example error response for slot not found _Example: SlotConfigurationNotFound_ Example error response for slot configuration not found ``` { "title": "Slot Configuration Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/slot-configuration-not-found", "detail": "Slot configuration with ID 'homepage-banner-config' could not be found for site 'RefArch'." } ``` _Example: SiteNotFound_ Example error response for site not found ### PUT Create or update a slot configuration `PUT /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId}` Operation ID: `createOrUpdateSlotConfiguration`. Security: AmOAuth2 (sfcc.experiences.rw). Creates a new slot configuration or updates an existing one. **Important**: * This is an admin-only operation requiring appropriate permissions. * If the slot configuration doesn't exist, it will be created (201). * If the slot configuration exists, it will be updated (200). * Configuration ID in URL must match the configuration ID in the request body. * The slot must exist before creating configurations. * Requires siteId query parameter to identify the site context. #### 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 ``` * `slotId` (path, string, required) Identifier for the slot Maximum length: 256. Example: `homepage-banner-slot`. * `configurationId` (path, string, required) Identifier for the slot configuration Maximum length: 256. Example: `homepage-banner-config`. * `context` (query, string) The context for the slot configuration (global, category, or folder) Allowed values: `global`, `category`, `folder`. Example: `global`. #### Request body (required) Media type: `application/json`. Schema: `SlotConfiguration`. _Example: CreateSlotConfigRequest_ Example request to create a new slot configuration ``` { "configurationId": "new-banner-config", "slotId": "homepage-banner-slot", "enabled": true, "default": false, "description": "New promotional banner configuration", "callout": { "default": { "source": "New Arrivals!" } }, "customerGroups": [ "registered-customers" ], "rank": 2, "template": "slots/banner/promo", "context": "global", "slotContent": { "type": "contentAssets", "contentAssetIds": [ "promo-banner-001" ] } } ``` _Example: UpdateSlotConfigRequest_ Example request to update an existing slot configuration ``` { "configurationId": "homepage-banner-config", "slotId": "homepage-banner-slot", "enabled": true, "default": true, "description": "Updated banner configuration for homepage", "callout": { "default": { "source": "Sale Now On!" } }, "customerGroups": [ "all-customers" ], "rank": 1, "template": "slots/banner/homepage", "context": "global", "slotContent": { "type": "contentAssets", "contentAssetIds": [ "sale-banner", "promo-banner" ] } } ``` #### Responses * **200** Slot configuration updated successfully Media type: `application/json`. Schema: `SlotConfiguration`. _Example: UpdatedSlotConfiguration_ Example response for a successfully updated slot configuration ``` { "configurationId": "homepage-banner-config", "slotId": "homepage-banner-slot", "uuid": "abc123def456ghi789jkl012", "enabled": true, "default": true, "description": "Updated banner configuration for homepage", "callout": { "default": { "source": "Sale Now On!", "markup": "

Sale Now On!

" } }, "customerGroups": [ "all-customers" ], "rank": 1, "template": "slots/banner/homepage", "context": "global", "slotContent": { "type": "contentAssets", "contentAssetIds": [ "sale-banner", "promo-banner" ] }, "creationDate": "2024-01-15T10:30:00.000Z", "lastModified": "2024-03-31T16:00:00.000Z" } ``` * **201** Slot configuration created successfully Media type: `application/json`. Schema: `SlotConfiguration`. _Example: CreatedSlotConfiguration_ Example response for a successfully created slot configuration ``` { "configurationId": "new-banner-config", "slotId": "homepage-banner-slot", "uuid": "xyz789abc456def123ghi456", "enabled": true, "default": false, "description": "New promotional banner configuration", "callout": { "default": { "source": "New Arrivals!", "markup": "

New Arrivals!

" } }, "customerGroups": [ "registered-customers" ], "rank": 2, "template": "slots/banner/promo", "context": "global", "slotContent": { "type": "contentAssets", "contentAssetIds": [ "promo-banner-001" ] }, "creationDate": "2024-03-31T15:45:00.000Z", "lastModified": "2024-03-31T15:45:00.000Z" } ``` * **400** Invalid slot configuration data provided. This can occur when: * The ID in the request path does not match the ID in the request body. * The specified context type is invalid. * The context ID is missing for category or folder context. Media type: `application/json`. Schema: `ErrorResponse`. _Example InvalidContextType: same as GET /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId} 400 response._ Example error response for invalid context type _Example MissingContextId: same as GET /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId} 400 response._ Example error response for missing context ID _Example: IdConflict_ Example error response for ID conflict ``` { "title": "ID Conflict", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/id-conflict", "detail": "The ID in the request path does not match the ID in the request body." } ``` _Example: InvalidContextType_ Example error response for invalid context type _Example: InvalidSlotId_ Example error response for invalid slot ID ``` { "title": "Invalid Slot ID", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-slot-id", "detail": "The specified slot ID is invalid or the slot does not exist." } ``` _Example: MissingContextId_ Example error response for missing context ID * **404** The specified resource was not found. This can occur when: * The specified site does not exist. * The specified slot does not exist. * Content asset does not exist in the library. Media type: `application/json`. Schema: `ErrorResponse`. _Example SiteNotFound: same as PUT /organizations/{organizationId}/pages/{pageId} 404 response._ Example error response for site not found _Example SlotNotFound: same as GET /organizations/{organizationId}/slots/{slotId}/{contextType} 404 response._ Example error response for slot not found _Example ContentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 404 response._ Example error response for content asset not found _Example: SiteNotFound_ Example error response for site not found _Example: SlotNotFound_ Example error response for slot not found _Example: ContentNotFound_ Example error response for content asset not found ### DELETE Delete a slot configuration `DELETE /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId}` Operation ID: `deleteSlotConfiguration`. Security: AmOAuth2 (sfcc.experiences.rw). Deletes a slot configuration. **Important**: * This is an admin-only operation requiring appropriate permissions. * The slot configuration must exist to be deleted. * This operation cannot be undone. * Requires siteId query parameter to identify the site context. #### 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 ``` * `slotId` (path, string, required) Identifier for the slot Maximum length: 256. Example: `homepage-banner-slot`. * `configurationId` (path, string, required) Identifier for the slot configuration Maximum length: 256. Example: `homepage-banner-config`. * `context` (query, string) The context for the slot configuration (global, category, or folder) Allowed values: `global`, `category`, `folder`. Example: `global`. #### Responses * **204** Slot configuration deleted successfully * **400** Invalid request parameters. This can occur when: * The specified context type is invalid. Media type: `application/json`. Schema: `ErrorResponse`. _Example InvalidContextType: same as GET /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId} 400 response._ Example error response for invalid context type _Example: InvalidContextType_ Example error response for invalid context type * **404** The requested resource was not found. This can occur when: * The specified site does not exist. * The specified slot does not exist. Media type: `application/json`. Schema: `ErrorResponse`. _Example SiteNotFound: same as PUT /organizations/{organizationId}/pages/{pageId} 404 response._ Example error response for site not found _Example SlotNotFound: same as GET /organizations/{organizationId}/slots/{slotId}/{contextType} 404 response._ Example error response for slot not found _Example: SiteNotFound_ Example error response for site not found _Example: SlotNotFound_ Example error response for slot not found ### PATCH Partially update a slot configuration `PATCH /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId}` Operation ID: `patchSlotConfiguration`. Security: AmOAuth2 (sfcc.experiences.rw). Updates specific properties of an existing slot configuration without replacing the entire resource. **Important**: * This is an admin-only operation requiring appropriate permissions. * Only the properties provided in the request body will be updated. * The slot configuration must already exist. * Useful for updating specific attributes without affecting other properties. * Requires siteId query parameter to identify the site context. #### 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 ``` * `slotId` (path, string, required) Identifier for the slot Maximum length: 256. Example: `homepage-banner-slot`. * `configurationId` (path, string, required) Identifier for the slot configuration Maximum length: 256. Example: `homepage-banner-config`. * `context` (query, string) The context for the slot configuration (global, category, or folder) Allowed values: `global`, `category`, `folder`. Example: `global`. #### Request body (required) Media type: `application/json`. Schema: `SlotConfiguration`. _Example: PatchSlotConfigRequest_ Example request to partially update a slot configuration ``` { "configurationId": "homepage-banner-config", "slotId": "homepage-banner-slot", "enabled": false, "description": "Temporarily disabled banner", "slotContent": { "type": "products", "productIds": [ "product-001" ] } } ``` #### Responses * **200** Slot configuration updated successfully Media type: `application/json`. Schema: `SlotConfiguration`. _Example UpdatedSlotConfiguration: same as PUT /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId} 200 response._ Example response for a successfully updated slot configuration _Example: UpdatedSlotConfiguration_ Example response for a successfully updated slot configuration * **400** Invalid slot configuration data provided. This can occur when: * The specified context type is invalid. * The context ID is missing for category or folder context. Media type: `application/json`. Schema: `ErrorResponse`. _Example InvalidContextType: same as GET /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId} 400 response._ Example error response for invalid context type _Example MissingContextId: same as GET /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId} 400 response._ Example error response for missing context ID _Example: InvalidContextType_ Example error response for invalid context type _Example: MissingContextId_ Example error response for missing context ID * **404** The requested resource was not found. This can occur when: * The specified slot does not exist. * The specified slot configuration does not exist. * The specified site does not exist. * Content asset does not exist in the library. Media type: `application/json`. Schema: `ErrorResponse`. _Example SlotNotFound: same as GET /organizations/{organizationId}/slots/{slotId}/{contextType} 404 response._ Example error response for slot not found _Example SlotConfigurationNotFound: same as GET /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId} 404 response._ Example error response for slot configuration not found _Example SiteNotFound: same as PUT /organizations/{organizationId}/pages/{pageId} 404 response._ Example error response for site not found _Example ContentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 404 response._ Example error response for content asset not found _Example: SlotNotFound_ Example error response for slot not found _Example: SlotConfigurationNotFound_ Example error response for slot configuration not found _Example: SiteNotFound_ Example error response for site not found _Example: ContentNotFound_ Example error response for content asset not found * **409** Conflict with existing resource. This can occur when: * A slot configuration with the specified ID already exists in this context. Media type: `application/json`. Schema: `ErrorResponse`. _Example: SlotConfigurationAlreadyExists_ Example error response for slot configuration conflict ``` { "title": "Slot Configuration Already Exists", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/slot-configuration-already-exists", "detail": "A slot configuration with the specified ID already exists in this context." } ``` ### POST Search for slot configurations `POST /organizations/{organizationId}/slot-configurations-search` Operation ID: `searchSlotConfigurations`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw). This API allows searching for slot configurations based on various criteria such as slot ID, context, customer groups, and more. **Important**: * This is an admin-only operation requiring appropriate permissions. * The search uses POST method to support complex query structures. * Results are paginated and can be sorted. * Use the query parameter to filter results based on specific criteria. #### 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 ``` #### Request body (required) Media type: `application/json`. Schema: `SlotConfigurationSearchRequest`. _Example: SearchBySlotId_ Example request to search slot configurations by slot ID ``` { "query": { "textQuery": { "fields": [ "slotId" ], "searchPhrase": "homepage-banner" } }, "limit": 25, "offset": 0 } ``` _Example: SearchByContext_ Example request to search slot configurations by context ``` { "query": { "boolQuery": { "must": [ { "termQuery": { "fields": [ "context" ], "operator": "is", "values": [ "global" ] } }, { "termQuery": { "fields": [ "enabled" ], "operator": "is", "values": [ true ] } } ] } }, "limit": 50, "offset": 0, "sorts": [ { "field": "rank", "sortOrder": "asc" } ] } ``` #### Responses * **200** Search completed successfully Media type: `application/json`. Schema: `SlotConfigurationSearchResult`. _Example: SearchResults_ Example response for slot configuration search ``` { "limit": 2, "offset": 0, "total": 25, "hits": [ { "configurationId": "homepage-banner-config", "slotId": "homepage-banner", "uuid": "abc123def456ghi789jkl012", "enabled": true, "default": true, "description": "Default banner configuration for homepage", "callout": { "default": { "source": "Limited Time Offer!", "markup": "

Limited Time Offer!

" } }, "customerGroups": [ "registered-customers", "vip-customers" ], "rank": 1, "template": "slots/banner/homepage", "context": "global", "schedule": { "startDate": "2024-01-01T00:00:00.000Z", "endDate": "2024-12-31T23:59:59.000Z" }, "slotContent": { "type": "products", "productIds": [ "product-001", "product-002" ] }, "assignmentInformation": { "activeCampaignAssignments": [ { "slotId": "homepage-banner", "slotConfigurationId": "homepage-banner-config", "slotConfigurationUuid": "abc123def456ghi789jkl012", "description": "Holiday campaign banner", "campaignId": "holiday-2024", "rank": 1, "customerGroups": [ "registered-customers" ], "context": "global", "enabled": true, "schedule": { "startDate": "2024-11-01T00:00:00.000Z", "endDate": "2024-12-31T23:59:59.000Z" } } ], "upcomingCampaignAssignments": [], "activeAbtestAssignments": [], "upcomingAbtestAssignments": [] }, "creationDate": "2024-01-15T10:30:00.000Z", "lastModified": "2024-01-15T10:30:00.000Z" }, { "configurationId": "category-banner-config", "slotId": "category-banner", "uuid": "xyz789abc456def123ghi456", "enabled": true, "default": false, "description": "Banner configuration for electronics category", "customerGroups": [ "all-customers" ], "rank": 2, "template": "slots/banner/category", "context": "category", "contextId": "electronics", "schedule": { "startDate": "2024-01-01T00:00:00.000Z", "endDate": "2024-06-30T23:59:59.000Z", "recurrence": { "dayOfWeek": [ "monday", "wednesday", "friday" ], "timeOfDay": { "timeFrom": "09:00:00", "timeTo": "17:00:00" } } }, "slotContent": { "type": "html", "body": { "default": { "source": "

Welcome to Electronics

Check out our latest deals!

", "markup": "

Welcome to Electronics

Check out our latest deals!

" } } }, "assignmentInformation": { "activeCampaignAssignments": [], "upcomingCampaignAssignments": [], "activeAbtestAssignments": [ { "abtestId": "electronics-test-001", "abtestDescription": "Electronics banner A/B test", "enabled": true, "schedule": { "startDate": "2024-02-01T00:00:00.000Z", "endDate": "2024-03-31T23:59:59.000Z" }, "segmentId": "segment-a", "segmentDescription": "Segment A - Control group" } ], "upcomingAbtestAssignments": [] }, "creationDate": "2024-01-10T08:00:00.000Z", "lastModified": "2024-01-20T14:30:00.000Z" } ], "query": { "textQuery": { "fields": [ "slotId" ], "searchPhrase": "banner" } }, "sorts": [ { "field": "rank", "sortOrder": "asc" } ] } ``` * **400** Invalid search query provided. Media type: `application/json`. Schema: `ErrorResponse`. _Example SqlQueryMalformedJoin: same as POST /organizations/{organizationId}/slot-search 400 response._ Example error response for malformed SQL query _Example UnqueryableField: same as POST /organizations/{organizationId}/slot-search 400 response._ Example error response for unqueryable field _Example: SqlQueryMalformedJoin_ Example error response for malformed SQL query _Example: UnqueryableField_ Example error response for unqueryable field _Example: FieldNotSortable_ Example error response for field not sortable ``` { "title": "Field Not Sortable", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/field-not-sortable", "detail": "The field 'template' can't be used to sort the results.", "field": "template" } ``` * **404** The requested resource was not found. This can occur when: * The specified site does not exist. Media type: `application/json`. Schema: `ErrorResponse`. _Example SiteNotFound: same as PUT /organizations/{organizationId}/pages/{pageId} 404 response._ Example error response for site not found _Example: SiteNotFound_ Example error response for site not found ### GET Get page types `GET /organizations/{organizationId}/page-types` Operation ID: `getPageTypes`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw). Retrieves the list of Page Designer page types available for a site, including their region definitions, attribute definitions, and supported aspect types. **Important**: * This is an admin-only operation requiring appropriate permissions. * Requires the siteId query parameter to identify the site context. * Aspect types are returned embedded within each page type's supportedAspectTypes. #### 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 ``` * `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25. Default: `25`. Minimum: 1. Maximum: 200. * `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset. Default: `0`. Minimum: 0. #### Responses * **200** Page types retrieved successfully Media type: `application/json`. Schema: `PageTypeResult`. _Example: PageTypesResult_ Example response for successfully retrieved page types ``` { "limit": 2, "offset": 0, "total": 2, "hits": [ { "id": "storePage", "name": { "default": "Store Page", "en": "Store Page" }, "description": { "default": "A general-purpose storefront page", "en": "A general-purpose storefront page" }, "route": "storefront", "archType": "headless", "regionDefinitions": [ { "id": "regionA", "name": { "default": "Main Region", "en": "Main Region" }, "maxComponents": 5, "componentTypeExclusions": [] } ], "attributeDefinitionGroups": [ { "id": "general", "name": { "default": "General", "en": "General" }, "attributeDefinitions": [ { "id": "title", "name": { "default": "Title", "en": "Title" }, "type": "string", "required": true } ] } ] }, { "id": "productDetailPage", "name": { "default": "Product Detail Page", "en": "Product Detail Page" }, "description": { "default": "Displays a single product bound to a product aspect", "en": "Displays a single product bound to a product aspect" }, "route": "product", "archType": "headless", "regionDefinitions": [ { "id": "regionA", "name": { "default": "Main Region", "en": "Main Region" }, "maxComponents": 5, "componentTypeExclusions": [] } ], "attributeDefinitionGroups": [], "supportedAspectTypes": [ { "id": "pdpAspect", "name": { "default": "Product Detail Aspect", "en": "Product Detail Aspect" }, "description": { "default": "Provides product context to the page", "en": "Provides product context to the page" }, "archType": "headless", "supportedObjectTypes": [ "product" ], "attributeDefinitions": [ { "id": "primaryProduct", "name": { "default": "Primary Product", "en": "Primary Product" }, "type": "product", "required": true } ] } ] } ] } ``` _Example: EmptyPageTypesResult_ Example response when the requested page contains no page types ``` { "limit": 25, "offset": 0, "total": 0, "hits": [] } ``` * **400** Invalid request parameters provided. Media type: `application/json`. Schema: `ErrorResponse`. _Example MissingSiteId: same as PUT /organizations/{organizationId}/pages/{pageId} 400 response._ Example error response for missing site ID _Example: MissingSiteId_ Example error response for missing site ID * **404** The requested resource was not found. This can occur when: * The specified site does not exist. Media type: `application/json`. Schema: `ErrorResponse`. _Example SiteNotFound: same as PUT /organizations/{organizationId}/pages/{pageId} 404 response._ Example error response for site not found _Example: SiteNotFound_ Example error response for site not found ### GET Get component types `GET /organizations/{organizationId}/component-types` Operation ID: `getComponentTypes`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw). Retrieves the list of Page Designer component types available for a site, including their group, region definitions, and attribute definitions. **Important**: * This is an admin-only operation requiring appropriate permissions. * Requires the siteId query parameter to identify the site context. * Each component type carries its group id and localized group name. #### 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 ``` * `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25. Default: `25`. Minimum: 1. Maximum: 200. * `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset. Default: `0`. Minimum: 0. #### Responses * **200** Component types retrieved successfully Media type: `application/json`. Schema: `ComponentTypeResult`. _Example: ComponentTypesResult_ Example response for successfully retrieved component types ``` { "limit": 2, "offset": 0, "total": 2, "hits": [ { "id": "commerce_assets.banner", "name": { "default": "Banner", "en": "Banner" }, "description": { "default": "A promotional banner component", "en": "A promotional banner component" }, "archType": "headless", "embedded": false, "group": { "id": "commerce_assets", "name": { "default": "Commerce Assets", "en": "Commerce Assets" } }, "attributeDefinitionGroups": [ { "id": "general", "name": { "default": "General", "en": "General" }, "attributeDefinitions": [ { "id": "heading", "name": { "default": "Heading", "en": "Heading" }, "type": "string", "required": true } ] } ] }, { "id": "commerce_assets.carousel", "name": { "default": "Carousel", "en": "Carousel" }, "description": { "default": "A rotating carousel of slides", "en": "A rotating carousel of slides" }, "archType": "headless", "embedded": false, "group": { "id": "commerce_assets", "name": { "default": "Commerce Assets", "en": "Commerce Assets" } }, "regionDefinitions": [ { "id": "slides", "name": { "default": "Slides", "en": "Slides" }, "maxComponents": 10, "componentTypeExclusions": [] } ], "attributeDefinitionGroups": [] } ] } ``` _Example: EmptyComponentTypesResult_ Example response when the requested page contains no component types ``` { "limit": 25, "offset": 0, "total": 0, "hits": [] } ``` * **400** Invalid request parameters provided. Media type: `application/json`. Schema: `ErrorResponse`. _Example MissingSiteId: same as PUT /organizations/{organizationId}/pages/{pageId} 400 response._ Example error response for missing site ID _Example: MissingSiteId_ Example error response for missing site ID * **404** The requested resource was not found. This can occur when: * The specified site does not exist. Media type: `application/json`. Schema: `ErrorResponse`. _Example SiteNotFound: same as PUT /organizations/{organizationId}/pages/{pageId} 404 response._ Example error response for site not found _Example: SiteNotFound_ Example error response for site not found ## 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`. ### PageRequest Includes all fields of `PageBase`. * `regions` (_array of RegionRequest_) The regions and their assigned components for the page ### Page Includes all fields of `PageBase`. * `custom` (_object_) Any custom data added by the custom code for the page type _Example_ ``` { "thumbnail_full": "http://static.myshop.com/new-homepage.jpg" } ``` * `regions` (_array of Region_) The regions (and their assigned components) for the page * `creationDate` (_string (date-time)_) The date and time of page creation Example: `2024-01-15T10:30:00.000Z`. * `lastModified` (_string (date-time)_) The date and time when the page was last modified Example: `2024-01-15T10:30:00.000Z`. * `online` (_boolean_) Indicates whether the page is online (active) or offline (draft) Example: `false`. ### 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`. ### ContentFolder * `id` (_string_, required) The ID of the content folder Maximum length: 256. Example: `seasonal-content`. * `description` (_object_) The localized content folder description B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `string`. _Example_ ``` { "default": "Folder for seasonal content", "en": "Folder for seasonal content" } ``` * `name` (_object_) The localized content folder name B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `string`. _Example_ ``` { "en": "Seasonal Content" } ``` * `online` (_boolean_) A flag indicating whether the folder is online (default is false) Example: `false`. * `pageDescription` (_object_) The localized content folder page description B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `string`. _Example_ ``` { "default": "Seasonal content page description", "en": "Seasonal content page description" } ``` * `pageKeywords` (_object_) The localized content folder page keywords B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `string`. _Example_ ``` { "default": "seasonal, content, folder", "en": "seasonal, content, folder" } ``` * `pageTitle` (_object_) The localized content folder page title B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `string`. _Example_ ``` { "default": "Seasonal Content", "en": "Seasonal Content" } ``` * `pageUrl` (_object_) The localized content folder page URL B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `string`. _Example_ ``` { "default": "/seasonal", "en": "/seasonal" } ``` * `parentFolderId` (_string_) The ID of the parent content folder Example: `root`. * `template` (_string_) The rendering template Example: `rendering/folder/seasonal`. * `creationDate` (_string (date-time)_, read-only) The date and time when the slot configuration was created Example: `2024-01-15T10:30:00.000Z`. * `lastModified` (_string (date-time)_, read-only) The date and time when the slot configuration was last modified Example: `2024-01-15T10:30:00.000Z`. 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`. ### ContentSubFolderResult Result document containing an array of content subfolders. Includes all fields of `PaginatedResultBase`. * `hits` (_array of ContentFolder_) The sorted array of search hits. This array can be empty ### ContentAsset * `id` (_string_, required) The ID of the content asset Maximum length: 256. Example: `homepage-banner`. * `classificationFolderId` (_string_) The ID of the classification folder. It is only part of the response, if the assignment from this content asset to the folder is marked as 'default'. The property is read-only. To set the classification folder just create/update an assignment between this content asset and a folder and mark it as 'default'. See details in /libraries/{libraryId}/folder-assignments/{contentId}/{folderId} resource. Example: `classificationFolderId`. * `name` (_object_) The localized content asset name B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `string`. _Example_ ``` { "default": "Homepage Banner", "en": "Homepage Banner" } ``` * `description` (_object_) The localized content asset description B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `string`. _Example_ ``` { "default": "Main promotional banner for the homepage", "en": "Main promotional banner for the homepage" } ``` * `online` (_object_) A flag indicating whether the content asset is online (default is false) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `boolean`. _Example_ ``` { "default": true } ``` * `pageDescription` (_object_) The localized content asset page description for SEO B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `string`. _Example_ ``` { "default": "Discover amazing products at great prices", "en": "Discover amazing products at great prices" } ``` * `pageKeywords` (_object_) The localized content asset page keywords for SEO B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `string`. _Example_ ``` { "default": "banner, promotion, homepage", "en": "banner, promotion, homepage" } ``` * `pageTitle` (_object_) The localized content asset page title for SEO B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `string`. _Example_ ``` { "default": "Homepage Banner - My Shop", "en": "Homepage Banner - My Shop" } ``` * `pageUrl` (_object_) The localized content asset page URL B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `string`. _Example_ ``` { "default": "/seasonal", "en": "/seasonal" } ``` * `searchable` (_object_) A site specific flag indicating whether the content asset is searchable B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `boolean`. _Example_ ``` { "default": true } ``` * `siteMapChangeFrequency` (_object_) The content assets change frequency needed for the sitemap creation (always, hourly, daily, weekly, monthly, yearly, never). B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `string`. Allowed values: `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, `never`. _Example_ ``` { "default": "always" } ``` * `siteMapIncluded` (_object_) The status if the content asset is included into the sitemap (either 0 or 1). B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `integer`. Minimum: 0. Maximum: 1. _Example_ ``` { "default": 0 } ``` * `siteMapPriority` (_object_) The content assets priority needed for the sitemap creation (0.0 for no priority defined). B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `number`. _Example_ ``` { "default": 0 } ``` * `template` (_string_) The rendering template Example: `rendering/content/banner`. * `creationDate` (_string (date-time)_, read-only) The date and time when the slot configuration was created Example: `2024-01-15T10:30:00.000Z`. * `lastModified` (_string (date-time)_, read-only) The date and time when the slot configuration was last modified Example: `2024-01-15T10:30:00.000Z`. 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 Result document containing an array of content folders. Includes all fields of `PaginatedResultBase`. * `hits` (_array of ContentFolder_) The sorted array of search hits. This array can be empty ### ContentFolderAssignment * `contentId` (_string_, required) The ID of the content asset Maximum length: 256. Example: `homepage-banner`. * `folderId` (_string_, required) The ID of the folder Maximum length: 256. Example: `homepage-folder`. * `position` (_number (double)_) The sort order/position of the content asset within the folder Minimum: 0. Example: `1`. * `default` (_boolean_) Indicates whether this is the default/primary folder assignment for the content asset Example: `true`. 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`. ### ContentAssetResult Result document for content assets in a folder Includes all fields of `PaginatedResultBase`. * `hits` (_array of ContentAsset_) The sorted array of search hits. This array can be empty. ### Select The property selector declaring which fields are included into the response payload. You can specify a single field name, a comma-separated list of names or work with wildcards. You can also specify array operations and filter expressions. The actual selector value must be enclosed within parentheses. For more information, please read the documentation about property selectors [here](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html). Type: `string`. Minimum length: 1. Pattern: ^\[(\].\*\[)\]$. Example: `(name,id,variationAttributes.(**))`. ### Slot Document representing a slot * `slotId` (_string_, required) The ID of the slot Maximum length: 256. Example: `homepage-banner-slot`. * `description` (_string_) The user-supplied description of the slot Maximum length: 4000. Example: `Main banner slot on homepage`. * `previewUrl` (_string_) A URL for previewing the slot in context. This URL is system-generated and allows viewing the slot's appearance on the storefront. Maximum length: 4000. Example: `https://example.com/preview/slot/homepage-banner-slot`. * `contextType` (_string_, required) The context type of the slot Allowed values: `global`, `category`, `folder`. Example: `global`. * `slotConfigurations` (_array of SlotConfiguration_) List of slot configurations associated with this slot * `creationDate` (_string (date-time)_) The date and time when the slot was created Example: `2024-01-15T10:30:00.000Z`. * `lastModified` (_string (date-time)_) The date and time when the slot was last modified Example: `2024-01-15T10:30:00.000Z`. ### SlotSearchRequest Request body for searching slots Includes all fields of `SearchRequest`. ### SlotSearchResult Result document for a slot search Includes all fields of `PaginatedSearchResult`. * `hits` (_array of Slot_) The sorted array of search hits ### SlotConfiguration Document representing a slot configuration * `configurationId` (_string_, required) The ID of the configuration Maximum length: 256. Example: `homepage-banner-config`. * `slotId` (_string_, required) The ID of the slot Maximum length: 256. Example: `homepage-banner`. * `uuid` (_string_) The UUID of the slot configuration Maximum length: 28. Example: `abc123def456ghi789jkl012`. * `enabled` (_boolean_, required) Specifies whether the slot is enabled Example: `true`. * `default` (_boolean_) Specifies whether the configuration is the default for the slot Example: `false`. * `description` (_string_) The configuration description Maximum length: 4000. Example: `Default banner configuration for homepage`. * `callout` (_object_) The call out message (localized) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `MarkupText`. _Example_ ``` { "default": { "source": "Limited Time Offer!", "markup": "

Limited Time Offer!

" } } ``` * `customerGroups` (_array of string_) The customer groups ids Items: Example: `registered-customers`. _Example_ ``` [ "registered-customers", "vip-customers" ] ``` * `rank` (_integer_) The rank of the slot configuration on its slot Minimum: 1. Example: `1`. * `template` (_string_) The template Maximum length: 256. Example: `slots/banner/homepage`. * `contextId` (_string_) The identifier for the context. Required when context is 'category' (categoryId) or 'folder' (folderId). Not applicable for 'global' context. Maximum length: 256. Example: `electronics`. * `context` (_string_) The context of the slot Allowed values: `global`, `category`, `folder`. Example: `global`. * `schedule` (_Schedule_) * `slotContent` (_SlotContent_, required) * `assignmentInformation` (_SlotConfigurationAssignmentInformation_) * `creationDate` (_string (date-time)_) The date and time when the slot configuration was created Example: `2024-01-15T10:30:00.000Z`. * `lastModified` (_string (date-time)_) The date and time when the slot configuration was last modified Example: `2024-01-15T10:30:00.000Z`. 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`. ### SlotConfigurationSearchRequest Request body for searching slot configurations Includes all fields of `SearchRequest`. ### SlotConfigurationSearchResult Result document for a slot configuration search Includes all fields of `PaginatedSearchResult`. * `hits` (_array of SlotConfiguration_) The sorted array of search hits ### PageTypeResult Result document containing an array of page types. Includes all fields of `PaginatedResultBase`. * `hits` (_array of PageType_, required) The sorted array of page types. This array can be empty. ### ComponentTypeResult Result document containing an array of component types. Includes all fields of `PaginatedResultBase`. * `hits` (_array of ComponentType_, required) The sorted array of component types. This array can be empty. ### PageBase * `id` (_string_, required) Unique identifier for the page Maximum length: 256. Example: `new-homepage`. * `typeId` (_string_, required) Page type identifier Maximum length: 256. Example: `storePage`. * `aspectTypeId` (_string_) The aspect type to assign to the page Maximum length: 256. Example: `pdpAspect`. * `name` (_string_, required) Display name of the page Maximum length: 4000. Example: `New Homepage`. * `description` (_string_) Description of the page Maximum length: 4000. Example: `New home page for the storefront`. * `pageTitle` (_string_) The SEO title of the page Maximum length: 4000. Example: `New Homepage - My Shop`. * `pageDescription` (_string_) The SEO description of the page Maximum length: 4000. Example: `Welcome to our new homepage.`. * `pageKeywords` (_string_) The SEO keywords of the page Maximum length: 4000. Example: `homepage, fashion, my shop`. * `thumbnail` (_string_) The thumbnail image for the page Maximum length: 256. Example: `new-homepage.jpg`. * `data` (_object_) The configuration data for the page. This is an open object that can contain: * Custom attributes defined by the page type * A `visibilityRule` object (see VisibilityRule schema) that defines visibility conditions for the page _Example_ ``` { "site_map_priority": 0.8, "layout": "default", "visibilityRule": { "customerGroups": [ { "id": "registered-customers" } ], "validFrom": "2024-01-01T00:00:00.000Z", "validTo": "2024-12-31T23:59:59.000Z" } } ``` 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`. ### RegionRequest * `id` (_string_, required) Region identifier Maximum length: 256. Example: `header`. * `components` (_array of ComponentRequest_) The components to assign to the region 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`. ### Region * `id` (_string_, required) Region identifier Maximum length: 256. Example: `header`. * `components` (_array of Component_) The components in the region ### 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) ### SearchRequest Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource. * `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200. Minimum: 1. Maximum: 200. Example: `10`. * `query` (_Query_, required) * `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed. * `offset` (_Offset_) ### PaginatedSearchResult Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`. Includes all fields of `PaginatedResultBase`. * `query` (_Query_, required) * `sorts` (_array of Sort_) The sorting that was applied to the result. * `hits` (_array of object_) The sorted array of search hits. Can be empty. _Example_ ``` { "limit": 1, "hits": [ { "couponId": "coupon1", "creationDate": "2019-10-20T12:00:00Z", "description": "This coupon is used to give 10% off stuff.", "enabled": false, "exportedCodeCount": 0, "lastModified": "2019-10-30T04:23:59Z", "redemptionCount": 3, "redemptionLimits": { "limitPerCode": 1, "limitPerCustomer": 1, "limitPerTimeFrame": { "limit": 2, "redemptionTimeFrame": 24 } }, "singleCode": "MyCode", "systemCodesConfig": { "codePrefix": "SG", "numberOfCodes": 500000 }, "totalCodesCount": 50, "type": "single_code" } ], "query": { "textQuery": { "fields": [ "id", "description" ], "searchPhrase": "stuff" } }, "sorts": [ { "field": "couponId", "sortOrder": "desc" } ], "offset": 2, "total": 8 } ``` ### MarkupText Document representing markup text with source and rendered HTML * `source` (_string_) The raw markup text Example: `

Welcome to our store

`. * `markup` (_string_) The rendered HTML (read only) Example: `

Welcome to our store

`. ### Schedule Document representing a time schedule. Defines an optional validity window (startDate/endDate) and an optional recurrence. Omitting a bound leaves that side of the window open (unbounded). * `startDate` (_string (date-time)_) The date to start validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ. Example: `2026-01-01T00:00:00.000Z`. * `endDate` (_string (date-time)_) The date to end of validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ. Example: `2026-01-31T23:59:59.000Z`. * `recurrence` (_object_) The recurrence of the schedule by day of week and time of day. Not all schedules support a recurrence. Includes all fields of `Recurrence`. ### SlotContent Document representing the content type for a slot * `type` (_string_, required) The type of content in the slot Allowed values: `products`, `categories`, `contentAssets`, `html`, `recommendedProducts`. Example: `products`. * `productIds` (_array of string_) The product ids (valid only for type 'products') Items: Maximum length: 100. Example: `product-001`. _Example_ ``` [ "product-001", "product-002" ] ``` * `categoryIds` (_array of string_) The category ids (valid only for type 'categories') Items: Maximum length: 256. Example: `electronics`. _Example_ ``` [ "electronics", "computers" ] ``` * `recommendationRuleId` (_string_) The recommendation rule id (valid only for type 'recommendedProducts') Maximum length: 256. Example: `top-sellers`. * `contentAssetIds` (_array of string_) The content asset ids (valid only for type 'contentAssets') Items: Example: `banner-001`. _Example_ ``` [ "banner-001", "banner-002" ] ``` * `body` (_object_) The HTML body (valid only for type 'html', localized) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `MarkupText`. _Example_ ``` { "default": { "source": "

Welcome

", "markup": "

Welcome

" } } ``` ### SlotConfigurationAssignmentInformation Information about assignments and assignment schedules of a slot configuration * `activeCampaignAssignments` (_array of SlotConfigurationCampaignAssignment_) A list of currently active campaigns this is assigned to * `upcomingCampaignAssignments` (_array of SlotConfigurationCampaignAssignment_) A list of upcoming campaigns this is assigned to * `activeAbtestAssignments` (_array of SlotConfigurationABTestGroupAssignment_) A list of currently active A/B tests this is assigned to * `upcomingAbtestAssignments` (_array of SlotConfigurationABTestGroupAssignment_) A list of upcoming A/B tests this is assigned to ### PageType * `id` (_string_, required) The page type id Maximum length: 256. Example: `storePage`. * `name` (_LocalizedText_) * `description` (_LocalizedText_) * `route` (_string_) The route the page type is used for Maximum length: 256. Example: `storefront`. * `archType` (_string_) The storefront architecture this type targets Allowed values: `controller`, `headless`. Example: `headless`. * `preview` (_string_) Preview indicator; present only for preview container page types Allowed values: `default`. Example: `default`. * `regionDefinitions` (_array of RegionDefinition_) The regions components can be assigned to * `attributeDefinitionGroups` (_array of AttributeDefinitionGroup_) The grouped attribute definitions for the page type * `supportedAspectTypes` (_array of AspectType_) The aspect types this page type supports, resolved as full objects ### ComponentType * `id` (_string_, required) The component type id Maximum length: 256. Example: `commerce_assets.banner`. * `name` (_LocalizedText_) * `description` (_LocalizedText_) * `archType` (_string_) The storefront architecture this type targets Allowed values: `controller`, `headless`. Example: `headless`. * `embedded` (_boolean_) Whether this is embedded content Example: `false`. * `componentId` (_string_) Developer-defined content id for embedded components, used as the Content.ID when the component is created Maximum length: 256. Example: `banner`. * `group` (_ComponentTypeGroup_) * `regionDefinitions` (_array of RegionDefinition_) The regions components can be assigned to * `attributeDefinitionGroups` (_array of AttributeDefinitionGroup_) The grouped attribute definitions for the component type ### ComponentRequest * `id` (_string_, required) Component identifier Maximum length: 256. Example: `banner-component-1`. * `typeId` (_string_, required) Component type identifier Maximum length: 256. Example: `commerce_assets.banner`. * `name` (_string_) Display name of the component Maximum length: 256. Example: `Header Banner`. * `data` (_object_) The configuration data for the component _Example_ ``` { "title": "Welcome Banner", "bannerImage": "welcome-banner.jpg" } ``` * `visible` (_boolean_) Indicates whether the component is visible Example: `true`. * `localized` (_boolean_) Indicates whether the component is localized for the current locale Example: `true`. * `designMetadata` (_object_) 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.banner", "name": "Banner Component", "archType": "headless" } ``` * `regions` (_array of RegionRequest_) The regions for the component (for nested components) 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`. ### Component * `id` (_string_, required) Component identifier Maximum length: 256. Example: `banner-component-1`. * `typeId` (_string_, required) Component type identifier Maximum length: 256. Example: `commerce_assets.banner`. * `name` (_string_) Display name of the component Maximum length: 256. Example: `Header Banner`. * `data` (_object_) The configuration data assigned to the component _Example_ ``` { "title": "Welcome Banner", "bannerImage": "welcome-banner.jpg" } ``` * `custom` (_object_) Any custom data added by the custom code for this component _Example_ ``` { "banner_url": "http://static.myshop.com/welcome-banner.jpg" } ``` * `visible` (_boolean_) Indicates whether the component is visible Example: `true`. * `localized` (_boolean_) Indicates whether the component is localized for the current locale Example: `true`. * `fragment` (_boolean_) Indicates whether the component is a fragment. True if the component is a fragment, otherwise false. Example: `false`. * `embedded` (_boolean_) Indicates whether the component is embedded in another component. True if the component is embedded, otherwise false. Example: `false`. * `designMetadata` (_object_) 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.banner", "name": "Banner Component", "archType": "headless" } ``` * `regions` (_array of Region_) The regions (and their assigned components) for the component ### 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) ### Offset The zero-based index of the first hit/data to include in the result. Type: `integer (int32)`. Default: `0`. Minimum: 0. Example: `0`. ### Query A set of objects that define criteria used to select records. A query can contain one of the following: * `MatchAllQuery` * Matches all documents. * `TermQuery` * Matches one or more documents against one or more document fields. * `TextQuery` * Matches text against one or more fields. * `BoolQuery` * Allows construction of a logical expression of multiple queries. * `FilteredQuery` * Allows a filter to be applied to a query. * `NestedQuery` * Allows you to query on nested documents. * _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._ Minimum properties: 1. Maximum properties: 1. * `boolQuery` (_BoolQuery_) * `filteredQuery` (_FilteredQuery_) * `matchAllQuery` (_MatchAllQuery_) * `nestedQuery` (_NestedQuery_) * `termQuery` (_TermQuery_) * `textQuery` (_TextQuery_) _Example_ ``` { "filteredQuery": { "query": { "textQuery": { "fields": [ "couponId" ], "searchPhrase": "disabled" } }, "filter": { "termFilter": { "field": "enabled", "operator": "is", "values": [ false ] } } } } ``` ### Sort Document representing a sort request. Each API has a different default sort configuration that can be modified in the request. * `field` (_string_, required) The name of the field to sort on. Maximum length: 256. Example: `couponId`. * `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used. Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`. _Example_ ``` { "field": "couponId", "sortOrder": "desc" } ``` ### Recurrence Document representing a schedule recurrence. * `dayOfWeek` (_array of string_) The days of week for recurrence. Items: Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Example: `monday`. * `timeOfDay` (_object_) The time of the day for recurrence. Includes all fields of `TimeOfDay`. ### SlotConfigurationCampaignAssignment Document representing a slotConfigurationCampaignAssignment * `slotId` (_string_, required) The ID of the slot Maximum length: 256. Example: `homepage-banner`. * `slotConfigurationId` (_string_, required) The ID of the slot configuration Maximum length: 256. Example: `homepage-banner-config`. * `slotConfigurationUuid` (_string_) The UUID of the slot configuration Maximum length: 28. Example: `abc123def456ghi789jkl012`. * `description` (_string_) The description of the slot configuration Maximum length: 4000. Example: `Holiday campaign banner`. * `campaignId` (_string_) The id of the campaign that has the slot configuration assigned to it Maximum length: 256. Example: `holiday-2024`. * `rank` (_integer_) The rank of the slot configuration-campaign assignment Minimum: 1. Example: `1`. * `customerGroups` (_array of string_) The list of customer groups Items: Example: `registered-customers`. _Example_ ``` [ "registered-customers" ] ``` * `context` (_string_, required) The slot context Allowed values: `global`, `category`, `folder`. Example: `global`. * `slotContextId` (_string_) The ID of the slot's context Maximum length: 256. Example: `electronics`. * `enabled` (_boolean_) A flag indicating whether the assignment is enabled Example: `true`. * `schedule` (_Schedule_) * `campaign` (_object_) The campaign details _Example_ ``` { "campaignId": "holiday-2024", "description": "Holiday campaign" } ``` * `slotConfiguration` (_SlotConfiguration_) * `creationDate` (_string (date-time)_) The date and time when the assignment was created Example: `2024-11-01T10:00:00.000Z`. * `lastModified` (_string (date-time)_) The date and time when the assignment was last modified Example: `2024-11-01T10:00:00.000Z`. ### SlotConfigurationABTestGroupAssignment Document representing a SlotConfiguration AB test group assignment * `abtestId` (_string_) The ID of the A/B test assigned to the slot configuration Example: `homepage-test-001`. * `abtestDescription` (_string_) The description of the A/B test Example: `Homepage banner A/B test`. * `enabled` (_boolean_) Specifies whether the A/B test is enabled (true) or not (false) Example: `true`. * `schedule` (_Schedule_) * `segmentId` (_string_) The ID of the A/B test segment Example: `segment-a`. * `segmentDescription` (_string_) The description of the A/B test segment Example: `Segment A - Control group`. ### LocalizedText A localized string keyed by locale id, plus a 'default' fallback B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html) Additional properties: `string`. Maximum length: 4000. Example: `Store Page`. _Example_ ``` { "default": "Store Page", "en": "Store Page" } ``` ### RegionDefinition * `id` (_string_, required) The region id, unique within its type Maximum length: 256. Example: `regionA`. * `name` (_LocalizedText_) * `description` (_LocalizedText_) * `maxComponents` (_integer_) The maximum number of components rendered in the region Example: `3`. * `componentTypeExclusions` (_array of ComponentTypeExclusion_) Component types that may not be assigned to this region ### AttributeDefinitionGroup * `id` (_string_, required) The attribute definition group id, unique within its type Maximum length: 256. Example: `general`. * `name` (_LocalizedText_) * `description` (_LocalizedText_) * `attributeDefinitions` (_array of AttributeDefinition_) The attribute definitions in this group ### AspectType * `id` (_string_, required) The aspect type id Maximum length: 256. Example: `pdpAspect`. * `name` (_LocalizedText_) * `description` (_LocalizedText_) * `archType` (_string_) The storefront architecture this type targets Allowed values: `controller`, `headless`. Example: `headless`. * `supportedObjectTypes` (_array of string_) The object types this aspect can be assigned to Items: Maximum length: 256. Example: `product`. _Example_ ``` [ "product" ] ``` * `attributeDefinitions` (_array of AttributeDefinition_) The aspect's attribute definitions (a flat list) ### ComponentTypeGroup * `id` (_string_, required) The component type group id Maximum length: 256. Example: `commerce_assets`. * `name` (_LocalizedText_) ### 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`. ### BoolQuery A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses: * `must`, which combines as an `AND` operator. * `should`, which combines as an `OR` operator. * `must_not`, which combines as a `NOT` operator. If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example: ``` (must-1 AND must-1 AND ...) AND (should-1 OR should-2 OR ...) AND NOT (must_not-1 OR must_not-2 OR ...) ``` * `must` (_array of Query_) List of queries to be evaluated as an `AND` operator. * `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator. * `should` (_array of Query_) List of queries to be evaluated as an `OR` operator. _Example_ ``` { "must": [ { "textQuery": { "fields": [ "couponId" ], "searchPhrase": "DEAL" } }, { "textQuery": { "fields": [ "description" ], "searchPhrase": "Big bargain deal" } } ], "mustNot": [ { "termQuery": { "fields": [ "enabled" ], "operator": "is", "values": [ false ] } } ] } ``` ### FilteredQuery Allows to filter the result of a possibly complex query using a possibly complex filter. * `filter` (_Filter_, required) * `query` (_Query_, required) _Example_ ``` { "query": { "textQuery": { "fields": [ "couponId" ], "searchPhrase": "disabled" } }, "filter": { "termFilter": { "field": "enabled", "operator": "is", "values": [ false ] } } } ``` ### MatchAllQuery Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints. ### NestedQuery Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints. A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation. * `path` (_string_, required) The path to the nested document. Maximum length: 2048. Example: `order.shippingAddresses`. * `query` (_Query_, required) * `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score. Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`. _Example_ ``` { "path": "order.shippingAddresses", "query": { "boolQuery": { "must": [ { "boolQuery": { "must": [ { "termQuery": { "fields": [ "order.shippingAddresses.firstName" ], "operator": "is", "values": [ "John" ] } } ] } }, { "boolQuery": { "must": [ { "termQuery": { "fields": [ "order.shippingAddresses.lastName" ], "operator": "is", "values": [ "Doe" ] } } ] } } ] } }, "scoreMode": "avg" } ``` ### TermQuery A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator. **Limitations:** * The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise. * A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields. * `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator. Minimum items: 1. * `operator` (_string_, required) Returns the operator to use for the term query. Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`. * `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator. Items: Example: `myCouponId`. ### TextQuery A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields. * `fields` (_array of Field_, required) The document fields that the search phrase matches against. Minimum items: 1. * `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces. Example: `campaign summer`. _Example_ ``` { "fields": [ "couponId" ], "searchPhrase": "limit" } ``` ### TimeOfDay Document representing a time schedule within a single day. * `timeFrom` (_string_) The time to start from. Time format: HH:mm or HH:mm:ss. Seconds are ignored and set to 0. Pattern: ^(\[01\]\[0-9\]|2\[0-3\]):\[0-5\]\[0-9\](https://developer.salesforce.com/docs/commerce/commerce-api/references/:/[0-5/]/[0-9/])?$. Example: `09:00:00`. * `timeTo` (_string_) The time to end on. Time format: HH:mm or HH:mm:ss. Seconds are ignored and set to 0. Pattern: ^(\[01\]\[0-9\]|2\[0-3\]):\[0-5\]\[0-9\](https://developer.salesforce.com/docs/commerce/commerce-api/references/:/[0-5/]/[0-9/])?$. Example: `17:00:00`. ### ComponentTypeExclusion * `typeId` (_string_, required) The excluded component type id Maximum length: 256. Example: `commerce_assets.carousel`. ### AttributeDefinition * `id` (_string_, required) The attribute definition id, unique within its type Maximum length: 256. Example: `title`. * `name` (_LocalizedText_) * `description` (_LocalizedText_) * `type` (_string_) The attribute value type Allowed values: `string`, `text`, `markup`, `product`, `category`, `file`, `page`, `image`, `boolean`, `integer`, `enum`, `url`, `custom`, `cms_record`. Example: `string`. * `required` (_boolean_) Whether a value for this attribute is required Example: `true`. * `defaultValue` (_string | boolean | integer | number_) The default value applied when no value is set; its type follows the attribute 'type' Example: `Welcome`. One of: `string`, `boolean`, `integer`, `number`. * _string_ Type: `string`. Maximum length: 4000. Example: `Welcome`. * _boolean_ Type: `boolean`. Example: `true`. * _integer_ Type: `integer`. Example: `1`. * _number_ Type: `number`. Example: `1`. Example: `Welcome`. * `values` (_array of string | integer | number_) The set of valid values, used when type is 'enum' _Example_ ``` [ "small", "medium", "large" ] ``` * `editor` (_object_) Editor configuration; populated only for 'custom' and 'cms\_record' types, otherwise omitted _Example_ ``` { "contentType": "product" } ``` * `dynamicLookup` (_object_) Runtime lookup that aliases this attribute to an aspect attribute * `aspectAttributeAlias` (_string_) The aspect attribute id this attribute aliases at render time Maximum length: 256. Example: `primaryProduct`. _Example_ ``` { "aspectAttributeAlias": "primaryProduct" } ``` ### Filter Contains a set of objects that define criteria used to select records. A filter can contain one of the following: * `TermFilter` * Matches records where a field (or fields) exactly matches some simple value (including `null`). * `RangeFilter` * Matches records where a field value lies within a specified range. * `Range2Filter` * Matches records in a specified range across fields. * `QueryFilter` * Matches records based on a query. * `BoolFilter` * Provides filtering of records using a set of filters combined using a logical operator. Minimum properties: 1. Maximum properties: 1. * `boolFilter` (_BoolFilter_) * `queryFilter` (_QueryFilter_) * `range2Filter` (_Range2Filter_) * `rangeFilter` (_RangeFilter_) * `termFilter` (_TermFilter_) ### Field Name of the field. Might be a custom field name prefixed with c\_. Type: `string`. Maximum length: 260. Example: `couponId`. ### BoolFilter Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator. * `filters` (_array of Filter_) A list of filters that are logically combined by an operator. * `operator` (_string_, required) The logical operator that is used to combine the filters. Allowed values: `and`, `or`, `not`. Example: `and`. _Example_ ``` { "operator": "and", "filters": [ { "termFilter": { "field": "id", "operator": "is", "values": [ "myId" ] } }, { "termFilter": { "field": "couponId", "operator": "is", "values": [ "couponOne" ] } } ] } ``` ### QueryFilter Wraps any query and allows it to be used as a filter. * `query` (_Query_, required) ### Range2Filter Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range. The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`. The second range (R2) is defined by `fromValue` and `toValue`. The filter mode specifies the method used to compare the two ranges: * `overlap`: R1 overlaps fully or partially with R2. * `containing`: R1 contains R2. * `contained`: R1 is contained in R2. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive. A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default. * `filterMode` (_string_) Compare mode: overlap, containing, or contained. Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`. * `fromField` (_object_, required) The field name of the field that starts the first range. Example: `validFrom`. Includes all fields of `Field`. Example: `validFrom`. * `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`. Default: `true`. Example: `true`. * `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended. Example: `2007-01-01T00:00:00.000Z`. * `toField` (_object_, required) The field name of the field that ends the first range. Example: `validTo`. Includes all fields of `Field`. Example: `validTo`. * `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`. Default: `true`. Example: `true`. * `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended. Example: `2017-01-01T00:00:00.000Z`. _Example_ ``` { "fromField": "validFrom", "toField": "validTo", "filterMode": "overlap", "fromValue": "2007-01-01T00:00:00.000Z", "toValue": "2017-01-01T00:00:00.000Z" } ``` ### RangeFilter Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive. A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default. * `field` (_object_, required) The search field. Example: `validFrom`. Includes all fields of `Field`. Example: `validFrom`. * `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended. One of: `string (date-time)`, `integer`, `number`. * _string (date-time)_ Type: `string (date-time)`. Example: `2007-01-01T00:00:00.000Z`. * _integer_ Type: `integer`. Example: `1`. * _number_ Type: `number`. Example: `1`. * `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`. Default: `true`. Example: `true`. * `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended. One of: `string (date-time)`, `integer`, `number`. * _string (date-time)_ Type: `string (date-time)`. Example: `2007-01-02T00:00:00.000Z`. * _integer_ Type: `integer`. Example: `2`. * _number_ Type: `number`. Example: `2`. * `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`. Default: `true`. Example: `true`. ### TermFilter Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only. * `field` (_object_, required) The filter field. Includes all fields of `Field`. * `operator` (_string_, required) The operator used to compare the field's values with the given values. Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`. * `values` (_array of string_) The filter values. Items: Example: `myId`. _Example_ ``` { "field": "id", "operator": "is", "values": [ "myId" ] } ```