Commerce App (CAP) Commands

Commands for managing Commerce App Packages (CAPs) — the standard format for distributing B2C Commerce integrations — and listing commerce features installed on an instance.

Overview

A Commerce App Package bundles cartridges, IMPEX data, and Storefront Next extensions into a single installable unit. See the Commerce Apps guide for full workflow details.

The cap list and cap tasks commands work with the broader commerce feature state system, which tracks all installed features including ISV apps, native apps, native features, and custom features.

Authentication

Install, uninstall, list, and tasks commands require OAuth authentication with OCAPI permissions and WebDAV access.

Required OCAPI Permissions

Configure these resources in Business Manager under Administration > Site Development > Open Commerce API Settings:

Resource	Methods	Commands
/jobs/*/executions	POST	cap install, cap uninstall, cap list, cap tasks
/jobs/*/executions/*	GET	cap install, cap uninstall, cap list, cap tasks
/sites	GET	cap list (when no --site-id specified)

The cap commands poll job status via GET /jobs/*/executions/*. The official Commerce Apps reference also lists /job_execution_search (POST) under the permissions for Commerce App job execution; the cap commands don't call it, but granting it lets a single OCAPI client match the full reference set.

WebDAV Access

The cap install command uploads the CAP zip to WebDAV (Impex/commerce-apps/) before triggering the install job. The cap list, cap tasks, and cap uninstall commands download site archive exports via WebDAV.

---

b2c cap validate

Validate the structure and manifest of a Commerce App Package (CAP).

Usage

b2c cap validate PATH

Arguments

Argument	Description
PATH	Path to a CAP directory or .zip file

Flags

Flag	Description
--json	Output result as JSON

Validation Checks

Errors (blocking — must fix before install):

• commerce-app.json must exist and be valid JSON
• Manifest must include id, name, version, domain fields
• version must be a valid semver string
• app-configuration/tasksList.json must exist as a valid JSON array
• Each task must have taskNumber, name, description, link
• At least one of cartridges/, storefront-next/, or impex/ must be present
• No pipeline/ directories in cartridges
• No *.ds pipeline descriptor files
• Site cartridges (cartridges/site_cartridges/) must not contain controllers/
• README.md must exist

Warnings (advisory):

• A marketplace icon is recommended. The command looks specifically for icons/icon.png; note that the Commerce Apps registry expects the icon to be named after the ISV (icons/{isv-name}.{ext}, where {ext} is png, svg, jpg, or jpeg), so a registry-ready CAP may still warn here.
• impex/uninstall/ is recommended for clean removal

Note: b2c cap validate performs local structural checks only (the items above). It enforces the manifest fields the CLI itself relies on — id, name, version, and domain — but the Commerce Apps registry additionally requires description and a publisher object (publisher.name, publisher.url, publisher.support). A CAP can therefore pass b2c cap validate and still be rejected by the registry. For registry-grade validation (manifest completeness, SHA-256, Storefront Next locale coverage, IMPEX install/uninstall pairing), use the cap-dev skills' /validate-app and the Testing & Validation guide.

Examples

# Validate a local CAP directory
b2c cap validate ./commerce-avalara-tax-app-v0.2.5

# Validate a zipped CAP
b2c cap validate ./commerce-avalara-tax-app-v0.2.5.zip

# Machine-readable output
b2c cap validate ./commerce-avalara-tax-app-v0.2.5 --json

---

b2c cap package

Package a Commerce App directory into a distributable .zip file.

Usage

b2c cap package PATH [--output PATH]

Arguments

Argument	Description
PATH	Path to the CAP source directory

Flags

Flag	Short	Description
--output PATH	-o	Output path (directory or .zip filename). Defaults to current directory.
--json		Output result as JSON

Examples

# Package to current directory
b2c cap package ./commerce-avalara-tax-app-v0.2.5

# Package to a specific output directory
b2c cap package ./commerce-avalara-tax-app-v0.2.5 --output ./dist

# Package with explicit zip filename
b2c cap package ./commerce-avalara-tax-app-v0.2.5 --output ./dist/my-app.zip

---

b2c cap install

Install a Commerce App Package on a B2C Commerce instance.

Usage

b2c cap install PATH --site-id SITE_ID

Arguments

Argument	Description
PATH	Path to a CAP directory or .zip file

Flags

Flag	Short	Description
--site-id SITE_ID	-s	Required. Site ID to install the app on
--clean-archive		Delete the uploaded zip from the instance after install
--timeout SECONDS	-t	Timeout in seconds (default: no timeout)
--skip-validate		Skip CAP structure validation before install
--create-pr		Create a pull request against the Storefront Next storefront when the app includes storefront content and a repository is connected to the storefront (default: off)
--json		Output result as JSON

Install Process

1. Validates the CAP structure (unless --skip-validate)
2. Packages the directory into a zip if a directory is provided
3. Uploads the zip to WebDAV at Impex/commerce-apps/{id}-v{version}.zip
4. Executes the sfcc-install-commerce-app system job
5. Waits for job completion
6. Archive is kept on the instance by default (use --clean-archive to remove)

Examples

# Install from a local directory
b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch

# Install from a zip
b2c cap install ./commerce-avalara-tax-app-v0.2.5.zip --site-id RefArch

# Install without running validation first
b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --skip-validate

# Remove the uploaded archive after install
b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --clean-archive

# Create a Storefront Next pull request for the app's storefront content
b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --create-pr

Creating a Storefront Pull Request

When a Commerce App includes Storefront Next content, the --create-pr flag instructs the install job to automatically open a pull request against the related Storefront Next storefront — provided a repository is also connected to the storefront. The pull request contains the storefront changes the app provides, so a developer can review and merge them rather than having them applied directly.

This flag is off by default. If the app has no storefront content, or no repository is connected to the storefront, the flag has no effect and the install proceeds normally.

b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --create-pr

---

b2c cap uninstall

Uninstall a Commerce App from a B2C Commerce instance. Looks up the app's domain automatically from the commerce feature state.

Usage

b2c cap uninstall APP_NAME --site-id SITE_ID

Arguments

Argument	Description
APP_NAME	App ID to uninstall (from commerce-app.json "id" field, e.g. avalara-tax)

Flags

Flag	Short	Description
--site-id SITE_ID	-s	Required. Site ID to uninstall the app from
--timeout SECONDS	-t	Timeout in seconds (default: no timeout)
--json		Output result as JSON

Examples

# Uninstall Avalara Tax from a site
b2c cap uninstall avalara-tax --site-id RefArch

---

b2c cap list

List commerce features installed on a B2C Commerce instance. Exports the commerce_feature_states data unit from each site and parses the results.

Usage

b2c cap list [--site-id SITE_IDS]

Flags

Flag	Short	Description
--site-id SITE_IDS	-s	Site IDs to query (comma-separated). If omitted, queries all sites.
--timeout SECONDS	-t	Timeout in seconds (default: no timeout)
--local	-l	List locally detected Commerce App Packages (no instance required)
--columns COLS	-c	Columns to display (comma-separated). Available columns: path, id, name, version, domain, siteId, featureName, featureType, featureSource, installStatus, configStatus, installedAt
--extended	-x	Show all columns including extended fields
--json		Output result as JSON

Table Columns

Column	Description
Site ID	Site the feature is installed on (includes Sites- prefix)
Name	Feature name (e.g. avalara-tax)
Type	ISV_APP, NATIVE_APP, NATIVE_FEATURE, or CUSTOM_FEATURE
Source	CUSTOM (uploaded via WebDAV) or REGISTRY (from App Registry)
Install Status	e.g. INSTALLED
Config Status	e.g. NOT_CONFIGURED, CONFIGURED
Version	Feature version if available
Installed At	Installation timestamp

JSON Output

With --json, returns the full feature state including configTasks (parsed JSON array of configuration steps) and installationMetadata (parsed JSON with job details, cartridge mappings, and IMPEX uninstall data).

Examples

# List all installed features across all sites
b2c cap list

# List features for specific sites
b2c cap list --site-id RefArch,SiteGenesis

# Machine-readable output with full details
b2c cap list --json

# List locally detected CAP directories
b2c cap list --local

---

b2c cap tasks

List configuration tasks for an installed Commerce App, with clickable links to Business Manager pages.

Usage

b2c cap tasks APP_NAME --site-id SITE_ID

Arguments

Argument	Description
APP_NAME	Commerce App feature name (e.g. avalara-tax)

Flags

Flag	Short	Description
--site-id SITE_ID	-s	Required. Site ID to query
--timeout SECONDS	-t	Timeout in seconds (default: no timeout)
--json		Output result as JSON

Examples

# Show configuration tasks for an installed app
b2c cap tasks avalara-tax --site-id RefArch

# Get tasks as JSON (includes full feature state)
b2c cap tasks avalara-tax --site-id RefArch --json

---

b2c cap pull

Pull installed Commerce App source packages from a B2C Commerce instance. By default, pulls all registry-sourced apps. Optionally specify a single app by name.

Useful for deploying cartridges to a code version or working with Storefront Next extensions locally.

Usage

b2c cap pull [APP_NAME] [--site-id SITE_ID] [--output DIR]

Arguments

Argument	Description
APP_NAME	(optional) Commerce App feature name to pull (e.g. avalara-tax). If omitted, pulls all registry apps.

Flags

Flag	Short	Description
--site-id SITE_ID	-s	Site ID to query for installed apps. If omitted, queries all sites.
--output DIR	-o	Output directory (default: ./commerce-apps)
--timeout SECONDS	-t	Timeout in seconds (default: no timeout)
--json		Output result as JSON

Examples

# Pull all registry apps to ./commerce-apps
b2c cap pull

# Pull a specific app by name
b2c cap pull avalara-tax

# Pull to a custom output directory
b2c cap pull --output ./my-apps

# Pull apps installed on a specific site
b2c cap pull --site-id RefArch