Salesforce API Version
A Salesforce API version is the numbered release of the Salesforce platform API that a piece of metadata, Apex class, trigger, or external integration is bound to.
Definition
A Salesforce API version is the numbered release of the Salesforce platform API that a piece of metadata, Apex class, trigger, or external integration is bound to. The number, written as a decimal like 64.0, tells the platform which set of features, fields, and behaviors to apply when that code or request runs. Every major release ships a new API version.
Salesforce publishes three major releases each year (Spring, Summer, and Winter), and the API version number increases by one with each release. Because old versions keep behaving the way they always did, the version a component is saved against acts as a contract. It is one of the main ways Salesforce evolves the platform without breaking integrations that were built years ago.
How API versioning works across Salesforce
How the version number is assigned and what it controls
The API version is a single decimal number tied to a specific Salesforce release. Winter '24 shipped as 59.0, and the number climbs by one every release after that. Apex classes and triggers store their version in metadata. SOAP, REST, and Bulk API requests name a version in the endpoint URL or envelope. Metadata API deployments set it through the version element in package.xml. Whatever the surface, the number decides which fields, methods, and rules the platform applies to that work. A field that did not exist in version 54.0 cannot be deployed against version 54.0, even if the org itself is on a much newer release. The same request sent against two different versions can return different results, because each version carries its own behavior set. This is why the version is not a cosmetic label. It is the switch that selects a frozen snapshot of platform logic, and it stays fixed until someone deliberately raises it. Reading the version off a class or an integration tells you exactly which generation of platform behavior that code expects to run under.
Backward compatibility as a promise, not a side effect
Salesforce treats older API versions as supported contracts. Code compiled against version 40.0 keeps running with the rules of version 40.0, even after the org upgrades through a dozen newer releases. When a release changes a default behavior, that change usually applies only to code saved at the new version or higher. Anything left at an older version sees the old behavior. This is deliberate. It lets the platform refine how features work without forcing every customer to rewrite working code three times a year. A worked example makes it concrete. Suppose a new release changes how a date field gets formatted in a SOAP response. An integration pinned to an older version still receives the original format, so it keeps parsing correctly. An integration that bumps to the new version gets the updated format and may need a small adjustment. Neither one breaks by surprise. The cost of this promise is that very old versions accumulate, and Salesforce eventually retires the oldest ones so it does not maintain logic forever. Compatibility buys you time to upgrade, but it is not permanent.
Setting the version on Apex, triggers, and components
Every Apex class and trigger carries its own API version, visible on the Version Settings area of the class in Setup. New classes default to the current release version, but you can pick any supported version when you create or edit them. Version Settings also pins the versions of any managed packages the code depends on, so an upgrade to a package does not silently change how your code calls it. Lightning components and Visualforce pages track an API version too. In a Salesforce DX project, the sourceApiVersion in sfdx-project.json sets the version metadata is written and retrieved against, while the CLI also has a separate apiVersion used for the API calls themselves. Keeping these aligned matters on a team. The Metadata API blog from Salesforce is blunt about it. Every developer sharing a repository should use the same API version, because mismatched versions cause deploy failures and can corrupt the shared source. Treat the version as a project-wide setting, not a per-developer preference, and change it on purpose through review rather than letting individual saves drift it around.
Retirement of old versions and the 2025 cutoff
Backward compatibility has limits. Salesforce periodically retires the oldest API versions so it is not maintaining decade-old logic forever. The clearest recent example is versions 21.0 through 30.0, which were deprecated and then retired as of the Summer '25 release across the SOAP, REST, and Bulk APIs. Once retired, those versions stop working. A REST call to a retired version returns 410 GONE. SOAP returns a 500 with UNSUPPORTED_API_VERSION. Bulk returns a 400 InvalidVersion. Any integration still pinned to one of those numbers simply fails. The risk lives in old, forgotten plumbing: outbound messages and connected apps built before 2014, an aging Data Loader, or AJAX Toolkit references baked into a Visualforce page. To find exposure before it bites, Salesforce points teams at the Event Log Browser and the ApiTotalUsage event, which expose the API version on each call. Filtering those logs for versions at or below the retirement threshold shows exactly which clients need attention. Retirement is announced well ahead through Release Updates, so the failures are avoidable if someone is watching.
Choosing a version strategy that ages well
There is no single correct version for everything, but there are sensible defaults. New Apex, new components, and new integrations should start on a current version so they can use the latest fields and methods. Existing code does not need to jump every release, since a working class on a slightly older version is fine and upgrading carries a small testing cost. The trap is letting things sit so long they fall into the retirement window. A practical rhythm is to review API versions once or twice a year, raise anything that has drifted far behind, and run regression tests in a sandbox before promoting the change. Pay special attention to integrations you do not own day to day, because those are the ones that quietly age out. Document the API version each integration uses so it shows up in reviews instead of being discovered during an outage. Treat the version as a maintained property of the system, the same way you treat a library dependency. Left alone it does not stay safe forever, it just stays quiet until a retirement turns the quiet into a failure.
Where the version shows up across the platform
The same concept appears in many places, which is part of why it confuses people. In a SOAP login or query, the version sits in the endpoint path or the request envelope. In REST, it is the vXX.0 segment of the URL, and Salesforce exposes a Versions resource that lists every version the org currently supports along with its label and base path. In the Metadata API, the version element in package.xml governs an entire deploy or retrieve. In Apex, it is Version Settings on the class. In a DX project it is two separate settings, one for source and one for the API calls. There is even a Version class in Apex that lets managed package code check which package version called it, so the same code can behave differently for different subscribers. The throughline is consistent. Wherever Salesforce code or a request meets the platform, a version number decides which generation of rules applies. Knowing where to read that number on each surface is most of what it takes to reason about why two things that look identical can behave differently.
Set the API version on an Apex class
You set the Salesforce API version on an Apex class or trigger from its Version Settings in Setup. This pins the platform behavior the code runs under and the versions of any managed packages it depends on. Use this to keep code on a deliberate, reviewed version rather than letting it drift.
- Open the class or trigger in Setup
Go to Setup and open the Apex Classes or Apex Triggers list. Click the name of the class or trigger you want to change, then click Edit to open it for changes. You need the relevant author or modify permission to edit Apex in that environment.
- Open the Version Settings tab
With the class open for editing, select the Version Settings tab. The Salesforce API Version field shows the version the code is currently saved against. This is the number that decides which platform behavior applies when the code runs.
- Choose the API version
Pick the API version you want from the list of supported versions. Move forward to a newer version to reach new fields and methods, or hold an older one if you need its behavior. Avoid any version near a published retirement so the code does not age out.
- Pin package versions and save
In the same tab, set the version for each managed package the code depends on so a package upgrade cannot silently change behavior. Save the class. In a team setting, make the change in source control so everyone deploys the same version.
The platform release version the class or trigger runs under, written as a decimal such as 64.0. It selects the feature and behavior set the code sees.
The pinned version of each installed managed package the code calls, so upgrading the package does not change how your code interacts with it.
Version Settings apply per class or trigger, so different pieces of code in the same org can run at different API versions on purpose.
- A field or method added in a newer release cannot be used by code saved at an older API version, even when the org is fully upgraded.
- Mismatched API versions across developers sharing a repository cause deploy failures, so set the version as a project decision, not a personal one.
- In Salesforce DX, sourceApiVersion and the CLI apiVersion are separate settings; keep them aligned to avoid confusing deploy and retrieve differences.
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Salesforce API Version.
Hands-on resources to go deeper on Salesforce API Version.
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 Salesforce API Version?
Q2. How often are new API versions released?
Q3. Why does versioning matter?
Discussion
Loading discussion…