Packaging Your Commerce App

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

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.

• 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)

This file defines the post-install configuration steps that appear in the Business Manager setup wizard. Each task has a task number, name, description, a deep link to the relevant BM page, and an initial status.

Example:

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

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:

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:

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

The impex/uninstall/ directory contains XML files that clean up resources when the app is removed. Uninstall IMPEX files should use mode="delete" 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:

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.

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:

1. /scaffold-app — Generate initial app structure
2. Build your app code and logic
3. /generate-service-impex, /generate-site-preferences-impex — Generate IMPEX files
4. /validate-impex — Validate IMPEX files during development
5. /package-app — Package app into ZIP
6. /validate-app — Comprehensive pre-submission validation
7. /submit-pr — Submit to the registry

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

1. Organize your project into the CAP directory structure.

2. Ensure commerce-app.json fields (id, version, domain) match the App Registry root manifest entry.

3. Run b2c cap validate to verify structure, manifest, and file integrity.

4. Run b2c cap package to produce the .zip artifact. The ZIP must contain a single root directory: commerce-{app-name}-app-v{version}/.

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

6. Compute the SHA256 hash and verify it matches the manifest:

7. Test the packaged .zip on a sandbox before submitting to the registry.