Reference

Technical reference for Commerce Apps APIs, data models, and terminology.

Every Commerce App Package must include a commerce-app.json file at the root of the CAP directory. This file defines the app’s identity and must match the corresponding entry in the App Registry manifest.

Publisher object:

Example:

Important: The version and domain fields in commerce-app.json must match the corresponding entry in the App Registry root manifest (commerce-apps-manifest/manifest.json). A mismatch causes CI validation to fail.

The following APIs support Commerce App lifecycle management:

Commerce App installation and uninstallation are driven by system jobs executed via the OCAPI Data API.

Base URL: /s/-/dw/data/v{version}/jobs/{job_id}/executions

Install Job ID: sfcc-install-commerce-app

Uninstall Job ID: sfcc-uninstall-commerce-app

Jobs are triggered via POST to the executions endpoint with parameters in the request body. The B2C CLI handles this automatically, but the underlying API can also be called directly.

Your API client must have the following OCAPI Data API resources configured in Business Manager (Administration > Site Development > Open Commerce API Settings):

These are the same permissions used by all B2C CLI job operations. For a complete OCAPI configuration example, see the B2C CLI Authentication Guide.

Note: cap install also requires WebDAV access in addition to OCAPI. See Development Environment Setup — WebDAV Access.

Example request:

Note: When using the B2C CLI (b2c cap install), the CLI handles packaging, WebDAV upload, and job execution automatically. You don’t need to call this API directly.

Example request:

Both install and uninstall jobs return a standard OCAPI job execution object. The CLI polls the execution status until the job completes or fails. Key response fields:

The CommerceFeatureState system object tracks installation and configuration status for each Commerce App per site.

The FeatureType field is derived from the type and provider fields in the App Registry manifest:

The CommerceFeatureState record is per-site. A single app can be installed on multiple sites within the same realm. Key multi-site behaviors:

• Cartridge copying: The install job copies cartridges to the active code version on the first site install. Subsequent site installs skip the copy if the cartridges already exist in the active code version.
• Cartridge path: Each site gets its own cartridge path entry, managed independently.
• IMPEX processing: Install IMPEX runs for every site install. Uninstall IMPEX only runs when the last site uninstalls the app, because services, jobs, and custom object definitions are instance-scoped resources shared across all sites.
• Cartridge file deletion: Cartridge files are only deleted from the active code version when the last site uninstalls the app.
• Feature toggles: Toggle disablement is also deferred until the last site uninstalls.

The platform automatically manages feature toggles during Commerce App installation and uninstallation. You don’t need to configure these manually — the install job enables them and the uninstall job disables them.

When a tax Commerce App is installed, the platform automatically enables the following toggles:

On uninstall, only TaxAppHooksEnabled is disabled (and only when the last tax app is removed from all sites). ScapiHookExecutionEnabled and MultilevelTax are left enabled because they may be needed by other platform features.

Note: These toggles serve as kill switches. If a Commerce App tax hook is misbehaving in production, internal support can disable TaxAppHooksEnabled without a code deployment to fall back to standard tax behavior.

The install job (sfcc-install-commerce-app) executes these steps in order:

1. Feature toggle check: Verifies CommerceAppsEnabled is enabled on the instance.
2. Manifest validation: Checks that the app name and domain exist in the App Registry manifest.
3. Idempotency check: If the app is already installed on this site, the job skips installation and returns success. If cartridges are missing from the active code version (for example, after a code version switch), the job re-copies them without re-running IMPEX.
4. Resolve site, library, and code version: Validates the target site exists, resolves the site’s content library ID (for LIBRARYID placeholder), and locates the active code version.
5. Write INSTALLING state.
6. Fetch and unzip CAP: Downloads the .zip from WebDAV or the App Registry and extracts it to a temporary directory.
7. Read tasksList.json: Parses post-install configuration tasks from the CAP.
8. Copy cartridges: Copies site_cartridges/ and bm_cartridges/ to the active code version directory. Skips copying if the app is already installed on another site and the cartridges are already present.
9. Update cartridge paths: Prepends site cartridges to the site’s cartridge path and adds BM cartridges to the Business Manager cartridge path.
10. Process install IMPEX: Replaces SITEID and LIBRARYID placeholders, zips the processed files, and executes a Site Import in merge mode.
11. Serialize uninstall IMPEX: Persists the contents of impex/uninstall/ into the CommerceFeatureState record so they’re available at uninstall time (the CAP isn’t needed for uninstall).
12. Enable feature toggles: For tax apps, enables TaxAppHooksEnabled, ScapiHookExecutionEnabled, and MultilevelTax.
13. Create storefront PR (optional): If storefront-next/ is present and should_create_pr is true, creates a GitHub PR against the merchant’s Storefront Next repository. A “Merge Storefront PR” task is automatically prepended to the configuration task list.
14. Write INSTALLED state.

On failure at any step, the job writes INSTALL_FAILED, removes cartridges from paths, and cleans up copied cartridge files.

The uninstall job (sfcc-uninstall-commerce-app) executes these steps:

