API Version
An API Version in Salesforce is the numbered release of the platform's APIs (SOAP, REST, Bulk, Streaming, Metadata, Tooling, Connect, Pub/Sub) that callers and Apex code pin to so the contract stays stable across Salesforce releases.
Definition
An API Version in Salesforce is the numbered release of the platform's APIs (SOAP, REST, Bulk, Streaming, Metadata, Tooling, Connect, Pub/Sub) that callers and Apex code pin to so the contract stays stable across Salesforce releases. Versions follow a major-minor pattern: 60.0, 61.0, 62.0, and so on. A new version ships with each Salesforce major release (Spring, Summer, Winter), bringing new objects, new fields, new endpoints, and occasionally renamed or removed ones. Apex classes carry their API version in metadata. SOAP and REST callers send it in the URL or the WSDL. Each Salesforce release adds the new version while keeping older ones available, usually for at least three years.
Pinning to an API version is the platform's main backward-compatibility lever. An Apex class written against API 50.0 keeps running unchanged through release after release because the platform honours the original 50.0 behaviour. An integration that calls /services/data/v55.0 stays on that contract until the integration owner upgrades the URL. The trade-off is staleness: behaviour fixed at 50.0 misses every subsequent improvement (new fields, performance optimisations, security upgrades). Salesforce periodically retires old API versions, giving customers years of notice but eventually forcing the upgrade.
How API Version pinning shapes Salesforce development
The release cadence and version numbering
Salesforce ships three major releases per year (Spring, Summer, Winter). Each release bumps the API version by one whole number: Summer 24 was API 61.0, Winter 25 was API 62.0, Spring 25 was API 63.0. Minor versions are rare (point releases like 50.1 do not generally exist; 50.0 stays 50.0 forever). The version number identifies the contract, not a build.
Apex class metadata and the apiVersion field
Every ApexClass and Trigger stores an apiVersion value in metadata. The value is set when the class is created (defaulting to the current release) and can be updated by editing the metadata file. The class then runs against that contract: SOQL behaviour, object field availability, governor limits, and platform methods all behave as they did in that version. Editing the apiVersion field is a deliberate change with potential behaviour shifts.
REST and SOAP version selection
REST API callers include the version in the path: /services/data/v60.0/sobjects/Account/. SOAP callers use the version embedded in the WSDL they fetched. Bulk, Tooling, Metadata, and Streaming APIs follow the same pattern. The version in the URL or WSDL determines the contract the call gets, not the version of the Salesforce org.
What changes between versions
Each release notes document lists new objects, new fields, deprecated fields, and behavior changes per API version. A typical version brings 5 to 20 new objects, dozens of new fields, and a handful of deprecation announcements. Occasional larger shifts (the move from Bulk API 1.0 to 2.0, the addition of GraphQL API) introduce parallel surfaces rather than rewriting the old contract.
Version retirement and the EOL timeline
Salesforce maintains the three most recent major versions plus older versions on a deprecation timeline. Versions older than about three years move to retirement with advance notice (often 12 to 18 months). Once retired, calls to that version fail. The Critical Update tracking surface and release notes give the schedule; production teams should subscribe.
Implications for managed packages
Managed packages pin their Apex classes to a specific API version per release. ISVs upgrade the apiVersion across their package versions, testing each upgrade for regression. Subscribers receive the upgraded package; the class then runs at the new version. ISVs who lag on apiVersion expose subscribers to deprecated behaviour and miss platform improvements.
Common pitfalls
Three patterns recur. The first is silent reliance on undocumented behaviour from an old version that breaks on upgrade. The second is mixing versions inside one project (Apex on 50.0, REST callouts on 55.0); inconsistency makes triage harder. The third is staying too far back to avoid one deprecation, only to face a forced upgrade with three years of accumulated behaviour change at once.
Upgrade strategy
Production teams typically upgrade Apex classes one or two versions per year and pin REST integrations to the same target. The pattern is to lift apiVersion incrementally, run the regression suite, ship to sandboxes, then promote. Skipping multiple versions at once compresses years of behaviour change into one release and makes regression triage harder than necessary.
How to manage API Versions in a Salesforce codebase
Version hygiene is a quiet, ongoing discipline. Done well it pays off invisibly; ignored, it surfaces at the worst possible moment as a forced upgrade or a deprecation outage.
- Inventory current API versions
Query the org's ApexClass and ApexTrigger metadata. Inspect REST callout code and Named Credentials for the version segment. Build a table of which artifacts run at which version.
- Pick a target version
Choose a target API version for the next quarter. Most teams target N-1 or N-2 (one or two releases behind current). Going to N requires testing every new release's behaviour changes.
- Upgrade Apex classes incrementally
Edit metadata to bump apiVersion. Run the test suite per class. Investigate any regressions against the release notes for that version. Promote in stages.
- Update REST and SOAP callers
Update the version segment in callout code and refresh WSDLs for SOAP integrations. Document the new contract for downstream consumers.
- Monitor for deprecation announcements
Subscribe to release notes. Track which API versions are scheduled for retirement and plan the upgrade well before the cutover date.
- apiVersion changes can shift SOQL behaviour, governor limits, and method signatures silently. Test the regression suite after every bump.
- Mixing versions across one project makes triage harder. Pick a target version per release and apply it consistently.
- Staying too far back to avoid one deprecation accumulates years of change into a single forced upgrade.
- Managed package classes carry their own apiVersion. Subscribers cannot edit it; upgrading the package is the only way.
Trust & references
Cross-checked against the following references.
- Salesforce API Version RetirementSalesforce Help
- Salesforce SOAP API Release NotesSalesforce Developer Docs
Straight from the source - Salesforce's reference material on API Version.
- REST API Developer GuideSalesforce 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. How often does Salesforce release a new API version?
Q2. Why does Salesforce pin each metadata component to a specific API version?
Q3. What eventually happens to very old API versions?
Discussion
Loading discussion…