Packaging Your Commerce App

Package your Commerce App into a CAP (Commerce App Package) for distribution.

CAP Structure Requirements

Your packaged Commerce App must conform to the CAP structure defined in Architecture Overview. The ZIP must contain a single root directory named commerce-{app-name}-app-v{version}/ and contain only the recognized subdirectories.

Required Files

commerce-app.json at the root of the package (see commerce-app.json Schema)
README.md at the root of the package
app-configuration/tasksList.json defining the setup wizard
icons/ directory with at least one icon file named {isv-name}.{ext} (PNG, SVG, JPG, or JPEG)
At least one of: cartridges/ (back-end logic), storefront-next/ (frontend extensions), or impex/ (configuration data)

Optional Files

app-configuration/adminComponents.json — declares Business Manager admin UI components shown to merchants after install. Use this to ship storefrontComponentVisibility toggles that let merchants enable or disable individual UI targets. See adminComponents.json Schema for the field reference and a complete example.
app-configuration/translations/<locale>.json — localized strings for tasksList.json and (when shipped) adminComponents.json. See App-shipped string localization.

The tasksList.json

This file defines the post-install configuration steps that appear in the Business Manager setup wizard. Each task has a stable taskKey, a task number, name, description, a deep link to the relevant BM page, and an initial status. The taskKey must be a unique snake_case identifier (matching ^[a-z][a-z0-9_]*$); locale files reference it to translate the name and description fields. See App-shipped string localization.

Example:

1[
2  {
3    "taskKey": "enable_tax_service",
4    "taskNumber": 1,
5    "name": "Enable Tax Service",
6    "description": "Navigate to Site Preferences and enable the tax calculation service",
7    "link": "/on/demandware.store/Sites-Site/default/ViewApplication-BM?..."
8  },
9  {
10    "taskKey": "configure_api_credentials",
11    "taskNumber": 2,
12    "name": "Configure API Credentials",
13    "description": "Enter your account ID and license key in site preferences",
14    "link": "/on/demandware.store/Sites-Site/default/ViewApplication-BM?..."
15  }
16]

Localizing app-shipped strings

To render tasksList.json and adminComponents.json strings in additional locales, ship locale files under app-configuration/translations/. Each locale file uses two reserved top-level namespaces — tasks (keyed by taskKey) and adminComponents (keyed by componentKey) — and Business Manager falls back to literal English when no translation is shipped. en-US.json is required if the directory exists. See App-shipped string localization for the full schema, supported locales, fallback chain, and CI validation rules.

IMPEX Structure

The impex/ directory contains site-scoped XML organized into install/ and uninstall/ subdirectories. The install/ directory is processed during app installation; the uninstall/ directory during removal.

Within install/, use standard Commerce Cloud IMPEX conventions:

jobs.xml for job definitions
services.xml for service credentials, profiles, and definitions
meta/system-objecttype-extensions.xml for system object attribute extensions
meta/custom-objecttype-definitions.xml for custom object type definitions
sites/SITEID/preferences.xml for site preferences

Placeholder Replacement

The install job automatically replaces SITEID and LIBRARYID placeholders in both file paths and file content during processing. Placeholder replacement applies to the following text file types: .xml, .csv, .txt, .json, .properties, .js. Binary files are copied as-is without replacement.

Use SITEID in directory paths (for example, sites/SITEID/preferences.xml) and inside XML content for site-scoped data.
Use LIBRARYID for content library references. The library ID is resolved from the target site’s content library at install time.
Empty text files are skipped during processing.

Example placeholder usage in preferences.xml:

1<?xml version="1.0" encoding="UTF-8"?>
2<preferences xmlns="http://www.demandware.com/xml/impex/preferences/2007-12-31">
3    <custom-preferences>
4        <custom-preference preference-id="myAppEnabled"
5            site-id="SITEID">true</custom-preference>
6    </custom-preferences>
7</preferences>

Install IMPEX

Install IMPEX files are processed via Site Import in merge mode, meaning they add or update data without deleting existing resources. Use placeholder credentials in service definitions — merchants configure real credentials during the post-install setup tasks.

Example impex/install/services.xml:

