Push Upgrade
A Push Upgrade is the mechanism a managed-package publisher uses to update every installed copy of their package across customer orgs at once, without each admin running the install wizard.
Definition
A Push Upgrade is the mechanism a managed-package publisher uses to update every installed copy of their package across customer orgs at once, without each admin running the install wizard. The publisher selects a patch version inside the Subscriber Support Console, picks which subscriber orgs receive it, schedules a date, and Salesforce deploys the metadata change on that schedule. The admin sees the new version reflected in Setup the next time they open Installed Packages, and any new components show up where the publisher placed them.
Push Upgrades only work for patch versions of a managed package, or for moving a beta to its corresponding general-availability release of the same major version. They never bump the major version, never change the API signature of public Apex classes, and never appear on unmanaged or unlocked packages. The patch namespace forbids breaking changes by design, which is what lets Salesforce promise that a push will not break compiled Apex or break a flow that references one of the publisher's fields in the subscriber org.
How a Push Upgrade lands in 200,000 subscriber orgs without a help desk meltdown
Patch versions only, never major releases
The single biggest constraint is the version restriction. A Push Upgrade can move a subscriber between patch versions of the same minor release, or from a beta to its corresponding general-availability release. It cannot upgrade 1.4 to 2.0, and it cannot move a customer between two different packages. If you want subscribers on a new major version, you issue a new install URL and let each admin take it manually. The patch-only rule is what lets Salesforce guarantee that a push will not break compiled Apex or break a flow that references one of your fields, because the patch namespace forbids breaking changes at the upload step.
Subscriber Support Console is the launch pad
To send a push, the publisher logs into the Partner Business Org, opens the package detail page, and clicks Push Upgrades. The console lists every subscriber that installed a matching prior version and lets the publisher filter by org type (production vs sandbox), region, or last activity. The publisher selects a target version, picks the org IDs to include, picks a launch time, and submits. Salesforce queues the job and sends a confirmation email when each org finishes. Failures show up in the same console with an error reason per org, usually one of three causes: missing dependency, conflicting metadata, or the subscriber org is paused for a release upgrade.
Scheduling and the maintenance window
The publisher schedules a push for a specific UTC timestamp. Salesforce respects each subscriber instance maintenance window, so a global push set for 18:00 UTC may execute at different real-world clock times for different orgs. The push job runs as a deferred metadata deploy, which means it does not block users from logging in, but any active Apex jobs from the old version may need to finish before deploy begins. Salesforce recommends scheduling pushes during off-peak hours and giving at least 48 hours of email warning to subscribers before pushing a fix that changes UI text.
What gets and does not get pushed
A push delivers new and changed managed components: Apex classes, triggers, custom objects, custom fields, page layouts, validation rules, flows, custom labels, and static resources. It does not push Custom Setting values or Custom Metadata records the subscriber created; only the type definitions. It does not modify profile or permission set assignments beyond the package permission set, and it never touches subscriber-created data records. Anything the subscriber overrode in their org, such as a translated label or a layout assignment, stays overridden after the push.
Subscriber rights and opt-out
A subscriber org cannot refuse a single push at the moment it lands, but they can disable Push Upgrades entirely from Setup, Installed Packages, Manage. They can also revert to the prior patch version within a short window after the push completes. If a subscriber files a partner case alleging the push broke something, Salesforce Partner Operations can roll the org back from their side. This is rare since the version restrictions prevent most regressions, but it has happened with ISVs that pushed Apex bug fixes whose return values changed in subtle ways downstream code depended on.
Testing before you push the world
Every ISV who has been burned by a push tells you the same thing. Install the candidate patch into a fresh scratch org, then into a paid Partner Developer Edition org seeded with realistic data, then into one or two friendly subscribers as a manual upgrade before scheduling a push to the rest. The candidate patch must pass the same security review the original package passed, and any new Apex must keep code coverage above 75 percent. The Subscriber Support Console lets the publisher log into a subscriber org as a read-only support user, which is the safest place to verify the patch behaves correctly against real customer data before flipping the switch on a global push.
When Push Upgrades fail
A failed push shows up in the console with one of a small set of error codes. Most failures are caused by metadata the subscriber introduced that clashes with the new package metadata, for example a custom field on a managed object whose name now collides with a field the patch adds. Other failures stem from disabled features (the subscriber turned off Person Accounts, but the patch references a Person Account field), or paused orgs (the subscriber is in read-only mode for a major release upgrade). In every case Salesforce stops the push for that single org without affecting any other subscriber. The publisher can fix the metadata conflict, file a case if the subscriber needs help, and retry the push for the failed list later.
Schedule a Push Upgrade from your Partner Business Org
Push a patch version from your Partner Business Org to every subscriber org running a compatible prior version, on a schedule you control.
- Build a patch version
From the package detail page in your Partner Business Org, click New Patch. Select the base version you are patching. Salesforce creates a patch development org seeded with the prior package contents.
- Make and test changes
Open the patch development org. Add or change only the metadata the patch namespace permits: no Apex API breaks, no field deletions, no signature changes. Deploy to a scratch org or a friendly subscriber and verify.
- Upload the patch
Back in the Partner Business Org, click Upload on the patch version. Salesforce runs the same security and packaging checks as a normal upload. You receive a new install URL when it succeeds.
- Open the Subscriber Support Console
From the package detail page, click Push Upgrades. The console shows every subscriber currently on a version eligible for this patch.
- Select targets and time
Filter the subscriber list. Pick the org IDs you want to push to. Choose a UTC scheduled time at least 48 hours in the future. Add a description that will appear in the post-push email to the subscriber admin.
- Submit and monitor
Submit the push. Salesforce queues the job. Refresh the console to watch the success and failure counts. Investigate any failures and either patch the conflict or retry that subset later.
The new patch version every selected subscriber org will receive at the scheduled time.
Org type, region, last package activity, and explicit org-ID list. Used to scope the push to a safe initial cohort.
UTC timestamp for when Salesforce begins deploying. Falls inside the subscriber instance maintenance window.
Free-text description that appears in the email sent to the subscriber admin after the push completes.
Controls whether Salesforce reattempts a failed push at the next maintenance window automatically.
- Push Upgrades only work between patch versions of the same minor release. They cannot bump a major version, and they cannot move a subscriber between two different packages.
- If a subscriber org has paused upgrades from Setup, Installed Packages, your push skips that org. The console marks it as Excluded, not Failed, so watch both counts.
- A push deploys metadata, not data. Custom Setting values, Custom Metadata records, and any subscriber-created data stay untouched, even when the patch redefines the underlying types.
- Schedule pushes outside the subscriber business hours. The deploy itself is online, but any Apex retries or flow re-evaluations that follow can surprise end users mid-task.
Trust & references
Cross-checked against the following references.
- Pushing an UpgradeSalesforce Developer Docs
- Push Upgrades for Managed PackagesSalesforce Help
- Salesforce Partner CommunitySalesforce Partner Program
Straight from the source - Salesforce's reference material on Push Upgrade.
- Pushing an UpgradeSalesforce Developer Docs
- Subscriber Support ConsoleSalesforce Developer Docs
- Managed Package VersioningSalesforce Developer Docs
Hands-on resources to go deeper on Push Upgrade.
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 a Push Upgrade?
Q2. When is push upgrade valuable?
Q3. What's a critical concern?
Discussion
Loading discussion…