Post-Publication and Maintenance

Manage updates, replication, and support for your published Commerce App.

Submit updated versions following the same packaging and submission process. Use b2c cap pull <app-name> --site-id <site-id> to download the currently installed version from an instance for comparison before upgrading. Include versioned migration directories in impex/ (for example, v1.1.0/) for schema changes that need to run on upgrade.

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

  1. Install on staging. Use Business Manager or b2c cap install to install the app on the staging instance for the target site.
  2. 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.
  3. 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.
  4. Replicate data to production. Run Data Replication to move site preferences, custom objects (including CommerceFeatureState), service definitions, and metadata. This activates the app on the production site by replicating its cartridge path entry.
  5. Reconfigure credentials on production. Service credentials (API keys, passwords, secrets) are stripped from replication and must be re-entered on production via Business Manager. Re-run any tasksList.json step that captures credentials.
  6. Verify on production. Re-test end-to-end on the production storefront before opening to live traffic.

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 site preferences, custom objects (CommerceFeatureState), services, and metadata (site-scoped)
  • The cartridge path is part of site configuration, so replicating site settings automatically activates the app on the target instance

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

Important: Service credentials don’t replicate. B2C Commerce strips passwords and secrets from IMPEX exports and excludes service configurations from data replication entirely. After replicating your app from staging to production, merchants must re-enter all API keys and service credentials on the target instance via Business Manager or programmatically. Your app’s tasksList.json should include a credential configuration step for every instance where the app is activated.

See: Web Services in B2C Commerce

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, ensure your uninstall IMPEX handles per-site data cleanup appropriately. Instance-scoped resources (service definitions, custom object type definitions) should only be removed by the last-site uninstall, which the platform handles automatically.

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

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.