SuiteCommerce Migration and Upgrade Checklist
First identify what you are changing. Oracle updates SuiteCommerce and SuiteCommerce MyAccount through managed bundles. SuiteCommerce Advanced (SCA) uses an unmanaged bundle and requires a manual migration. Those are different projects.
Oracle explains the distinction in Commerce Patches and Upgrades. Use the procedure for your source release, including Oracle's guidance for Aconcagua and later or Kilimanjaro and earlier.
No generic checklist can promise zero downtime. Activation, DNS, integrations, data changes, and account-specific customizations affect the cutover. Set an outage tolerance with the business and prepare a tested recovery plan.
1. Define the change
Record:
- current product and release;
- target product and release;
- domains and applications affected;
- theme, extensions, SuiteApps, SuiteScripts, and integrations in scope;
- business processes that must keep working;
- acceptable maintenance window and rollback point.
Do not infer the version from a filename alone. Confirm it in the account and deployed application records.
2. Inventory custom work
List each customization and its owner. Separate supported extensions from direct source changes and old overrides. Direct edits are usually the highest migration risk because a new reference implementation may replace the code they changed.
For each item, decide whether to retain, replace, or remove it. Check the target release notes and Oracle's compatibility guidance. Compile success is useful, but it does not prove runtime compatibility.
3. Prepare recovery
Keep source in version control and tag the deployed state. Export the configuration and data that your account and tools allow you to restore. Document who can reverse an activation or deployment.
A rollback plan should state:
- the trigger;
- the person who makes the decision;
- the exact version or activation to restore;
- how orders and customer changes made during the window are handled;
- how staff and customers are informed.
Test the plan. An archive that nobody has restored is not a recovery plan.
4. Test in a safe account
Use a sandbox or release preview account where available. Match production configuration closely enough to exercise real paths without copying secrets into source control.
Test at least:
- anonymous and signed-in browsing;
- search, category, and product pages;
- pricing, promotions, tax, shipping, and payment flows relevant to the store;
- account registration and MyAccount tasks;
- integrations and scheduled jobs;
- mobile layouts, analytics, consent, and transactional messages.
Use test payment methods and provider-approved test credentials. Never run load tests against production without explicit approval.
5. Rehearse deployment
Write the deployment steps in order and assign an owner to each. Include extension or theme upload, domain activation, configuration changes, cache behavior, smoke tests, and the stop point for rollback.
Oracle's Extension Developer Tools treat upload and activation as separate steps. The current command behavior is documented in the Gulp command reference.
6. Cut over and validate
During the agreed window:
- Pause only the jobs or edits identified in the plan.
- Capture the current state.
- Apply the rehearsed changes.
- Run a short smoke test before opening normal traffic.
- Continue with the full business checklist.
- Roll back if a defined trigger is met.
Watch application errors, payment failures, integration queues, and order flow. Compare them with a normal period instead of using an invented universal threshold.
Final checklist
- Product and release path confirmed
- Release notes reviewed
- Customizations classified
- Restore steps tested
- Sandbox test passed
- Payment and integration owners available
- Deployment rehearsed
- Rollback triggers agreed
- Smoke test completed
- Post-cutover monitoring assigned
A controlled migration is more valuable than an ambitious promise about downtime.
