Commerce Apps (CAPs)

Commerce App Packages (CAPs) are the standard format for distributing B2C Commerce integrations. A CAP bundles cartridges, IMPEX configuration data, and Storefront Next UI extensions into a single installable unit.

What Is a Commerce App Package?

A CAP can contain any combination of:

• Back-end cartridges — site cartridges implementing extension points (e.g., sf.commerce.app.tax.calculate) and BM cartridges for admin UI
• IMPEX data — services, site preferences, custom object definitions, and uninstall cleanup scripts
• Storefront Next extensions — React components injected into the storefront via UI targets
• App configuration — tasksList.json defining the post-install setup wizard in Business Manager

CAP Directory Structure

commerce-{app}-v{version}/
├── commerce-app.json          # Required: app manifest (id, name, version, domain)
├── README.md                  # Required: documentation
├── app-configuration/
│   └── tasksList.json         # Required: post-install configuration wizard
├── cartridges/
│   ├── bm_cartridges/         # Business Manager cartridges (may have controllers/)
│   └── site_cartridges/       # Site cartridges (no controllers/, no pipelines)
├── icons/
│   └── icon.png               # Recommended: marketplace icon
├── impex/
│   ├── install/               # Data imported on install
│   └── uninstall/             # Recommended: cleanup data for removal
└── storefront-next/
    └── src/extensions/        # React components and target-config.json

Development Workflow

1. Build and Organize Your CAP

Structure your project following the CAP layout above. The commerce-app.json manifest is required:

{
  "id": "my-integration",
  "name": "My Integration",
  "version": "1.0.0",
  "domain": "tax",
  "description": "Automated tax compliance",
  "publisher": {
    "name": "My Company",
    "url": "https://example.com"
  }
}

2. Validate

Run validation before packaging or installing to catch structural issues early:

b2c cap validate ./commerce-my-integration-v1.0.0

Validation checks include:

• Required files (commerce-app.json, README.md, tasksList.json)
• Valid manifest schema and semver version
• No pipelines or .ds files (not supported in CAPs)
• Site cartridges must not have controllers/ (use extension points instead)

3. Package (Optional)

Create a distributable zip for CI/CD pipelines or registry submission:

b2c cap package ./commerce-my-integration-v1.0.0 --output ./dist

This creates dist/my-integration-v1.0.0.zip with the correct root directory structure.

4. Install on a Sandbox

Install the CAP on a sandbox instance for testing. Provide the local directory or zip:

# From a directory
b2c cap install ./commerce-my-integration-v1.0.0 --site RefArch

# From a zip
b2c cap install ./dist/my-integration-v1.0.0.zip --site RefArch

The CLI uploads the package to WebDAV (Temp/) and triggers the sfcc-install-commerce-app platform job, which deploys cartridges, imports IMPEX data, and creates a Storefront Next PR (if applicable).

5. Complete Configuration Tasks

After install, complete the setup wizard tasks in Business Manager or via CLI. Installed apps transition through:

INSTALLING → INSTALLED → CONFIGURING → ACTIVE

6. Uninstall

To remove an installed app:

b2c cap uninstall my-integration --domain tax --site RefArch

VS Code Extension Integration

The B2C DX VS Code extension provides Commerce App support directly in the file explorer.

CAP Directory Detection

Any directory containing a commerce-app.json file is automatically decorated with a CA badge in the VS Code explorer, making CAP directories easy to identify.

Install from the Explorer

Right-click any CAP directory in the VS Code explorer and choose B2C-DX → Install Commerce App (CAP). You will be prompted for the target site ID.

Authentication Requirements

Install and uninstall commands require:

• OAuth credentials (SFCC_CLIENT_ID, SFCC_CLIENT_SECRET) — for running the system job
• WebDAV credentials (SFCC_USERNAME, SFCC_PASSWORD) — for uploading the CAP zip

export SFCC_HOSTNAME=my-instance.commercecloud.salesforce.com
export SFCC_CLIENT_ID=your-client-id
export SFCC_CLIENT_SECRET=your-client-secret
export SFCC_USERNAME=your-bm-username
export SFCC_PASSWORD=your-webdav-access-key

See the Authentication Guide for complete setup instructions.

CI/CD Integration

A typical CI/CD pipeline for Commerce App deployment:

- name: Validate CAP
  run: b2c cap validate ./commerce-my-integration-v${{ env.VERSION }}

- name: Package CAP
  run: b2c cap package ./commerce-my-integration-v${{ env.VERSION }} --output ./dist

- name: Install CAP
  run: b2c cap install ./dist/my-integration-v${{ env.VERSION }}.zip --site ${{ env.SITE_ID }}
  env:
    SFCC_HOSTNAME: ${{ secrets.SFCC_HOSTNAME }}
    SFCC_CLIENT_ID: ${{ secrets.SFCC_CLIENT_ID }}
    SFCC_CLIENT_SECRET: ${{ secrets.SFCC_CLIENT_SECRET }}
    SFCC_USERNAME: ${{ secrets.SFCC_USERNAME }}
    SFCC_PASSWORD: ${{ secrets.SFCC_PASSWORD }}

Reference

• CAP CLI Commands — full command reference
• ISV Developer Guide — CAP structure specification and domain extension points