Post-Install Maintenance

Manage updates, replication, and support after a Commerce App is installed — whether it was published to the registry or installed privately from WebDAV.

Updating Your App

Package and test every update as a new CAP. ISVs publish the new version through the App Registry; private-app producers deliver the new .zip directly to the merchant. Compare updates with the producer’s retained release artifact. For registry apps, b2c cap pull <app-name> --site-id <site-id> can retrieve the registry package. Private WebDAV packages can be pulled only when the installed record has a persisted version and the uploaded archive was retained. Include versioned migration directories in impex/ (for example, v1.1.0/) for schema changes that need to run on upgrade.

Replication Compatibility

Recommended Merchant Workflow

The expected lifecycle for promoting a Commerce App from staging to production:

Install on staging. Use Business Manager or b2c cap install to install the app on the staging instance for the target site.
Configure and test on staging. Complete every task in the app’s tasksList.json (entering API credentials, setting site preferences, running test transactions). Validate end-to-end behavior on the staging storefront before promoting.
Replicate code to production. Run Code Replication first to move cartridges to the production realm. The app won’t function on production until cartridges are present.
Replicate supported site data to production. Select the applicable site preferences and metadata, including the separate CommerceFeatureState replication task. Replicate the cartridge path only after the cartridges are present.
Configure non-replicated resources. Import or configure service definitions and profiles separately, and enter production credentials on the target instance. Re-run any tasksList.json step required for that instance.
Integrate storefront code. Merge or otherwise deploy Storefront Next code separately; B2C code replication doesn’t deploy the merchant’s storefront repository.
Verify on production. Confirm the cartridge path, CommerceFeatureState, services, credentials, storefront code, and end-to-end behavior before opening to live traffic.

How Replication Moves a Commerce App

Commerce Apps are designed to be replication-friendly. An app installed on a staging instance can be promoted to production using standard Commerce Cloud replication:

Code Replication moves cartridges (realm-scoped)
Data Replication moves selected supported site data; select CommerceFeatureState as its own replication task
Service definitions and profiles require separate import or target-instance configuration
Storefront Next code follows the merchant’s storefront source-control and deployment process

Important: Code replication must complete before data replication. If the cartridge path is updated before the cartridges exist on the production realm, the storefront fails to initialize the feature.

Important: Standard Data Replication doesn’t move service configurations or credentials. Import or configure the required service metadata separately, and enter API keys, passwords, and other secrets on the target instance. Include a credential configuration step in your app’s tasksList.json for every instance where the app is activated.

See: Web Services in B2C Commerce

Multi-Site Considerations

Commerce Apps support installation across multiple sites within the same realm. For the full mechanism — cartridge sharing, per-site state, deferred cleanup on the last-site uninstall, and feature toggle handling — see Multi-Site Behavior.

Tip for ISVs: If your app stores site-specific data in custom objects, make sure your uninstall IMPEX handles per-site data cleanup. Instance-scoped resources (service definitions, custom object type definitions) are removed only by the last-site uninstall, which the platform handles automatically.

Version Management

Version tracking in catalog.json applies to ISVs publishing to the App Registry. Private apps have no registry entry; ship a new .zip and reinstall.

When publishing a new version to the App Registry:

Update the ZIP and root manifest entry (version, zip, sha256 fields). Do not manually add new version entries to catalog.json — CI generates those automatically when your PR merges. Allow up to 15 minutes after merge for the new version to appear in existing Business Manager sessions; see Manifest and Catalog Cache TTL.
To deprecate a previous version, add "deprecated": true to the existing version entry in catalog.json. This is the only manual edit to catalog.json that is expected. Use deprecation for versions with critical bugs or known issues that should prevent new installations.
Version upgrades are currently a manual process: merchants uninstall the old version and install the new one. Automated in-place upgrades are planned for a future release (Wave 3).

Monitoring and Support

For the initial release, implement your own logging within your cartridge scripts and monitor through standard Commerce Cloud mechanisms:

Job execution logs: Installation, uninstallation, and IMPEX processing results are logged in Business Manager under Administration > Operations > Job Schedules. The install job writes detailed step-by-step progress to the job log.
Custom script logging: Use the dw.system.Logger API in your hook implementations. Log at appropriate levels: debug for detailed flow, info for key operations, warn for recoverable issues, error for failures.
CommerceFeatureState: Query the CommerceFeatureState system object to check installation status, configuration progress, and error messages for a specific site. The InstallationMetadata JSON field contains the job execution ID, cartridge names, and any error details.