--- schema_version: "1" id: 0f36d0211c891fa55b01d3e36603df8b6518099dc1364b9f265f60555041d36a title: Scripts 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/scripts.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/scripts source_site: developer.salesforce.com content_type: documentation content_hash: 4b471d776ef2832fa02f745d65a6f93633a52be876debd2edcd120e8687a28c8 products: - B2C Commerce API - Salesforce APIs --- Scripts # Scripts [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/scripts/scripts-oas-v1-public.yaml) ## API Overview The Scripts API provides endpoints for managing code versions on a Commerce Cloud instance. ### Overview Code versions represent deployable bundles of cartridge code. This API allows administrators to list, create, read, update, and delete code versions on their Commerce Cloud instance. ### Key Features * **List Code Versions**: Retrieve all code versions available on the instance * **Get Code Version**: Get detailed information about a specific code version * **Create Code Version**: Create or replace a code version using PUT * **Update Code Version**: Modify code version properties, such as activating a code version * **Delete Code Version**: Remove a code version (the active code version cannot be deleted) ### Authentication This API requires OAuth 2.0 authentication with the appropriate scopes: * `sfcc.scripts` - Read access to code version resources * `sfcc.scripts.rw` - Read and write access to code version resources ### Best Practices 1. Always verify which code version is active before making changes 2. Use PATCH to update specific properties like activating a code version 3. Avoid deleting the active code version - deactivate it first 4. Use the GET list endpoint to discover available code versions before performing operations **Version:** 1.0.1 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/dx/scripts/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) AccountManager OAuth 2.0 bearer token Authentication. * OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token) * Scope sfcc.scripts: Scripts API READONLY scope * Scope sfcc.scripts.rw: Scripts API scope * OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token) ## Operations ### GET Get a list of code versions. `GET /organizations/{organizationId}/code-versions` Operation ID: `getCodeVersions`. Security: AmOAuth2 (sfcc.scripts, sfcc.scripts.rw). Retrieves a list of all code versions available on the instance. #### 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 ``` * `expand` (query, array of string, style: form, explode: false) Specifies which related resources to include in the response. Use `size` to include the total size of the code version. Items: Allowed values: `size`. Example: `size`. _Example_ ``` [ "size" ] ``` #### Responses * **200** List of code versions successfully retrieved. Media type: `application/json`. Schema: `CodeVersionResult`. _Example: CodeVersionListSuccess_ Successful code version list result Example of a successful response returning a list of all code versions on the instance. ``` { "limit": 2, "total": 2, "data": [ { "id": "version1", "active": true, "cartridges": [ "app_storefront_base", "app_storefront_controllers" ], "compatibilityMode": "25.6", "lastModificationTime": "2025-01-15T10:30:00.000Z", "rollback": false, "webDavUrl": "https://example.com/on/demandware.servlet/webdav/Sites/Cartridges/version1" }, { "id": "version2", "active": false, "cartridges": [ "app_storefront_base" ], "compatibilityMode": "25.6", "lastModificationTime": "2025-01-10T08:00:00.000Z", "rollback": true, "webDavUrl": "https://example.com/on/demandware.servlet/webdav/Sites/Cartridges/version2" } ] } ``` * **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 a code version. `GET /organizations/{organizationId}/code-versions/{codeVersionId}` Operation ID: `getCodeVersion`. Security: AmOAuth2 (sfcc.scripts, sfcc.scripts.rw). Retrieves the details of a specific code version by its 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 ``` * `codeVersionId` (path, string, required) The ID of the code version. Minimum length: 1. Maximum length: 256. Example: `version1`. * `expand` (query, array of string, style: form, explode: false) Specifies which related resources to include in the response. Use `size` to include the total size of the code version. Items: Allowed values: `size`. Example: `size`. _Example_ ``` [ "size" ] ``` #### Responses * **200** Code version successfully retrieved. Media type: `application/json`. Schema: `CodeVersion`. _Example: CodeVersionSuccess_ Successful code version retrieval Example of a successful response returning a single code version with all properties. ``` { "id": "version1", "active": true, "cartridges": [ "app_storefront_base", "app_storefront_controllers" ], "compatibilityMode": "25.6", "lastModificationTime": "2025-01-15T10:30:00.000Z", "rollback": false, "webDavUrl": "https://example.com/on/demandware.servlet/webdav/Sites/Cartridges/version1" } ``` _Example: CodeVersionSuccessWithSize_ Successful code version retrieval with size expanded Example of a successful response returning a single code version with the totalSize field included when `expand=size` is requested. ``` { "id": "version1", "active": true, "cartridges": [ "app_storefront_base", "app_storefront_controllers" ], "compatibilityMode": "25.6", "lastModificationTime": "2025-01-15T10:30:00.000Z", "rollback": false, "totalSize": 104857600, "webDavUrl": "https://example.com/on/demandware.servlet/webdav/Sites/Cartridges/version1" } ``` * **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** Code version not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: CodeVersionIdNotFound_ ``` { "title": "Code Version Id Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/code-version-id-not-found", "detail": "The code version with ID 'nonexistent_version' couldn't be found." } ``` ### PUT Create or replace a code version. `PUT /organizations/{organizationId}/code-versions/{codeVersionId}` Operation ID: `createCodeVersion`. Security: AmOAuth2 (sfcc.scripts.rw). Creates a new code version or replaces an existing one with the given 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 ``` * `codeVersionId` (path, string, required) The ID of the code version. Minimum length: 1. Maximum length: 256. Example: `version1`. #### Responses * **200** Code version successfully replaced. Media type: `application/json`. Schema: `CodeVersion`. _Example: CodeVersionReplacedSuccess_ Successful code version replacement Example of a successful response when an existing code version is replaced via PUT. ``` { "id": "version1", "active": true, "cartridges": [ "app_storefront_base", "app_storefront_controllers" ], "compatibilityMode": "25.6", "lastModificationTime": "2025-01-16T12:00:00.000Z", "rollback": false, "webDavUrl": "https://example.com/on/demandware.servlet/webdav/Sites/Cartridges/version1" } ``` * **201** Code version successfully created. Media type: `application/json`. Schema: `CodeVersion`. _Example: CodeVersionCreatedSuccess_ Successful code version creation Example of a successful response when a new code version is created via PUT. ``` { "id": "new_version", "active": false, "cartridges": [ "app_storefront_base" ], "compatibilityMode": "25.6", "lastModificationTime": "2025-01-16T09:00:00.000Z", "rollback": false, "webDavUrl": "https://example.com/on/demandware.servlet/webdav/Sites/Cartridges/new_version" } ``` * **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" } ``` * **409** A code version with the given ID already exists. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: CodeVersionIdAlreadyExists_ ``` { "title": "Code Version Id Already Exists", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/code-version-id-already-exists", "detail": "The code version ID 'version1' already exists." } ``` ### DELETE Delete a code version. `DELETE /organizations/{organizationId}/code-versions/{codeVersionId}` Operation ID: `deleteCodeVersion`. Security: AmOAuth2 (sfcc.scripts.rw). Deletes an existing code version by its ID. The active code version cannot be deleted. #### 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 ``` * `codeVersionId` (path, string, required) The ID of the code version. Minimum length: 1. Maximum length: 256. Example: `version1`. #### Responses * **204** Code version successfully deleted. * **400** The active code version cannot be deleted. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: CodeVersionModification_ ``` { "title": "Code Version Modification", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/code-version-modification", "detail": "The code version 'version1' is active and can't be changed." } ``` * **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** Code version not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example CodeVersionIdNotFound: same as GET /organizations/{organizationId}/code-versions/{codeVersionId} 404 response._ ### PATCH Update a code version. `PATCH /organizations/{organizationId}/code-versions/{codeVersionId}` Operation ID: `updateCodeVersion`. Security: AmOAuth2 (sfcc.scripts.rw). Updates an existing code version with the provided properties. Use this endpoint to activate a code version. #### 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 ``` * `codeVersionId` (path, string, required) The ID of the code version. Minimum length: 1. Maximum length: 256. Example: `version1`. #### Request body (required) Media type: `application/json`. Schema: `CodeVersion`. _Example: ActivateCodeVersion_ Activate a code version Example of activating a code version by setting active to true ``` { "active": true } ``` #### Responses * **200** Code version successfully updated. Media type: `application/json`. Schema: `CodeVersion`. _Example CodeVersionSuccess: same as GET /organizations/{organizationId}/code-versions/{codeVersionId} 200 response._ Successful code version retrieval Example of a successful response returning a single code version with all properties. _Example: CodeVersionSuccess_ Successful code version retrieval Example of a successful response returning a single code version with all properties. * **400** The active code version cannot be modified. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example CodeVersionModification: same as DELETE /organizations/{organizationId}/code-versions/{codeVersionId} 400 response._ * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` * **404** Code version not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example CodeVersionIdNotFound: same as GET /organizations/{organizationId}/code-versions/{codeVersionId} 404 response._ * **409** A code version with the given ID already exists (when renaming). Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example CodeVersionIdAlreadyExists: same as PUT /organizations/{organizationId}/code-versions/{codeVersionId} 409 response._ ## 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`. ### CodeVersionResult Result containing a list of code versions. Includes all fields of `ResultBase`. * `data` (_array of CodeVersion_) List of code versions. ### 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`. ### CodeVersion A code version represents a deployable bundle of cartridge code on a Commerce Cloud instance. * `id` (_string_) The ID of the code version. Minimum length: 1. Maximum length: 256. Example: `version1`. * `active` (_boolean_) Whether this is the active code version. Example: `true`. * `cartridges` (_array of string_) A list containing the names of all cartridges participating in this code version. Items: Maximum length: 256. Example: `app_storefront_base`. _Example_ ``` [ "app_storefront_base", "app_storefront_controllers" ] ``` * `compatibilityMode` (_string_) The compatibility mode for this code version. Maximum length: 100. Example: `25.6`. * `activationTime` (_string (date-time)_) The timestamp when this code version was activated. Example: `2025-01-15T10:00:00.000Z`. * `lastModificationTime` (_string (date-time)_) The timestamp when this code version was last modified. Example: `2025-01-15T10:30:00.000Z`. * `rollback` (_boolean_) Whether this code version supports rollback. Example: `false`. * `totalSize` (_integer (int64)_) The total size of the code version in bytes. Only included when `expand=size` is requested. Example: `104857600`. * `webDavUrl` (_string_) The WebDAV URL for uploading code to this code version. Maximum length: 4000. Example: `https://example.com/on/demandware.servlet/webdav/Sites/Cartridges/version1`. ### 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) ### 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`.