Architecture Overview

Understand the Commerce Apps framework, extension points, and packaging structure.

Commerce Apps are the “feature packaging” layer that allows merchants to apply native or third-party customizations to their site and storefront. Commerce Apps support both backend and frontend (Storefront Next) code. The framework uses a centralized Commerce App Registry hosted on GitHub to provide a smooth installation experience. It bridges the gap between third-party service logic and the storefront through automated metadata, code, and UI orchestration.

Note: The examples in this guide focus on the tax domain, but the same architectural patterns and automation workflows apply identically to all other merchant service categories (for example, address verification, ratings & reviews, and shipping).

Commerce Apps are organized in a hierarchy:

Domains are the top-level commerce categories: Payments, Tax, Shipping, Ratings & Reviews, Loyalty, Fraud, and so on. Each domain represents a functional feature area of a commerce application.

Storefront extensions are UI features within a domain that merchants can turn on individually. For example, the Shipping domain has separate storefront extensions for Delivery Estimation and Shipping Options & Calculations, allowing merchants to turn on only the features they need.

UI targets are named landing zones on Storefront Next pages where components render. Each extension contains one or more components that can target defined UI targets across different storefront surfaces (PDP, PLP, Cart, Checkout, My Account, and so on). Targets follow a semantic namespace: {namespace}.{surface}.{domain}.{feature}.

Components are the React elements that render within each UI target. They can come from the platform (as pre-built Storefront Next components) or from an ISV extension (replacing the platform component).

Example: The Ratings & Reviews domain includes extensions for Star Rating, Review Summary, Reviews List, Q&A, and Review Purchase. The Star Rating extension has UI targets on PDP (sfcc.pdp.reviews.rating), Product Card (shared), and Quick Add. Each target renders a component that displays the aggregate star rating for a product.

There are three distinct architectures for building a Commerce App. Each architecture determines what goes into your Commerce App Package (CAP). The right one depends on your domain, your needs, and what platform capabilities you want to leverage.

Your Commerce App delivers only Storefront Next extensions — React components that replace or extend platform UI targets. There is no backend cartridge or IMPEX in your CAP. This architecture is appropriate when the platform already provides the backend APIs you need, and you only want to customize the shopper-facing experience.

Your CAP includes the storefront-next/ and app-configuration/ directories, but no cartridges/ or impex/ directories.

Your Commerce App delivers only backend cartridges and IMPEX configuration — no Storefront Next extensions. This architecture is appropriate when the platform already provides the frontend components and a formal backend interface contract, and you only need to supply the backend logic that fulfills that contract.

You implement platform-defined extension point hooks (for example, sfcc.app.tax.calculate, sfcc.app.tax.commit, sfcc.app.tax.cancel). The platform provides both the frontend components and the extension point interface — you only need to implement the script API endpoints. This is the most turnkey approach, but it requires the platform to have defined extension points for your domain. Currently, only the Tax domain has extension points, with additional domains planned for later in 2026.

Your CAP includes the cartridges/, impex/, and app-configuration/ directories but no storefront-next/ directory.

Your Commerce App delivers both Storefront Next extensions and backend cartridges. You own the full stack for your feature: frontend components, backend SCAPI or service integrations, and all data handling. This architecture gives you full creative and functional control over both the UX and the data layer.

Your CAP includes the storefront-next/, cartridges/, impex/, and app-configuration/ directories.

There are two sub-types of fullstack apps:

You replace the platform’s default UI components with your own Storefront Next extensions, and your backend implements platform-defined extension point hooks. The platform defines the backend interface contract — you supply the hook implementations that fulfill it. This sub-type is available for domains where the platform has defined formal extension points.

You replace the platform’s default UI components with your own Storefront Next extensions, and your backend is a custom SCAPI that supplies data to those components. No platform-defined extension points are required — you define your own API contract. This sub-type is available for any domain, even if the platform hasn’t defined formal extension points yet.

A CAP is a standardized .zip file with the following directory layout:

Commerce Apps introduce domain-specific extension points that replace the legacy shared hooks (both business defined hooks like dw.order.calculate and general before/after SCAPI hooks). This eliminates code conflicts where multiple integrations (for example, two tax providers) compete for the same hook.

Note: Only Tax extension points are live in April 2026. Shipping, Fraud, and other domain interface extension points arrive in the second half of 2026. See Supported Domains for the full domain timeline.

