Upgrading
Upgrading in Salesforce managed packaging is the process of installing a newer version of a managed package into a Subscriber org that already has an earlier version installed.
Definition
Upgrading in Salesforce managed packaging is the process of installing a newer version of a managed package into a Subscriber org that already has an earlier version installed. The platform applies the Publisher new metadata, code, and configuration without disturbing the Subscriber own customizations on top, and without deleting the records and data that already live in the org.
Upgrades come in two flavors. Patch upgrades carry the patch number in the version (1.0.0 to 1.0.1) and are intended to be drop-in: bug fixes, security patches, no schema changes. Major version upgrades (1.0.0 to 2.0.0) can carry breaking changes such as schema additions, component renames, or behavior changes that require Subscriber-side reconfiguration. Reading the Publisher release notes before any upgrade is the difference between a smooth install and a midnight support call.
What happens during a managed package upgrade and how to plan one
What happens technically during an upgrade
When a Subscriber clicks Upgrade on an Installed Package, the platform downloads the new package version metadata, compares it against the currently installed version, and applies the diff to the Subscriber org. New components are added. Existing managed components are updated in place. Components that have been removed in the new version are deleted from the Subscriber org. Subscriber-created components (custom fields on the package objects, validation rules, page layouts that the Subscriber added) are preserved. Data on package-defined custom objects is preserved. Apex classes from the new package compile against the Subscriber current API version and metadata; if compilation fails, the upgrade fails and the org rolls back to the prior version.
Patch versus major upgrades
Patch versions ship as drop-in fixes. The Publisher signs a patch when the changes are limited to bug fixes, security patches, and small additive enhancements that do not change schema or remove components. Major versions are riskier: they may add required fields, change Apex method signatures, remove components, or alter behavior in ways that affect Subscriber-side extensions. The version number signals the risk level. Most Publishers also publish release notes that document every change. A patch version can usually be applied during business hours; a major version usually deserves a planned maintenance window and a sandbox dry run first.
Compilation, dependencies, and rollback behavior
Salesforce compiles every Apex class in the new package against the Subscriber org during install. If a Subscriber-side extension references a method or class from the package that no longer exists in the new version, compilation fails. The platform then rolls the org back to the previous package version automatically; no data is lost, and the Subscriber sees an error describing what failed to compile. This safety mechanism is the reason Publishers usually avoid removing public Apex symbols across minor versions; doing so breaks Subscriber-side code that depends on them. Subscribers can mitigate the risk by running every upgrade in a sandbox first and confirming their custom Apex still compiles before promoting.
Push upgrades versus pull upgrades
Publishers can ship upgrades two ways. Push Upgrade is a Salesforce-managed mechanism where the Publisher initiates the upgrade for all Subscribers automatically; the Subscriber does nothing. Push Upgrades are typically reserved for security patches and small bug fixes (Salesforce restricts what kinds of changes are eligible for push). Pull upgrades require the Subscriber admin to manually trigger the install from the AppExchange or the Publisher install URL. Most major version upgrades are pull-only. Subscribers can disable push upgrades for specific packages through the Installed Packages settings, but doing so means they have to track patches manually. Most orgs accept push for everything except the highest-risk packages.
What an upgrade does to Subscriber customizations
Customizations that the Subscriber added to package-defined objects survive the upgrade. Subscriber-added fields, validation rules, page layout changes, list views, sharing rules, and Apex code that references package symbols all remain in place. The upgrade may rearrange Publisher-supplied components (a Publisher-supplied page layout assignment, for example) and the Subscriber may need to reapply their layout customizations after the upgrade if the Publisher rebuilt the layout. Data on package-defined custom objects is preserved across upgrades. Reports and dashboards built on package data continue to work as long as the underlying objects and fields the report references still exist in the new version. Plan for the rare case where the Publisher removed an object the Subscriber built reports on; those reports break and need rebuilding.
Testing, rollback, and the upgrade playbook
A safe upgrade playbook has four parts. First, read the Publisher release notes carefully and note any breaking changes. Second, install the new version into a sandbox that mirrors production, including the same Subscriber-side extensions, and run a full regression test against the Subscriber standard user journeys. Third, schedule the production upgrade for a maintenance window. Fourth, have a rollback plan in case the upgrade succeeds but business processes break in production. Salesforce does not support rolling back to an earlier package version once the upgrade completes successfully (the auto-rollback only covers compilation failures during install). Manual rollback means uninstalling the package and reinstalling the prior version, which is destructive to data and almost never the right answer in production.
Running a managed package upgrade safely
The actual upgrade work is a five-step sequence: read the release notes, install in sandbox, run regression tests, schedule production, and validate post-install. Doing each step in the right order is the difference between an uneventful upgrade and a production support escalation. This routine applies whether you are upgrading a CPQ package, a Marketing Cloud Account Engagement (Pardot) package, an industry cloud add-on, or any AppExchange managed package. Skipping the sandbox step is the most common reason production upgrades fail unexpectedly.
- Read the Publisher release notes
Find the Publisher release notes for the new version. They are typically linked from the AppExchange listing or from the Publisher support site. Read the breaking-changes section first, the new-features section second, and the bug-fixes section last. Capture any items that affect your Subscriber-side customizations (renamed methods, removed fields, behavior changes). If your org has Apex code that extends the package, find every reference to package symbols in your code and compare against the release notes. Skip this step and the rest of the routine is guesswork.
- Install in a sandbox and run regression tests
Refresh a sandbox that has the same configuration and the same Subscriber-side extensions as production. Install the new package version into the sandbox using the AppExchange link or the Publisher install URL. Watch the install log for compilation failures or permission warnings. After install, run your full regression test suite on the affected user journeys. Manual testers should cover the package main flows; automated tests should cover any Apex code that depends on the package. Capture every defect in your tracker and triage them with the Publisher and your dev team before scheduling production.
- Schedule the production upgrade and notify users
Pick a maintenance window when usage is low (overnight or weekend for most orgs). Notify users in advance about the window and any expected behavior changes. On the day, take a metadata snapshot of the production org (a recent change set or DX export) so you have a record of pre-upgrade state. Install the package version in production using the same AppExchange link or install URL you tested with in sandbox. Watch the install log. For Push Upgrades, you do not control the timing; the Publisher pushes when they push.
- Validate post-upgrade and document
After install completes, validate the package by walking through the same regression scenarios you ran in sandbox. Confirm new features show up in the UI, custom code still compiles and runs, and any Publisher-supplied automations fire correctly. Update the org upgrade log with the date, version, and any issues you encountered. Document any new package features for end users (release notes from your side, not the Publisher side). Schedule a one-week monitoring window during which support tickets that mention the upgraded package get routed to a dedicated triage queue.
- Push Upgrades happen without Subscriber action and during Publisher-chosen windows. Disable Push Upgrades on high-risk packages if your change management policy requires advance notice for every install.
- Compilation failures during install trigger an automatic rollback to the prior version. The rollback is data-safe but the error message is technical. Have a developer ready to interpret on the day of the upgrade.
- Salesforce does not support rolling back a successful upgrade. Manual rollback means uninstalling the package and losing data, which is almost never the right answer. Test thoroughly in sandbox first.
- Major version upgrades may change Apex method signatures, schema, or behavior. Read the release notes and update Subscriber-side code in the same release window so production never runs on an inconsistent combination.
- Reports and dashboards built on package data can break if the Publisher removed or renamed an object or field. Inventory dependencies before upgrade and rebuild any reports that break the moment the new version goes live.
Trust & references
Straight from the source - Salesforce's reference material on Upgrading.
- Install and Upgrade Managed PackagesSalesforce Developer Docs
- Push Upgrades OverviewSalesforce Developer Docs
- Install a PackageSalesforce Help
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is Upgrading?
Q2. Is existing data preserved?
Q3. What should you do before upgrading?
Discussion
Loading discussion…