Skip to content
Log in

Managing StoreConnect upgrades

On this page

StoreConnect upgrades are a two-step process: the Salesforce package is upgraded first, then the web application is deployed.

The Salesforce package is upgraded at StoreConnect’s discretion. You may not receive advance notice before a package upgrade. For major version upgrades, you will be notified before the web application is deployed, giving you time to prepare and test before the cutover.

Understanding StoreConnect releases

StoreConnect ships two types of releases on separate schedules:

Package releases (e.g. v20.17, v20.18) update the Salesforce package — new objects, fields, Apex logic, validation rules, and the StoreConnect Console. A package upgrade can change how records behave, what fields are available, and how the console is laid out.

Website releases (e.g. v20.0.41, v21.0.1) update the StoreConnect web application — storefront behavior, payment gateway integrations, checkout flows, and Liquid templates. These are deployed automatically and independently of the package.

Upgrade procedure

1. Receive notification

StoreConnect notifies you that the Salesforce package is now on the latest version. At this point the web application has not yet been upgraded.

2. Test in a sandbox (optional)

If you have access to a Salesforce sandbox, this is a good opportunity to test the upgrade before it reaches production. Refresh a full or partial sandbox, then run the Setup Wizard from the StoreConnect Web Console to provision the web application on the new version. This gives you a safe environment to work through changes before they affect your live store.

3. Review the upgrade guide and release notes

Read the upgrade guide for the version you are moving to — for example, Upgrade guide — v19 to v20. Work through each section that is relevant to your implementation. These guides are easier to follow than reading the release notes alone and include step-by-step instructions specific to that version.

4. Prepare your theme

If the upgrade requires template changes, make those changes in a cloned version of your theme rather than your active theme. This keeps your live store stable while you prepare the updated version.

Name your themes clearly so you can switch between them quickly — for example, Default Theme v19 for the current active theme and Default Theme v20 for the updated version.

:::warning Cloning a theme is not a simple one-click operation. A theme record has many related template records, and Salesforce has no built-in way to clone a record and all its related records in one step. You will need to clone each template manually, or use a third-party tool capable of deep-cloning related records. Plan time for this before the upgrade window opens. :::

5. Switch themes at the right time

Once the web application is upgraded, StoreConnect will notify you. At that point you can switch your store to the updated theme.

Timing matters here. There are two scenarios:

  • Theme changes that are backward-compatible. You can switch to the new theme before or after the web application is upgraded without affecting your live store.
  • Theme changes that are required for the upgraded site to function correctly. If you switch the new theme before the upgrade, your live store may break. If you switch after the upgrade but take too long, your live store will be broken in the interim.

For the second scenario, coordinate with StoreConnect on timing so you can switch the theme as soon as the upgrade is complete. Make sure you are available to receive the upgrade completion notification and can act on it immediately.

How to read release notes

After a package upgrade is applied to your org, read the release notes before your website is upgraded to the matching version. If you are upgrading across multiple versions, read all of them in order — risks are cumulative.

Focus on these sections in order:

Breaking changes and cautions — read this first, every time. These are changes that will affect your store immediately on upgrade or when records are next edited. They often require action before or immediately after upgrading.

Deprecated fields — these are fields that are no longer valid and will be removed in a future release. Record them now and plan to clean them up before the next upgrade.

Enhancements — review these for any changes to existing behavior. An enhancement that changes how a feature works may affect your configuration or staff workflows even when it is not classified as a breaking change.

Fixed bugs — if a bug fix corrects behavior you were relying on (or working around), it may require you to update your configuration.

:::tip Keep a simple log of what you notice in each section as you read. You will use it to build your pre-upgrade action list. :::

Common upgrade risks

These are the most frequent causes of issues after a StoreConnect package upgrade.

Field changes

Field API names never change. Label changes are cosmetic — they only affect how the field appears in the Salesforce UI and have no impact on automations, Flows, or reports.