1. Feature toggle check: Verifies CommerceAppsEnabled is enabled.
2. Idempotency check: Verifies the app is currently installed on the target site and no uninstall is already in progress.
3. Read persisted state: Reads installed cartridge names and serialized uninstall IMPEX data from the CommerceFeatureState record before writing the UNINSTALLING state (which overwrites some metadata fields).
4. Write UNINSTALLING state.
5. Remove cartridges from paths: Removes site cartridges from the site’s path and BM cartridges from the BM path. On partial failure, attempts to restore the site cartridge path.
6. Delete cartridge files (last site only): If this is the last site using the app, deletes the cartridge directories from the active code version.
7. Disable feature toggles (last site only): For tax apps, disables TaxAppHooksEnabled.
8. Process uninstall IMPEX (last site only): Reconstructs the uninstall IMPEX files from persisted state, replaces placeholders, and executes a Site Import in merge mode. This step is intentionally ordered last because it’s irreversible.
9. Write UNINSTALLED state.

Important: The uninstall job does not require access to the original CAP archive. All data needed for uninstall is read from the CommerceFeatureState record that was persisted during installation.

The App Registry uses a root manifest (commerce-apps-manifest/manifest.json) to define all available apps. The manifest organizes apps by domain, with each domain containing an array of app entries.

The manifest supports three entry types:

• app (ISV or Salesforce apps): Installable Commerce App Packages with version, zip, and sha256 fields. These go through the full CAP install flow.
• feature (native platform features): Built-in features like Flat Tax or Basic Shipping that are configured directly in Business Manager via a configurationUrl. No CAP install is needed.
• custom (custom provider placeholders): Placeholders that let merchants configure their own custom integrations. No CAP install is needed.

Provider domains (tax, payment, shipping) display under “Providers” in the Cart & Checkout Hub. All other domains display under “Additional Setup”. Multiple entries within the same domain appear as provider options under a single hub tile.

The following limitations apply to Commerce Apps:

• Commerce Apps are designed exclusively for Storefront Next. SiteGenesis and SFRA storefronts aren’t supported.
• SiteGenesis cartridges (sitegenesis_storefront_controllers, sitegenesis_storefront_core) and SFRA cartridges (app_storefront_base) override the dw.order.calculate hook, which bypasses Commerce App tax hook selection entirely. These cartridges must be removed from the site’s cartridge path before installing a tax Commerce App.
• Hybrid setups (Storefront Next with SiteGenesis/SFRA cartridges still on the path) will produce unpredictable behavior for Commerce App extension points.

• Only Tax extension points (sfcc.app.tax.calculate, sfcc.app.tax.commit, sfcc.app.tax.cancel) are live in the initial release. Shipping, Fraud, and other adapter interface extension points arrive in the second half of 2026.
• Only one Commerce App can be the active provider for a given domain per site. Installing a second tax app on the same site will overwrite the first.
• Legacy hooks (dw.order.calculateTax) and Commerce App extension points are mutually exclusive per site. When TaxAppHooksEnabled is active, the platform calls the registered Commerce App hook instead of the legacy hook.

• No in-place upgrades. To update to a new version, merchants must uninstall the old version and install the new one. Automated version upgrades are planned for Wave 3.
• No rollback mechanism. After uninstalling, there is no one-click way to restore the previous version. Merchants must re-install the desired version.

• Cartridge files are shared across sites at the code version level. You can’t run different versions of the same Commerce App on different sites within the same realm.
• Instance-scoped resources (service definitions, custom object type definitions) are shared across all sites. Uninstall IMPEX only runs when the last site uninstalls the app.

• Extensions are incorporated via a GitHub Pull Request at install time. The merchant must manually merge the PR and rebuild their storefront.
• There is no automated mechanism to remove storefront extension code on uninstall. Merchants must manually remove the extension files from their Storefront Next repository.

• B2C CLI Documentation
• B2C Commerce API Documentation
• SCAPI Getting Started
• Web Services in B2C Commerce

• CAP (Commerce App Package): The standardized .zip archive containing all artifacts for a Commerce App.

• Extension Point: A platform-defined interface, such as sfcc.app.tax.calculate, where ISV logic can be injected.

• Hook: The script implementation that fulfills an extension point contract.

• UI Target: A named set of feature components in Storefront Next that can be injected at build time.

• Extension: An independently toggleable UI plugin feature containing one or more UI targets and associated components.

• App Registry: The centralized GitHub repository hosting certified Commerce App packages.

• CommerceFeatureState: The system object tracking installation and configuration status per-site.

• SCAPI: Salesforce Commerce API, the RESTful API layer for Commerce Cloud.

• OCAPI: Open Commerce API, the Data API used for job execution and Business Manager operations.

• Storefront Next (Odyssey): The React-based storefront framework for Commerce Cloud.

• BFF (Backend for Frontend): The pattern where a custom SCAPI serves as the intermediary between ISV front-end components and ISV back-end services.

• B2C CLI: The command-line interface for B2C Commerce development and operations, including Commerce App lifecycle management.

• Manifest: The root manifest.json file in the App Registry that defines all available Commerce Apps, native features, and custom provider placeholders.