SuiteCommerce 2023.x to 2024.x: Upgrade and SCA Migration Guide

A 2023-to-2024 Commerce update is not one universal procedure. SuiteCommerce and SuiteCommerce MyAccount receive managed-bundle updates automatically. SuiteCommerce Advanced (SCA) is an unmanaged bundle and requires a manual migration.

This article covers the 2024.1 and 2024.2 releases for teams that still need that version-specific history. If you are planning a migration now, start with Oracle's current Commerce release notes and choose the latest supported major or minor release rather than assuming 2024.2 is the right target.

First identify the Commerce product

SuiteCommerce and SuiteCommerce MyAccount

Oracle distributes these products through a managed bundle. Major and minor updates apply to the account on Oracle's schedule. Unless a release note says otherwise, there is no source migration to run.

Your job is release readiness:

• read the release notes;
• check extension and theme compatibility;
• test key storefront and account flows around the account update window;
• watch custom integrations and analytics after the update.

SuiteCommerce Advanced

Oracle distributes SCA as an unmanaged bundle. An account update does not migrate the SCA application. To receive SCA code changes, install or update the target SCA bundle, create a new local source workspace, carry forward supported customizations, deploy to a development SSP application or sandbox, and test before cutover.

Oracle explains this split in Commerce Patches and Upgrades.

What the 2024 release pages actually establish

The official 2024.1 release page and 2024.2 release page provide:

• the SuiteCommerce and SCA bundle IDs for those releases;
• links to major and minor release notes;
• the NetSuite account-version dependency;
• confirmation that SuiteCommerce updates automatically while SCA does not.

Use the linked detailed notes to build a change list. Do not infer features, breaking changes, or performance gains from the release number. The old version of this article claimed percentage improvements and broad SEO, checkout, subscription, and B2B changes without sources. Those claims have been removed.

1. Inventory the current implementation

Before installing anything, record the current state.

Account and application

Capture:

• product: SuiteCommerce, SuiteCommerce MyAccount, or SCA;
• exact Commerce or SCA release and minor version;
• NetSuite account release;
• website, domains, and SSP application links;
• active theme, skin, and extensions per domain;
• installed Commerce-related bundle IDs;
• Node.js and developer-tool versions used by the team.

Customizations

Classify each change by owner and migration path:

For each item, record the repository path, business owner, test case, external dependency, and rollback option. If no one can explain why a customization exists, do not silently carry it forward. Test whether the target release or configuration already covers the requirement.

2. Read every release note in the path

For a 2023.x to 2024.2 review, read:

• the source release's remaining minor notes;
• 2024.1 major and minor notes;
• 2024.2 major and minor notes;
• Theme release notes for the Base Theme in use;
• Extension release notes for every Oracle extension in use.

Turn each relevant note into one of four actions:

1. no impact;
2. configuration change;
3. code change;
4. regression test.

Keep the source URL beside the action. This avoids a migration plan built from memory or a generic checklist.

3. Prepare isolated environments

Use source control and a separate workspace for the target release.

# Example only; adapt branch names to your repository
git switch production
git pull --ff-only
git switch -c migration/sca-target-release

Do not overwrite the working source directory for the current live SCA release. Oracle tells SCA teams to download the new source ZIP into a new working directory.

Use a sandbox when available. Otherwise, link the new SCA development SSP application to a development domain. Never point the primary domain at untested source.

For theme and extension work, Oracle recommends separate extracted developer-tool directories for sandbox and production. This reduces the chance of reusing an authentication ID for the wrong account.

4. Handle SuiteCommerce automatic updates

For SuiteCommerce or SuiteCommerce MyAccount, do not follow the SCA source-migration steps. Build an update test plan instead.

Before the scheduled update:

• verify each active extension's target-version range;
• confirm third-party SuiteApps support the account release;
• record the current active theme and extension versions;
• save baseline screenshots and performance measurements;
• test a representative order and account flow.

After the update:

• check browser and server-side errors;
• retest search, product detail, cart, checkout, payment, confirmation, and My Account;
• verify integrations received expected payloads;
• confirm analytics and consent behavior;
• compare results with the baseline.

If a problem is isolated to a custom extension or theme, fix and deploy that package. Do not attempt to replace the managed SuiteCommerce core.

5. Migrate SCA Aconcagua or later

Oracle's Migrate from Aconcagua and Later procedure is the source of truth. In condensed form:

