Version
A Version in Salesforce is a numbered iteration of a component, an API endpoint, or a package release that identifies a specific point in the platform history and the capabilities available at that point.
Definition
A Version in Salesforce is a numbered iteration of a component, an API endpoint, or a package release that identifies a specific point in the platform history and the capabilities available at that point. Common examples include the Salesforce API Version (which tracks each Salesforce release, like 59.0 for Winter 24), the Apex Class API Version (set per class to lock in compatibility), and the Managed Package Version (set per package upload to identify which release a Subscriber is on).
Versioning sits at the heart of how Salesforce handles backward compatibility. The platform can run code written against API version 30.0 alongside code written against API version 60.0 because each component locks in the behavior of the version it was created or compiled against. This is how Salesforce can ship three releases a year and still keep ten-year-old custom code working in production.
How Version works across API, packages, Flow, and metadata in Salesforce
API Version: what it controls and where it lives
Every Apex class, trigger, Visualforce page, Aura component, Lightning Web Component, REST endpoint, and SOAP endpoint has an API Version attached to it. The version controls the platform behavior the component sees: which DML semantics apply, which SOQL syntax is valid, which fields exist on standard objects, and which exception classes get thrown. The version is set when the component is created and can be changed manually later. Pre-release versions are not selectable; only released versions are. Salesforce publishes a version-by-version compatibility guide in the developer documentation that describes every behavior change. When debugging unexpected behavior, the API version on the component is one of the first things to check, since the same code can behave differently across versions.
Release version, API version, and the three-times-a-year cadence
Salesforce releases three major versions per year: Spring, Summer, and Winter. Each release bumps the API version number (every release adds one to the major version; minor versions are reserved for patches inside a release window). Spring 2023 was API 57.0; Summer 2023 was 58.0; Winter 24 was 59.0; and so on. Sandboxes upgrade on a different schedule from production, so during the preview window, sandboxes run one release ahead of production. This is why pre-release testing happens in sandbox: it lets you verify that your custom code on the current API version still behaves correctly when production catches up. Knowing the release-to-version mapping is essential for reading platform-bug reports and Salesforce release notes.
Package Version: managed packages and the upgrade chain
Managed packages ship in numbered versions of the form major.minor.patch (1.0.0, 1.1.0, 1.1.1, 2.0.0). The version is set by the Publisher when uploading a new package version to the AppExchange. Subscribers see the version in the Installed Packages list and can upgrade between compatible versions through the package install flow. Major version bumps may include schema changes, component renames, or removals; minor and patch versions are intended to be drop-in. Publishers control which versions remain installable from AppExchange and can deprecate older versions. The Subscriber side stores the installed version on the Installed Package record, and the Publisher side stores the version reference on the License record in their LMA.
Version-pinning, deprecation, and backward compatibility
Each platform version has a defined support lifecycle. New API versions are added every release; older ones remain available indefinitely so customer code keeps working. The exception is when Salesforce explicitly deprecates a behavior, marking it as scheduled for removal at a future version. Deprecated behavior is still available for several releases before final removal, and Salesforce publishes the removal target in release notes. Custom code pinned to a deprecated version eventually has to be bumped to a newer one or rewritten. Audit your org API version inventory every year (a SOQL query against ApexClass.ApiVersion and similar) and identify any components pinned to versions older than ten releases. Those are the ones most at risk of breaking on future deprecations.
How API Version interacts with Apex behavior
Some changes between API versions are behavioral, not syntactic. An Apex class on version 30.0 may behave differently than the same class on version 60.0, even if the source code is identical. Examples include the order of trigger execution for related records, the default value of certain context variables, the rules for governor-limit enforcement during chained transactions, and the exception thrown by certain DML failures. The platform documents each behavioral change in the version-by-version compatibility guide. Reading this guide before bumping an Apex class to a newer API version is the safest way to avoid surprise regressions. If your test suite is thin, bump version-by-version and run the tests at each step, rather than jumping ten versions at once.
Versioning custom metadata, flows, and reports
Some Salesforce artifacts have implicit versioning that does not always look like a version number. Flow runtime versions are numbered (1, 2, 3) and stored on the FlowDefinition record; activating a new version deactivates the previous. Report Types have an internal version that updates when fields are added or removed. Custom Object metadata carries a release tag rather than a version number, since each object lives at the org level. Approval Processes track versions implicitly through Activation history. When packaging or migrating between orgs, all of these versions matter because the deploy target has to be compatible with what the source produced. Confirm version compatibility before deploying anything cross-org, since version mismatches surface as cryptic deploy errors rather than friendly messages.
Auditing and managing Version across an org
Working with Version in Salesforce is mostly inventory and audit work rather than active configuration. The platform manages version assignments for new components; the operational task for an admin or developer is auditing existing components for stale versions, planning upgrades when Salesforce deprecates a behavior, and confirming version compatibility before deploying or installing. This guide covers the common audit and bump workflow that most teams run on a quarterly cadence.
- Inventory API Version across your custom code
Run SOQL queries against the ApexClass, ApexTrigger, ApexPage, AuraDefinition, and LightningComponentBundle metadata objects, selecting ApiVersion and grouping by version number. The result is a histogram of how many components are pinned to each version. Anything more than ten releases behind the current platform version is a candidate for an upgrade audit. Export the result to a spreadsheet and tag each row with the responsible team or product line. This list is the input to the next quarter upgrade work.
- Read the version-by-version compatibility guide
For each version gap you plan to close, open the Salesforce developer documentation and read the version-by-version compatibility guide for that range. Salesforce documents every behavioral change between releases. Identify which changes apply to your code (DML behavior, governor limits, exception types, namespace rules) and flag the components most likely to be affected. The guide is the single best source of truth for what to test during a version bump. Skipping it and hoping the tests catch everything is the most common reason version upgrades break in production.
- Bump versions in a sandbox with full test coverage
Open each component flagged for upgrade, bump the API version one release at a time, and run the full Apex test suite after each bump. Do not jump ten versions in one move. The version-by-version approach catches issues at the step where they are introduced rather than at the end where the root cause is buried. Document any code changes the bump requires in the team release tracker so the same code does not break next time. Sandbox-test the change for at least one full release cycle before promoting to production.
- Audit Package Versions for installed managed packages
Open Setup, Installed Packages, and review the version of every managed package in the org. Compare against the latest version each Publisher offers on AppExchange. Identify packages two or more major versions behind, since those are the most likely to have unresolved security fixes or behavioral updates. Coordinate with the Publisher to confirm the upgrade path is supported and contains no breaking schema changes. Schedule the upgrade in a sandbox first, then promote to production with a documented rollback plan.
- API Version is set per component, not per org. Different Apex classes in the same org can run on different versions, and the same code can behave differently across versions. Audit before assuming consistency.
- Managed package major version bumps may include schema changes. Read the Publisher release notes carefully and test in sandbox; do not assume a major version upgrade is drop-in for any non-trivial package.
- Sandboxes run one release ahead of production during the preview window. Code that works in sandbox during preview may behave differently in production until production upgrades to the same release.
- Deprecated behavior is removed without notice if you ignore the deprecation announcement. Salesforce publishes the removal target in release notes; read them every release or risk surprise breakage.
- Flow versions do not show up in standard reports without a custom report type. Build the report type once, then add it to your governance dashboard so old flow versions do not accumulate unnoticed.
Trust & references
Straight from the source - Salesforce's reference material on Version.
- Apex Version SettingsSalesforce Developer Docs
- Salesforce Release NotesSalesforce Help
- Managed Package VersioningSalesforce Developer Docs
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 Version?
Q2. Why does versioning matter?
Q3. What examples exist?
Discussion
Loading discussion…