1<?xml version="1.0" encoding="UTF-8"?>
2<services xmlns="http://www.demandware.com/xml/impex/services/2014-09-26">
3    <service-credential service-credential-id="myapp.api.cred">
4        <url>https://api.example.com</url>
5        <user-id>YOUR_API_KEY</user-id>
6        <password>YOUR_API_SECRET</password>
7    </service-credential>
8    <service-profile service-profile-id="myapp.api.profile">
9        <timeout-millis>5000</timeout-millis>
10        <rate-limit-enabled>true</rate-limit-enabled>
11        <rate-limit-calls>10</rate-limit-calls>
12        <rate-limit-millis>1000</rate-limit-millis>
13    </service-profile>
14    <service service-id="myapp.api">
15        <service-type>HTTP</service-type>
16        <enabled-flag>true</enabled-flag>
17        <service-credential service-credential-id="myapp.api.cred"/>
18        <service-profile service-profile-id="myapp.api.profile"/>
19    </service>
20</services>

Important: Use dotted notation for service IDs (for example, myapp.api) and camelCase with an app prefix for attribute IDs (for example, myAppEnabled). Don’t hardcode production credentials.

Uninstall IMPEX

The impex/uninstall/ directory contains XML files that clean up resources when the app is removed. Use mode="delete" in uninstall IMPEX files to remove services, profiles, and credentials.

During installation, the platform serializes the contents of impex/uninstall/ and persists them in the CommerceFeatureState record. At uninstall time, the platform reconstructs these files from persisted state — the original CAP archive isn’t needed for uninstall.

Deletion order matters: Delete in this order to respect foreign key relationships: service → profile → credential.

Example impex/uninstall/services.xml:

1<?xml version="1.0" encoding="UTF-8"?>
2<services xmlns="http://www.demandware.com/xml/impex/services/2014-09-26">
3    <service service-id="myapp.api" mode="delete"/>
4    <service-profile service-profile-id="myapp.api.profile" mode="delete"/>
5    <service-credential service-credential-id="myapp.api.cred" mode="delete"/>
6</services>

Note: Uninstall IMPEX only runs when the last site uninstalls the app, because services and custom object definitions are instance-scoped resources shared across all sites. See Multi-Site Behavior for details.

Naming Conventions

Resource	Convention	Example
Service IDs	Dotted notation	`avalara.tax.api`
Attribute IDs	camelCase with app prefix	`avalaraTaxEnabled`
Custom object IDs	camelCase with app prefix	`avalaraTaxConfig`
Credential IDs	Dotted notation	`avalara.tax.api.cred`
Profile IDs	Dotted notation	`avalara.tax.api.profile`

Packaging and Validation Workflow

Using Claude Code Skills (Recommended)

The Commerce Apps repository includes Claude Code skills that automate packaging and validation. See the full skill catalog in Development Environment Setup — Claude Code Skills.

Typical packaging workflow:

/scaffold-app — Generate initial app structure
Build your app code and logic
/generate-service-impex, /generate-site-preferences-impex — Generate IMPEX files
/validate-impex — Validate IMPEX files during development
/package-app — Package app into ZIP
/validate-app — Comprehensive pre-submission validation
/submit-pr — Submit to the registry (targets the appropriate release branch, such as release/26.8)

Manual Workflow

If you aren’t using Claude Code, follow these steps:

Organize your project into the CAP directory structure.
Ensure commerce-app.json fields (id, version, domain) match the App Registry root manifest entry.
Run b2c cap validate to verify structure, manifest, and file integrity.
Run b2c cap package to produce the .zip artifact. The ZIP must contain a single root directory: commerce-{app-name}-app-v{version}/.

Verify the ZIP contains no junk files (.DS_Store, __MACOSX, hidden files). Use exclusion flags when creating the ZIP manually:

1zip -r my-app-v1.0.0.zip commerce-my-app-app-v1.0.0/ \
2  -x "*.DS_Store" -x "__MACOSX/*" -x "*/.*" -x "Thumbs.db"

Compute the SHA256 hash and verify it matches the manifest:
1shasum -a 256 my-app-v1.0.0.zip
Test the packaged .zip on a sandbox before submitting to the registry.
Open a pull request against the appropriate release branch in the App Registry (for example, release/26.8 or release/26.9). Do not target main — submissions must target a release branch.