--- schema_version: "1" id: d0f9f4eda33a722a0f51f4b17698792733f3f7e22648b4e90c76d3aa67761978 title: Sites 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/sites.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/sites source_site: developer.salesforce.com content_type: documentation content_hash: 7fafe946dcf43178bb9dc2d322c5d521d9be58786417039d3180effaf3f5ba30 products: - B2C Commerce API - Salesforce APIs --- Sites # Sites [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/sites/sites-oas-v1-public.yaml) ## API Overview The Sites API provides endpoints for retrieving and searching sites within Salesforce Commerce Cloud using the following capabilities: * Site Retrieval: List all sites in an organization or retrieve a specific site by ID. * Advanced Discovery: Use the `displayName`, `description`, or `id` attributes to find specific sites for reporting or administrative operations. * Status Monitoring: Filter sites by their `inDeletion` status to track maintenance workflows or identify sites marked for removal. * Results Management: Navigate large datasets efficiently using pagination (limit/offset), field selection, and multi-field sorting. Sites represent individual storefronts or channels within a Commerce Cloud organization. ### Authentication 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.sites` (read-only access) or `sfcc.sites.rw` (read-write access) and other relevant scopes in the client ID used to generate the token. For a full list of 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 the [Authorization for Admin APIs guide.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html) ### Endpoints | Method | Endpoint | Description | | --- | --- | --- | | GET | `/organizations/{organizationId}/sites` | Returns a paginated list of sites | | GET | `/organizations/{organizationId}/sites/{siteId}` | Returns a single site by ID | | POST | `/organizations/{organizationId}/site-search` | Searches for sites using complex queries | ### Attribute Reference The following attributes can be used in search queries and sorting: * `id`: The unique identifier of the site (String) * `displayName`: The user-friendly display name of the site (String) * `description`: The description of the site (String) * `inDeletion`: Boolean flag indicating if the site is marked for deletion (Boolean) ### Use Cases * Site Management: Find and filter sites for administrative operations. * Site Lookup: Retrieve a specific site by ID to inspect its configuration. * Reporting: Generate reports on site configurations and status. * Monitoring: Track sites that are marked for deletion or maintenance. * Lifecycle Tracking: Monitor the deletion queue by filtering for sites where `inDeletion` is true. ### Best Practices * Use the `select` parameter to limit response fields and reduce payload size. * Use specific search queries to minimize result set size. * Apply sorting to organize results meaningfully. * Use pagination for large result sets. * Filter out deleted sites when appropriate using the `inDeletion` attribute. * Cache site information when possible to reduce API calls. **Version:** 1.3.0 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/site/sites/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 security scheme for Admin API access using Account Manager. Requires appropriate scopes for site management operations. * OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dw/oauth2/access\_token) * Scope sfcc.sites: Access to site resources * Scope sfcc.sites.rw: Read and write access to site resources ## Operations ### POST Search Sites `POST /organizations/{organizationId}/site-search` Operation ID: `searchSites`. Security: AmOAuth2 (sfcc.sites, sfcc.sites.rw). Searches for sites. The query attribute specifies a complex query that can be used to narrow down the search. This is the list of searchable attributes: * id - String * displayName - String * description - String * inDeletion - Boolean The output of the query can also be sorted. These are the list of sortable attributes: * id - String * displayName - String * description - String * inDeletion - Boolean #### 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 ``` #### Request body (required) The search request document Media type: `application/json`. Schema: `SiteSearchRequest`. _Example: SiteSearchById_ Search sites by ID Example of searching for sites by their ID using a term query ``` { "query": { "termQuery": { "fields": [ "id" ], "operator": "is", "values": [ "RefArch" ] } }, "limit": 10, "offset": 0 } ``` _Example: SiteSearchByDisplayName_ Search sites by display name Example of searching for sites by their display name using a text query ``` { "query": { "textQuery": { "fields": [ "displayName" ], "searchPhrase": "Reference Architecture" } }, "limit": 25, "offset": 0, "sorts": [ { "field": "displayName", "sortOrder": "asc" } ] } ``` _Example: SiteSearchActiveOnly_ Search only non-deleted sites Example of searching for sites that are not marked for deletion ``` { "query": { "termQuery": { "fields": [ "inDeletion" ], "operator": "is", "values": [ false ] } }, "limit": 100, "offset": 0, "sorts": [ { "field": "id", "sortOrder": "asc" } ] } ``` _Example: SiteSearchComplex_ Complex site search with multiple criteria Example of a complex search combining multiple conditions ``` { "query": { "boolQuery": { "must": [ { "termQuery": { "fields": [ "inDeletion" ], "operator": "is", "values": [ false ] } }, { "textQuery": { "fields": [ "displayName", "description" ], "searchPhrase": "production" } } ] } }, "limit": 20, "offset": 0, "sorts": [ { "field": "displayName", "sortOrder": "asc" } ] } ``` #### Responses * **200** Returns site search results Media type: `application/json`. Schema: `SiteSearchResult`. _Example: SiteSearchResultSuccess_ Successful site search result Example of a successful site search returning multiple sites ``` { "limit": 2, "offset": 0, "total": 2, "hits": [ { "id": "RefArch", "customerListLink": { "customerListId": "RefArch", "title": "Default Customer List" }, "displayName": { "default": "displayName", "en": "An English displayName", "de": "A German displayName" }, "description": { "default": "description", "en": "An English description", "de": "A German description" }, "inDeletion": false, "storefrontStatus": "online", "siteCatalogId": "storefront-catalog-m-en", "cartridges": "plugin_custom_cartridge:plugin_wishlists:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core", "customCartridges": "plugin_custom_cartridge:plugin_wishlists", "creationDate": "2024-01-15T10:00:00.000Z", "lastModified": "2024-10-14T15:30:00.000Z" }, { "id": "RefArchGlobal", "customerListLink": { "customerListId": "RefArchGlobal", "title": "Default Customer List" }, "displayName": { "default": "displayName", "en": "An English displayName", "de": "A German displayName" }, "description": { "default": "description", "en": "An English description", "de": "A German description" }, "inDeletion": false, "storefrontStatus": "online", "siteCatalogId": "storefront-catalog-m-de", "cartridges": "plugin_custom_cartridge:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core", "customCartridges": "plugin_custom_cartridge", "creationDate": "2024-02-10T08:00:00.000Z", "lastModified": "2024-11-01T12:00:00.000Z" } ], "query": { "termQuery": { "fields": [ "inDeletion" ], "operator": "is", "values": [ false ] } }, "sorts": [ { "field": "id", "sortOrder": "asc" } ] } ``` _Example: SiteSearchResultSingle_ Single site search result Example of a site search returning a single site ``` { "limit": 1, "offset": 0, "total": 1, "hits": [ { "id": "RefArch", "customerListLink": { "customerListId": "RefArch", "title": "Default Customer List" }, "displayName": { "default": "displayName", "en": "An English displayName", "de": "A German displayName" }, "description": { "default": "description", "en": "An English description", "de": "A German description" }, "inDeletion": false, "storefrontStatus": "online", "siteCatalogId": "storefront-catalog-m-en", "cartridges": "plugin_custom_cartridge:plugin_wishlists:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core", "customCartridges": "plugin_custom_cartridge:plugin_wishlists", "creationDate": "2024-01-15T10:00:00.000Z", "lastModified": "2024-10-14T15:30:00.000Z" } ], "query": { "termQuery": { "fields": [ "id" ], "operator": "is", "values": [ "RefArch" ] } }, "sorts": [ { "field": "id", "sortOrder": "asc" } ] } ``` * **400** Bad Request - Malformed search query or invalid parameters Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: MalformedSearchParameter_ Malformed search query Example of an error when the search query is malformed or invalid ``` { "title": "Malformed Search Parameter", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-search-parameter", "detail": "The search query contains invalid syntax. Please check the query structure and try again." } ``` _Example: InvalidFieldName_ Unqueryable Field Example of an error when an invalid field name is used in the search query ``` { "title": "Unqueryable Field", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unqueryable-field", "detail": "The field 'invalid_field' is not a searchable attribute for sites. Valid fields are: id, displayName, description, inDeletion." } ``` _Example: InvalidSortField_ Field Not Sortable Example of an error when an invalid field is used for sorting ``` { "title": "Field Not Sortable", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/field-not-sortable", "detail": "The field 'invalid_sort' is not a sortable attribute for sites. Valid sortable fields are: id, displayName, description, inDeletion." } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` ### GET Get Sites `GET /organizations/{organizationId}/sites` Operation ID: `getSites`. Security: AmOAuth2 (sfcc.sites, sfcc.sites.rw). Returns a paginated list of sites for the organization. Results are sorted by site ID in ascending order by default. Use the `select` parameter to control which fields are included in the response. Use the `limit` and `offset` parameters to paginate through results. #### 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 ``` * `select` (query, Select) _Example: select_ ``` (**) ``` * `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25. Default: `25`. Minimum: 1. Maximum: 50. * `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset. Default: `0`. Minimum: 0. #### Responses * **200** Returns a paginated list of sites Media type: `application/json`. Schema: `Sites`. _Example: GetSitesSuccess_ Successful retrieval of sites Example of a successful response returning a paginated list of sites with `select=(**)` applied. ``` { "limit": 3, "offset": 0, "total": 3, "data": [ { "id": "RefArch", "displayName": { "default": "Reference Architecture Site" }, "description": { "default": "Main storefront for reference architecture" }, "inDeletion": false, "storefrontStatus": "online", "siteCatalogId": "storefront-catalog-m-en", "cartridges": "plugin_custom_cartridge:plugin_wishlists:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core", "customCartridges": "plugin_custom_cartridge:plugin_wishlists", "customerListLink": { "customerListId": "customer-list-1", "title": "Default Customer List" }, "creationDate": "2024-01-15T10:00:00.000Z", "lastModified": "2024-10-14T15:30:00.000Z" }, { "id": "SiteGenesis", "displayName": { "default": "SiteGenesis Demo Site" }, "description": { "default": "Demo site for testing purposes" }, "inDeletion": false, "storefrontStatus": "online", "siteCatalogId": "storefront-catalog-sg", "cartridges": "plugin_custom_cartridge:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core", "customCartridges": "plugin_custom_cartridge", "customerListLink": { "customerListId": "customer-list-sg", "title": "SiteGenesis Customer List" }, "creationDate": "2023-06-10T08:00:00.000Z", "lastModified": "2024-09-20T12:45:00.000Z" }, { "id": "MobileSite", "displayName": { "default": "Mobile First Site" }, "description": { "default": "Optimized for mobile shopping experience" }, "inDeletion": false, "storefrontStatus": "maintenance", "siteCatalogId": "mobile-catalog", "cartridges": "plugin_wishlists:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core", "customCartridges": "plugin_wishlists", "creationDate": "2024-03-01T14:20:00.000Z", "lastModified": "2024-10-10T09:15:00.000Z" } ] } ``` _Example: GetSitesWithSelect_ Sites with select filter applied Example of a response when the select parameter limits returned fields ``` { "limit": 2, "offset": 0, "total": 2, "data": [ { "id": "RefArch" }, { "id": "SiteGenesis" } ] } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` ### GET Get Site `GET /organizations/{organizationId}/sites/{siteId}` Operation ID: `getSiteById`. Security: AmOAuth2 (sfcc.sites, sfcc.sites.rw). Returns the site identified by the given site ID. #### 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` (path, SiteId, required) The identifier of the site. _Example_ ``` RefArch ``` #### Responses * **200** Returns the requested site Media type: `application/json`. Schema: `Site`. _Example: GetSiteByIdSuccess_ Successful retrieval of a single site Example of a successful response returning a single site by its ID ``` { "id": "RefArch", "displayName": { "default": "Reference Architecture Site" }, "description": { "default": "Main storefront for reference architecture" }, "inDeletion": false, "storefrontStatus": "online", "siteCatalogId": "storefront-catalog-m-en", "cartridges": "plugin_custom_cartridge:plugin_wishlists:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core", "customCartridges": "plugin_custom_cartridge:plugin_wishlists", "customerListLink": { "customerListId": "customer-list-1", "title": "Default Customer List" }, "creationDate": "2024-01-15T10:00:00.000Z", "lastModified": "2024-10-14T15:30:00.000Z" } ``` _Example: GetSiteByIdMaintenance_ Site in maintenance mode Example of a site with maintenance storefront status ``` { "id": "MobileSite", "displayName": { "default": "Mobile First Site" }, "description": { "default": "Optimized for mobile shopping experience" }, "inDeletion": false, "storefrontStatus": "maintenance", "siteCatalogId": "mobile-catalog", "cartridges": "plugin_wishlists:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core", "customCartridges": "plugin_wishlists", "creationDate": "2024-03-01T14:20:00.000Z", "lastModified": "2024-10-10T09:15:00.000Z" } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` * **404** Site Not Found - The requested site ID does not exist Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: SiteNotFound_ Site Not Found Example of an error when the requested site ID does not exist ``` { "title": "Site Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/site-not-found", "detail": "No site with ID 'unknown' could be found." } ``` ### GET Get Site Custom Cartridges `GET /organizations/{organizationId}/sites/{siteId}/custom-cartridges` Operation ID: `getSiteCustomCartridges`. Security: AmOAuth2 (sfcc.sites, sfcc.sites.rw). Returns the site's custom cartridge path - the colon-delimited list of custom (non-system) cartridges assigned to the site. This is the mutable segment of the site's cartridge path. For the effective cartridge path, including system cartridges, see the `cartridges` field on the [Site](#tag/Sites/operation/getSiteById) resource. #### 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` (path, SiteId, required) The identifier of the site. _Example_ ``` RefArch ``` #### Responses * **200** Returns the site's custom cartridge path Media type: `application/json`. Schema: `SiteCustomCartridges`. _Example: GetSiteCustomCartridgesSuccess_ Successful retrieval of a site's custom cartridge path Example of a successful response returning the site's custom cartridge path ``` { "customCartridges": "plugin_custom_cartridge:plugin_wishlists" } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` * **404** Site Not Found - The requested site ID does not exist Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: SiteNotFound_ Site Not Found Example of an error when the requested site ID does not exist ``` { "title": "Site Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/site-not-found", "detail": "No site with ID 'unknown' could be found." } ``` ### PUT Replace Site Custom Cartridges `PUT /organizations/{organizationId}/sites/{siteId}/custom-cartridges` Operation ID: `replaceSiteCustomCartridges`. Security: AmOAuth2 (sfcc.sites.rw). Atomically replaces the site's custom cartridge path with the provided colon-delimited list. Each cartridge name must start with a letter and contain only letters, numbers, or underscores. Cartridge names that don't match this format are rejected with 400 Bad Request. This endpoint does not verify that a cartridge is present the active code version. System cartridges are not part of this resource and are unaffected by this operation. #### 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` (path, SiteId, required) The identifier of the site. _Example_ ``` RefArch ``` #### Request body (required) The custom cartridge path replacement request Media type: `application/json`. Schema: `SiteCustomCartridges`. _Example: ReplaceSiteCustomCartridgesRequest_ Replace the custom cartridge path Example of replacing a site's custom cartridge path with a new colon-delimited list ``` { "customCartridges": "plugin_custom_cartridge:plugin_wishlists:plugin_loyalty" } ``` #### Responses * **200** Custom cartridge path successfully replaced Media type: `application/json`. Schema: `SiteCustomCartridges`. _Example: ReplaceSiteCustomCartridgesSuccess_ Successfully replaced a site's custom cartridge path Example of a successful response after replacing the site's custom cartridge path ``` { "customCartridges": "plugin_custom_cartridge:plugin_wishlists:plugin_loyalty" } ``` * **400** Bad Request - Invalid cartridge path Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: InvalidCartridgeName_ Invalid Cartridge Path Example of an error when a specified cartridge name does not match the required format ``` { "title": "Invalid Cartridge Path", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-cartridge-path", "detail": "Invalid cartridge path '123_invalid': The cartridge name may only contain letters, numbers, or '_', must start with a letter, and be separated by ':'.", "cartridge": "123_invalid" } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` * **404** Site Not Found - The requested site ID does not exist Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: SiteNotFound_ Site Not Found Example of an error when the requested site ID does not exist ``` { "title": "Site Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/site-not-found", "detail": "No site with ID 'unknown' could be 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`. ### SiteSearchRequest Document representing a search request for retrieving sites. The query is a potentially complex set of expressions. Searchable attributes: * id - String * displayName - String * description - String * inDeletion - Boolean Sortable attributes: * id - String * displayName - String * description - String * inDeletion - Boolean Includes all fields of `SearchRequest`. ### SiteSearchResult Document representing a site search result. This includes the query, sorts, hits (array of Site objects), and pagination information. Includes all fields of `PaginatedSearchResult`. * `hits` (_array of Site_, required) The sorted array of search hits (Site objects). Can be empty. ### 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`. ### 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.(**))`. ### Sites Document representing a paginated list of sites. Includes all fields of `PaginatedResultBase`. * `data` (_array of Site_, required) The array of sites. ### 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`. ### Site * `id` (_object_, required) ID The ID of the site. Includes all fields of `SiteId`. * `displayName` (_object_) 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`. Localized string Maximum length: 4000. Example: `Site Display Name`. _Example_ ``` { "default": "Site Display Name", "en-US": "Site Display Name", "de-DE": "Site-Anzeigename", "ja-JP": "サイト表示名" } ``` * `description` (_object_) 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`. Localized string Maximum length: 4000. Example: `Site Description`. _Example_ ``` { "default": "Site Description", "en-US": "Site Description", "de-DE": "Site-Beschreibung", "ja-JP": "サイトの説明" } ``` * `customerListLink` (_object_) The link to the customer list Includes all fields of `CustomerListLink`. * `inDeletion` (_boolean_) Specifies whether the site status is in deletion (true) or not (false) Example: `false`. * `storefrontStatus` (_string_) Status of the storefront Allowed values: `online`, `maintenance`, `to_be_deleted`, `protected`. Example: `online`. * `siteCatalogId` (_string_) The catalog bound to the given site. Minimum length: 1. Maximum length: 256. Example: `storefront-catalog-m-en`. * `cartridges` (_string_, read-only) The effective cartridge path for the site, delimited by ':'. Includes both system cartridges and the site's custom cartridges (see `customCartridges`). Maximum length: 4000. Example: `app_storefront_base:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core`. * `customCartridges` (_string_) The custom cartridge path assigned to the site, delimited by ':'. Does not include system cartridges. This is the subset of `cartridges` that can be configured for the site. Maximum length: 4000. Example: `app_storefront_base`. * `creationDate` (_string (date-time)_) The timestamp when the site was created. Example: `2024-01-15T10:00:00.000Z`. * `lastModified` (_string (date-time)_) The timestamp when the site was last modified. Example: `2024-10-14T15:30:00.000Z`. ### SiteCustomCartridges Document representing the custom cartridge path of a site - the colon-delimited list of custom (non-system) cartridges assigned to the site. This is the mutable segment of the site's cartridge path and aligns with the site import and export representation (`custom-cartridges`). Each cartridge name must start with a letter and contain only letters, numbers, or underscores. * `customCartridges` (_string_, required) The custom cartridges assigned to the site, delimited by ':'. Maximum length: 4000. Example: `plugin_custom_cartridge:plugin_wishlists`. ### 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 } ``` ### 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) ### CustomerListLink Document representing a link to a customer list. * `customerListId` (_string_) The customer list identifier Minimum length: 1. Maximum length: 256. Example: `customer-list-1`. * `title` (_string_) The title of the customer list link Maximum length: 256. Example: `Default Customer List`. ### 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" } ``` ### Offset The zero-based index of the first hit/data to include in the result. Type: `integer (int32)`. Default: `0`. Minimum: 0. Example: `0`. ### 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) ### 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" } ``` ### 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`. ### 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" ] } ```