The UI Targets framework is how Commerce Apps deliver frontend components to the storefront. It is a build-time mechanism, not a runtime injection.

How it works: The core Storefront Next application defines explicit placeholders using <UITarget targetId="..." /> React components. These contain no business logic and serve only as injection points. During the build process, a Vite plugin replaces UITarget entries with the actual React components specified in the extension’s target-config.json.

Naming convention: Platform-defined targets use the sfcc namespace: sfcc.{surface}.{domain}.{feature}. For example, sfcc.pdp.reviews.rating identifies the star rating component location on the product detail page.

Custom namespaces: SI partners and customers can create their own UI targets with their own namespace prefix (not sfcc). This makes the target’s framework extensible beyond platform-defined locations.

Installation mechanism: When a Commerce App is installed, the install job processes the storefront-next/ directory from the CAP and creates a pull request against the merchant’s Storefront Next repository. The PR includes the extension code and target configuration. The branch is named commerce-app-install/{app-name}/{version}/{site-id} and the PR title follows the pattern [Commerce App] Add {app-name} {version} storefront UI. A “Merge Storefront PR” task is automatically prepended to the merchant’s configuration task list. ISV components become part of the merchant’s build after the PR is merged.

Manual integration: If the merchant prefers not to use the automated pull request flow (for example, when installing from Business Manager without GitHub integration configured), they can use b2c cap pull to download the installed app package. The storefront-next/ extensions and cartridges/ can then be reviewed and integrated into the merchant’s storefront and cartridge projects through their standard source control and deployment processes. See b2c cap pull for details.

Commerce App installation is tracked at the site level but the app’s artifacts are deployed at the instance level. Cartridges, service definitions, custom object types, and other instance-scoped resources are shared across all sites on the instance. However, each site has its own installation record (CommerceFeatureState), its own cartridge path entry, and its own configuration state. This means a merchant installs an app per site, but the underlying code and instance resources are only deployed once and shared.

The standard lifecycle from installation through activation:

INSTALLING → INSTALLED → NOT_CONFIGURED → CONFIGURING → CONFIGURED

• INSTALLING: The platform is processing the CAP. It unpacks the archive, deploys cartridges to the active code version, executes IMPEX data imports, and creates a GitHub PR for storefront components.
• INSTALLED: Code is deployed and metadata is imported, but the app isn’t yet active. The merchant needs to complete configuration tasks.
• NOT_CONFIGURED: The app is installed but configuration has not yet started. The merchant needs to open the setup wizard to begin.
• CONFIGURING: The merchant has started but not yet finished the setup wizard (defined by tasksList.json). Tasks might include verifying API credentials, setting site preferences, or running a test transaction.
• CONFIGURED: All configuration tasks are complete. The platform automatically transitions to this state when the last task is marked complete. The app is now active and the app extension point hooks begin executing.

• INSTALLING → INSTALL_FAILED — The installation job encountered an error. Check system job logs for details.
• CONFIGURING → CONFIGURATION_FAILED — Configuration encountered an error during the setup process.

Any post-install state (INSTALLED, NOT_CONFIGURED, CONFIGURING, or CONFIGURED) can transition to UNINSTALLING:

{any post-install state} → UNINSTALLING → UNINSTALLED

• UNINSTALLING: The platform is removing the app. This includes removing cartridges from the site’s cartridge path, and — if this is the last site using the app — deleting cartridge files, disabling feature toggles, and executing uninstall IMPEX.
• UNINSTALLED: The app has been successfully removed from the site.
• UNINSTALL_FAILED: The uninstallation job encountered an error (UNINSTALLING → UNINSTALL_FAILED). Check system job logs for details.

State is tracked per-site in the CommerceFeatureState system object. Site A can have an app fully configured while Site B is still in progress, even though they share the same code baseline.

Install Commerce Apps using either method:

Business Manager (no-code): Navigate to the Cart & Checkout Hub in Business Manager, select a Commerce App, and click Install. The platform handles everything automatically. After installation, you’re redirected to a configuration task list.

CLI (pro-code): Use the B2C CLI to validate your CAP (b2c cap validate), package it (b2c cap package), and install it on a target instance (b2c cap install). The CLI handles packaging, WebDAV upload, and job execution automatically. See Development Environment Setup for the full command reference.