1. Review the target major and latest minor release notes.
2. Install the target SCA bundle, or update the installed bundle when the minor release keeps the same bundle ID.
3. Download the target source ZIP from: Web Site Hosting Files > Live Hosting Files > SSP Applications > NetSuite Inc. - SCA <version> > Source > _Sources.
4. Extract it into a new local working directory.
5. Recreate core changes as themes or extensions where the Extensibility API supports the requirement.
6. For required source customizations, copy custom modules into a new custom-module folder.
7. Merge references into the new distro.json.
8. Compare module versions and changed source against each customization.
9. Link the target development SSP application to a development domain.
10. Reactivate compatible themes and extensions there.
11. Deploy any required SCA source customizations with the SCA developer tools.
12. Run the full test plan before linking or deploying to the primary domain.

Do not copy the old distro.json

Oracle warns against replacing the target release's distro.json with the old one. The target file can include new modules and dependencies. Diff the files and transfer only the required custom-module references and application dependencies.

Prefer public extension points

If an old customization edits a standard SCA module, first look for a supported Extensibility API component or theme override. Direct core changes cost more to review on every migration. Keep a source customization only when the public APIs cannot meet the requirement, and document why.

6. Migrate Kilimanjaro or earlier

These releases predate themes and extensions. Oracle's Migrate From Kilimanjaro and Earlier procedure requires more than a source merge:

• recreate Sass and template customizations as a theme;
• recreate JavaScript, SuiteScript, and JSON customizations as extensions where supported;
• manually migrate only code that the Extensibility API cannot express;
• link and test the new SSP application on a development domain.

Do not copy the old core tree over the new release. That defeats the migration and can remove target-release changes.

7. Validate themes and extensions with their own tools

Themes and extensions are separate from SCA core source. Use the matching Oracle tools archive and the Node.js version for the target implementation.

For an extension:

gulp extension:fetch
gulp extension:local
gulp extension:deploy

For a theme:

gulp theme:fetch
gulp theme:local
gulp theme:deploy

The fetch tasks can overwrite local workspace files, so commit or back up first. The local and deploy tasks can update manifest.json; use the documented --preserve-manifest flag only when you have intentional manual manifest edits.

There is no documented gulp extension:validate command in the current Theme and Extension Developer Tools reference. gulp extension:deploy --to sandbox also does not select an environment named “sandbox.” The --to flag resets authentication and lets you select or create another authentication ID. For account-specific domains, use the documented --account <account-id> form.

See the Gulp command reference.

8. Build a test matrix from business risk

At minimum, cover:

Storefront

• home, category, search, and faceted navigation;
• product detail, options, pricing, stock, and add-to-cart;
• promotions, gift certificates, and saved lists in use;
• mobile and supported desktop browsers;
• metadata, canonical links, structured data, and sitemap behavior that the site relies on.

Checkout

• guest and signed-in checkout;
• every shipping and pickup method;
• tax calculation;
• each payment method;
• success, decline, retry, duplicate-submit, and timeout paths;
• confirmation email and order creation in NetSuite.

My Account and B2B

• login and password reset;
• order history and reorder;
• addresses and payment methods;
• quotes, invoices, purchase orders, and account hierarchy if enabled.

Integrations and operations

• analytics and consent tags;
• tax, payment, fraud, search, reviews, and marketing services;
• scheduled scripts and custom records used by Commerce;
• customer-service workflows;
• deployment, activation, and rollback access.

Record evidence for each test. “Page loaded” is not enough for order, payment, tax, or integration paths.

9. Cut over without promising zero downtime

No generic article can guarantee a zero-downtime SCA migration. Domain links, Extension Manager compilation, caches, payment behavior, and account-specific integrations all affect the release.

Use a written cutover plan:

1. Freeze changes to the current release branch.
2. Confirm the target bundle, SSP application, theme, and extension versions.
3. Complete final tests on the development domain or sandbox.
4. Record current domain and activation settings.
5. Choose a low-risk release window.
6. Deploy or link the approved target.
7. Activate the approved theme and extensions.
8. Run smoke tests through an actual order flow.
9. Monitor errors and integrations.
10. Revert to the recorded prior application or activation if the stop conditions are met.

Define stop conditions before release, such as failed payment authorization, incorrect totals, order-creation failure, or a broken login flow.

10. Keep a migration record

After release, record:

• source and target SCA versions;
• installed bundle IDs and minor versions;
• SSP application and domain links;
• active theme and extension versions;
• source customizations that remain and why;
• test results, incidents, and follow-up work.

This record is the starting point for the next migration. It is more useful than an estimated timeline copied from an unrelated implementation.

Primary Oracle references

• Commerce Patches and Upgrades
• Commerce release notes
• 2024.1 release page
• 2024.2 release page
• Migrate SuiteCommerce Advanced
• Migrate from Aconcagua and Later
• Migrate From Kilimanjaro and Earlier