AppExchange Upgrades
AppExchange Upgrades is the platform mechanism that delivers new versions of managed packages from an AppExchange Publishing Organization to the customer orgs that already have a previous version installed.
Definition
AppExchange Upgrades is the platform mechanism that delivers new versions of managed packages from an AppExchange Publishing Organization to the customer orgs that already have a previous version installed. When a partner releases a new package version, customers can upgrade in place rather than uninstalling and reinstalling. The upgrade carries Apex classes, custom objects, custom fields, page layouts, and other metadata into the existing managed namespace, preserving all customer data that lives in the package's objects. Upgrades come in three flavours: Push Upgrades (the partner pushes the new version to selected customer orgs on a schedule), Pull Upgrades (the customer installs the new version themselves from AppExchange), and Patch Upgrades (a constrained release that adds limited changes without going through full Security Review).
The upgrade model is critical to the AppExchange ecosystem because most packages evolve continuously. Customers expect to receive bug fixes, security patches, and new features without re-architecting their installation. Partners depend on the upgrade machinery to ship improvements without forcing customers off the product. The trade-off is governance: every upgrade must preserve backwards compatibility, respect customer customisations (custom fields added to managed objects, validation rules layered on managed records), and avoid breaking the org's existing automation. Mature ISVs invest heavily in upgrade testing because a broken upgrade ripples across every customer install at once.
How AppExchange Upgrades preserve customer customisations
Push, Pull, and Patch upgrades
Push Upgrades let the partner schedule a new version to deploy automatically into customer orgs. Customers usually receive an email notification and a scheduled date. Pull Upgrades require the customer to initiate the install themselves through AppExchange. Patch Upgrades are constrained releases that can change Apex code but not data model; they go through a faster Security Review and are typical for hot-fix releases.
Major versus patch versions
Managed packages version with both major and patch numbers. A new major version (3.0 to 4.0) can add or remove objects, fields, and Apex; a patch version (3.1 to 3.2) is restricted to backwards-compatible changes within the same major. The version policy dictates what an upgrade is allowed to do; the platform enforces these boundaries during package upload.
What an upgrade can and cannot change
Upgrades can add new components, change Apex implementations (with constraints), add new optional fields, and modify default page layouts. Upgrades cannot remove required fields, change field data types, or remove objects without explicit customer action. The protected operations exist to preserve customer data; partners who want to remove a deprecated field do so over several versions, often through a Hide step before final removal.
How customer customisations survive
Customers often customise managed packages: adding custom fields to managed objects, layering validation rules and Flows on managed records, modifying page layouts. These customisations live in the customer's namespace and survive upgrades. The package's namespace is upgraded; the customer's namespace stays untouched. The model lets customers extend a package without losing those extensions on every upgrade.
Push upgrade scheduling
Partners schedule push upgrades through the License Management Application in their APO. They select target customer orgs (by license type, by version), pick a date, and submit. Salesforce queues the upgrade and processes it at the scheduled time. Customers can receive push notification emails ahead of the upgrade. Some partners push aggressively to keep customers current; others push only major releases and leave minor versions to pull.
Pull upgrades and customer control
Pull upgrades give customers final say over the timing. The new version appears on the listing's Upgrade button; the customer clicks Install in Production or Install in Sandbox to take the new version. Most enterprise customers prefer pull because it gives them control over the change window and lets them validate in sandbox first.
Patch upgrades and hot-fixes
Patch upgrades exist for partners who need to ship a bug fix without committing to a full major release. The constraints make them faster to release: Salesforce Security Review for patches is lighter, the version-policy enforcement is stricter, and the partner can target specific customer orgs without affecting others. Patches are how partners respond to outages or critical bugs without delay.
Common upgrade failures
Three failures dominate. Apex class compile errors break the upgrade because every class in the package must compile against the customer's org metadata. Test failures (managed-package tests must still pass post-upgrade) abort the upgrade. Permission-set conflicts cause downstream user-facing breakage even when the upgrade itself completes. Partners catch these in pre-release testing against a representative range of customer orgs before scheduling a push.
How to manage AppExchange Upgrades safely
Upgrade rollout is a partner and customer collaboration. Partners need staged release discipline; customers need sandbox validation before allowing production upgrades.
- Test the new version in a representative sandbox
Both partners and customers benefit from a sandbox that mirrors the production customisations. Run the upgrade there first, validate behaviour, and document any breaking changes.
- Review the partner's release notes
Read every entry in the partner's release notes. Pay special attention to schema changes, deprecation announcements, and any required post-upgrade steps.
- Schedule the production upgrade in a change window
For push upgrades, partners schedule against a quiet window. For pull upgrades, customers schedule against their own change calendar. Avoid mid-quarter close days.
- Run post-upgrade validation
After the upgrade lands, validate critical flows: page renders, automation, integrations, and any user-facing surfaces. Catch regressions in the first 24 hours when it is easiest to roll back.
- Communicate to affected users
For visible changes, notify the user community before and after the upgrade. Most upgrade complaints come from users surprised by changed behaviour, not from technical regressions.
- Push upgrades affect the entire selected customer set at the scheduled time. Test against representative customisations or break customers en masse.
- Customer customisations on managed objects survive upgrades, but custom validation rules on managed records can fail if the upgrade changes underlying schema.
- Patch upgrades go through faster review but are constrained; do not use them to ship structural changes that need a major release.
- Failed upgrades leave the customer on the previous version. Rollback is not always clean; pre-upgrade validation is the right insurance.
Trust & references
Cross-checked against the following references.
- Distribute Package UpgradesSalesforce Developer Docs
- Push UpgradesSalesforce Developer Docs
Straight from the source - Salesforce's reference material on AppExchange Upgrades.
- Patch VersionsSalesforce Developer Docs
Hands-on resources to go deeper on AppExchange Upgrades.
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 happens to subscriber customizations and data during an AppExchange upgrade?
Q2. What is a Push Upgrade?
Q3. What is the recommended testing approach before a production upgrade?
Discussion
Loading discussion…