When a field needs to change significantly, StoreConnect deprecates the old field and introduces a new one. During the package upgrade, data is automatically copied from the old field to the new one. The new field may not take effect on the storefront until the website is upgraded to the matching version.

New fields and related lists added by an upgrade are not automatically added to your page layouts. Your Salesforce System Administrator will need to add any new fields or related lists you wish to use to the relevant page layouts after upgrading.

Deprecated fields and components

Fields and components are usually announced as deprecated in one release and removed in a later one. If you have custom Flows, reports, or Apex that reference a deprecated field, they will break if the field is eventually removed. StoreConnect may delete deprecated fields from our package, but if they are already in your org, they remain there. You can delete them yourself, when you are ready.

Console navigation changes

Occasionally, functionality moves within the StoreConnect Console — for example, actions previously in the left navigation may move to a header toolbar. This does not change how the feature works, but it will confuse staff who follow documented steps or muscle memory.

What to do: When the release notes mention navigation changes, update your internal guides, onboarding materials, and support scripts before rolling out the upgrade to your team.

Post-install migrations with upgrade path dependencies

Some package upgrades run automatic data migrations to set default values on existing records. Occasionally, a migration is tied to a specific upgrade path (e.g. upgrading from version X but not from version Y). If the migration does not run, affected records may be left in an unexpected state.

What to do: After upgrading, verify the data state of any records called out in the release notes. If a patch release notes a migration fix, read it carefully to understand whether your upgrade path was affected.

Picklist values

If new picklist values are added to StoreConnect, they are not automatically updated in your org. If you wish to add them, you can do so by using the Manage picklist values tool in StoreConnect Console Setup.

StoreConnect will normally only add new values. If a picklist value is renamed, any Flow, automation, validation rule, or custom code that matches on the old value by name will silently stop working — it will not throw an error, it will just never match.

Pre-upgrade checklist

Complete this after a package upgrade is applied and before the website upgrade goes live:

  • [ ] Read the upgrade guide for your target version — for example, Upgrade guide — v19 to v20
  • [ ] Read the release notes for every version between your current version and the target — not just the latest
  • [ ] List every item in the Breaking changes and cautions sections that affect you
  • [ ] Identify which records, reports, Flows, or integrations are affected
  • [ ] Note any deprecated fields you need to schedule for removal — deprecated fields remain in your org and can be removed from page layouts when you are ready
  • [ ] Brief staff on any console or navigation changes

Post-upgrade tasks

After the web application is upgraded, review the following:

  1. Check your store site. Look carefully for any design issues that may be linked to Liquid or theme component changes.
  2. Run a test order end-to-end through checkout and confirm it syncs to Salesforce correctly.
  3. Confirm payment processing works for your active payment providers.
  4. Check the StoreConnect Console for sync errors, particularly for any new fields you have added to page layouts.
  5. Review page layouts. For new functionality involving new objects or fields, ensure you are using a page layout with the required fields and related lists.
  6. Ensure interdependent integrations are up to date.
  7. Review error logs. Check error logs for automations, scheduled jobs, and API workflows.
  8. Confirm any other area called out in the release notes behaves as expected.

Update picklist values

After a package upgrade, you may need to update picklist values. The StoreConnect Console includes a tool for this.

Go to the StoreConnect Console, select Setup > Manage picklist values and follow the on-screen prompts.

StoreConnect console update picker values

If something breaks after upgrading

  1. Check the breaking changes and cautions section of the release notes — the cause and fix are often described there.
  2. Check the StoreConnect Console for sync errors, which may point to a field or record-level issue.
  3. Contact StoreConnect support if you cannot identify the cause.

Version-specific upgrade guidance

For version-specific upgrade guidance, refer to the articles specific to your target version. There is a dedicated set of articles for each major upgrade covering what to review and any steps specific to that version.

Was this article helpful?

Was this article helpful?