Commerce Apps (CAPs)

Commerce App Packages (CAPs) are the standard format for distributing B2C Commerce integrations. A CAP bundles back-end cartridges, IMPEX configuration data, and Storefront Next UI extensions into a single installable unit, deployed to an instance with a platform job.

This page covers what the B2C CLI does for CAPs and the agent skills we recommend. It is intentionally brief: the Commerce Apps ISV Developer Guide on Salesforce Developers is the authoritative source for the CAP format, manifest schema, architectures, domains and extension points, the installation state machine, and the submission/registry process. Use this page for the CLI workflow; follow the links for the spec.

Develop CAPs with AI Agent Skills

If you build CAPs with an AI coding agent, install the agent skills so it understands the CAP format, the b2c cap commands, and the scaffolding/packaging/submission workflow. We recommend three plugins:

• b2c-cli — the b2c cap commands (validate, package, install, uninstall, list, tasks, pull) and the rest of the CLI.
• b2c — the B2C Commerce development patterns CAPs are built from (cartridges, hooks, metadata, Custom APIs, Storefront Next extensions).
• cap-dev — scaffolding, generating IMPEX, validating, and submitting CAPs to the registry.

b2c-cli and b2c ship in the B2C Developer Tooling marketplace; cap-dev ships separately from the SalesforceCommerceCloud/commerce-apps registry repository.

Claude Code

# B2C Developer Tooling skills (the CLI + platform development patterns)
claude plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling
claude plugin install b2c-cli
claude plugin install b2c

# CAP authoring skills (separate marketplace)
claude plugin marketplace add SalesforceCommerceCloud/commerce-apps
claude plugin install cap-dev --scope project

Add --scope project to any install to scope it to the current project instead of your user profile. The b2c-cli and b2c skills also install via b2c setup skills, and the cap-dev skills via b2c setup skills cap-dev for other agents (Cursor, Codex, Copilot). For full plugin management — listing, updating, and uninstalling — see the Agent Skills & Plugins guide.

Which tool for what? Use the cap-dev skills to author a CAP (scaffold the structure, generate IMPEX, validate against the registry rules, and open a submission PR). Use the B2C CLI to operate on a CAP against an instance (validate locally, package, install, uninstall, list, and pull).

CLI Workflow

The B2C CLI provides the cap topic for working with Commerce App Packages. The commands accept a CAP directory or a packaged .zip.

# Validate structure locally (no instance required)
b2c cap validate ./commerce-my-integration-app-v1.0.0

# Package into a distributable zip (no instance required)
b2c cap package ./commerce-my-integration-app-v1.0.0 --output ./dist

# Install on a sandbox (uploads via WebDAV, then runs the install job)
b2c cap install ./commerce-my-integration-app-v1.0.0 --site RefArch

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

# List apps installed on an instance (add --local to list CAP directories on disk)
b2c cap list --site RefArch

# View post-install configuration tasks (with Business Manager deep links)
b2c cap tasks my-integration --site RefArch

# Pull installed app sources for cartridge or Storefront Next development
b2c cap pull my-integration --site RefArch

# Uninstall (the app's domain is discovered automatically)
b2c cap uninstall my-integration --site RefArch

validate and package (and list --local) are local-only and need no credentials, which makes them well-suited to CI. install, uninstall, tasks, pull, and remote list run a system job and/or query the instance, so they require authentication — see Authentication Requirements. On install, the CLI uploads the package via WebDAV to Impex/commerce-apps/ and triggers the sfcc-install-commerce-app platform job, which deploys cartridges and imports IMPEX data.

See the CAP CLI reference for every command, flag, and option.

Creating a Storefront Pull Request

If a CAP includes Storefront Next content, pass --create-pr on install to have the install job automatically open a pull request against the related Storefront Next storefront — provided a repository is also connected to the storefront:

b2c cap install ./commerce-my-integration-app-v1.0.0 --site RefArch --create-pr

The pull request contains the storefront changes the app provides, so a developer can review and merge them rather than having them applied directly. The flag is off by default; if the app has no storefront content or no repository is connected to the storefront, it has no effect.

Inspecting Installed State

After install, complete the setup wizard tasks in Business Manager or follow the deep links from b2c cap tasks. b2c cap list reports each installed app's install status and configuration status per site. For the full installation state machine (the INSTALLING → INSTALLED → NOT_CONFIGURED → CONFIGURING → CONFIGURED happy path plus the error and uninstall flows), see the Architecture guide.

VS Code Extension Integration

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

• CAP detection — any directory containing a commerce-app.json file is decorated with a CA badge in the explorer, making CAP directories easy to identify.
• Install from the explorer — right-click a CAP directory and choose B2C-DX → Install Commerce App (CAP). You will be prompted for the target site ID.

Authentication Requirements

The remote cap commands (install, uninstall, tasks, pull, and remote list) require both:

• OAuth credentials (SFCC_CLIENT_ID, SFCC_CLIENT_SECRET) — for running the system job via OCAPI
• WebDAV credentials (SFCC_USERNAME, SFCC_PASSWORD) — for uploading the CAP zip (there is no SCAPI substitute for the WebDAV upload)

export SFCC_SERVER=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

You can also authenticate WebDAV interactively in the browser with --user-auth. The local-only commands (validate, package, list --local) need no credentials. See the Authentication Guide for complete setup, including Account Manager OAuth clients with WebDAV permissions.

CI/CD Integration

Because validate and package are local-only, a typical pipeline validates and packages on every change and installs to a dedicated sandbox on promotion. All cap commands accept --json for machine-readable output.

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

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

- name: Install CAP
  run: b2c cap install ./dist/my-integration-v${{ env.VERSION }}.zip --site ${{ env.SITE_ID }} --json
  env:
    SFCC_SERVER: ${{ secrets.SFCC_SERVER }}
    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 b2c cap command and flag reference
• Commerce Apps ISV Developer Guide — the authoritative CAP specification, covering:
  • Architecture — the three app architectures, extension points (e.g. sfcc.app.tax.calculate), UI targets, CAP directory structure, and the installation state machine
  • Development environment — sandbox setup, the cap-dev Claude Code skills, and the end-to-end lifecycle
  • Packaging — required files, the commerce-app.json manifest, and zip layout
  • Testing & validation and submission & review — the registry review checklist and submission process