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

bash

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

bash

# 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

bash

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

bash

# 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

bash

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

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

Examples

bash

# 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.

bash

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

bash

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

bash

# 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

bash

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

bash

# 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

bash

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

bash

# 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

bash

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

bash

# 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

Commerce App (CAP) Commands ​

Overview ​

Authentication ​

Required OCAPI Permissions ​

WebDAV Access ​

b2c cap validate ​

Usage ​

Arguments ​

Flags ​

Validation Checks ​

Examples ​

b2c cap package ​

Usage ​

Arguments ​

Flags ​

Examples ​

b2c cap install ​

Usage ​

Arguments ​

Flags ​

Install Process ​

Examples ​

Creating a Storefront Pull Request ​

b2c cap uninstall ​

Usage ​

Arguments ​

Flags ​

Examples ​

b2c cap list ​

Usage ​

Flags ​

Table Columns ​

JSON Output ​

Examples ​

b2c cap tasks ​

Usage ​

Arguments ​

Flags ​

Examples ​

b2c cap pull ​

Usage ​

Arguments ​

Flags ​

Examples ​

Commerce App (CAP) Commands

Overview

Authentication

Required OCAPI Permissions

WebDAV Access

b2c cap validate

Usage

Arguments

Flags

Validation Checks

Examples

b2c cap package

Usage

Arguments

Flags

Examples

b2c cap install

Usage

Arguments

Flags

Install Process

Examples

Creating a Storefront Pull Request

b2c cap uninstall

Usage

Arguments

Flags

Examples

b2c cap list

Usage

Flags

Table Columns

JSON Output

Examples

b2c cap tasks

Usage

Arguments

Flags

Examples

b2c cap pull

Usage

Arguments

Flags

Examples