Salesforce API Versioning and Deprecation Policy

TL;DR

• Bottom line: Salesforce guarantees minimum 3-year support per API version, releases 3 new versions annually (Winter/Spring/Summer), and retires old versions in waves with 1-year advance notice. [src1]
• Key limit: As of Summer '25, minimum supported version is v31.0 — versions 21.0-30.0 are permanently retired and return HTTP 410 GONE. [src2]
• Watch out for: Retired versions fail silently in some middleware — you may not get a clear error until production breaks. Always test with retirement enforcement enabled in sandbox. [src3]
• Best for: Planning integration version upgrades, understanding deprecation timelines, and avoiding surprise breakage from version retirement.
• Current version: Spring '26 = API v66.0 (released February 2026). [src5]

System Profile

This card covers the Salesforce Platform API versioning and deprecation lifecycle across all API surfaces — REST, SOAP, Bulk v1, Bulk 2.0, Metadata, Tooling, Connect, Streaming, and Pub/Sub. The policy applies uniformly to all Salesforce editions (Developer, Professional, Enterprise, Unlimited, Performance) though API call limits vary by edition. All Salesforce instances are cloud-hosted. [src1]

API Surfaces & Capabilities

All Salesforce API surfaces share the same version numbering scheme and deprecation policy. Each new platform release increments the version number by 1.0 across all surfaces simultaneously. [src1]

Version Numbering System

Salesforce releases 3 major platform updates per year, each incrementing the API version by 1.0. [src5]

Release Cadence

Important: The Winter release carries the year of the upcoming year. Winter '26 was released in September-October 2025, not 2026. [src5]

Version-to-Release Mapping (2017-2026)

Deprecation Policy

The Official 3-Year / 1-Year Rule

Salesforce's API End-of-Life policy has two core guarantees: [src1]

1. Minimum 3-year support: Each API version is supported for at least 3 years from its release date.
2. 1-year deprecation notice: Customers actively using a version scheduled for retirement receive at least 1 year of advance notice.

Retirement Wave History

Pattern observation: Waves retire ~10 versions at a time, spaced approximately 3 years apart. If the pattern holds, v31.0-v39.0 retirement could be announced around 2027-2028 — but this is not confirmed by Salesforce. [src2]

What Happens When a Version Is Retired

[src3]

Rate Limits & Quotas

Rate limits are not version-specific — they are org-wide and edition-dependent. However, version retirement effectively sets a rate limit of zero for retired versions. [src1]

Version-Related Limits

Authentication

Authentication is version-aware — SOAP login uses versioned endpoints, while OAuth 2.0 token endpoints are version-independent. [src2]

Authentication Gotchas

• SOAP login uses version-specific WSDL — if your WSDL was generated from a retired version, you cannot authenticate. Regenerate from a current version. [src2]
• OAuth 2.0 token endpoints are version-independent, but subsequent API calls must use a supported version in the URL path. [src1]
• Some middleware hardcodes the API version in the SOAP login URL — check connector settings, not just your code. [src3]

Constraints

• Retired API versions return hard errors with no fallback — there is no automatic version forwarding or graceful degradation. [src1]
• SOAP integrations require regenerating the WSDL file when upgrading versions — you cannot simply change a version number. [src4]
• Version retirement is org-wide — you cannot maintain different minimum versions for different connected apps. [src1]
• Feature availability is version-gated — Composite API (v34.0+), Bulk 2.0 (v41.0+), Pub/Sub API (v53.0+) all require minimum versions. [src5]
• Sandbox and production may be on different releases during preview windows — sandbox gets the new version ~4 weeks before production. [src3]
• No version-specific SLAs — Salesforce does not guarantee performance or uptime for versions nearing end of life. [src1]

Integration Pattern Decision Tree

START — User has a Salesforce integration and needs version guidance
|-- What is your current API version?
|   |-- v30.0 or below
|   |   |-- URGENT: Already retired as of Summer '25
|   |   |-- Action: Upgrade immediately to v59.0+
|   |   +-- Generate new WSDL if SOAP; update URL paths if REST
|   |-- v31.0-v39.0
|   |   |-- SAFE for now, but at risk in next retirement wave
|   |   |-- Action: Plan upgrade within 12 months
|   |   +-- Target: Latest GA version (v66.0 as of Spring '26)
|   |-- v40.0-v55.0
|   |   |-- Within support window but aging
|   |   |-- Action: Upgrade during next quarterly maintenance window
|   |   +-- Focus: Test for breaking changes in release notes
|   +-- v56.0+
|       |-- Current and fully supported
|       +-- Action: Monitor release notes for deprecation announcements
|
|-- How to manage versions going forward?
|   |-- Pin to specific version (recommended for stability)
|   |-- Always use latest (max feature access, 3x/year testing)
|   +-- Stay N versions behind (balanced approach)
|
+-- What API type?
    |-- REST/Bulk 2.0 -> Change version number in URL path
    |-- SOAP/Metadata -> Regenerate WSDL from current version
    |-- Bulk v1 -> Consider migrating to Bulk 2.0 (v41.0+)
    +-- Streaming -> Consider migrating to Pub/Sub API (v53.0+)

Quick Reference

Version Status Matrix (as of Spring '26)

[src1, src2, src6]

Key Version Milestones

[src5, src6]

Step-by-Step Version Upgrade Guide

1. Identify your current API version

Query your Salesforce org to see all available API versions. [src1]

# List all supported API versions for your org
curl https://YOUR_INSTANCE.salesforce.com/services/data/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Verify: Response contains an array of version objects with version, label, and url fields.

2. Audit integrations using deprecated versions

Use Event Log File Browser or API Total Usage to find integrations on old versions. [src3]

# Query API Total Usage event logs via REST
curl "https://YOUR_INSTANCE.salesforce.com/services/data/v66.0/query?q=SELECT+LogFile+FROM+EventLogFile+WHERE+EventType='ApiTotalUsage'+AND+CreatedDate=TODAY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Verify: CSV file downloaded. Filter API_VERSION column for versions <= 30.0.

3. Test retirement enforcement in sandbox

Enable voluntary retirement enforcement to identify affected integrations before production. [src3]

Setup > Search "API Version" > Enable "Retirement Enforcement"
This makes deprecated API calls fail immediately in sandbox.

Verify: API calls to retired versions return 410 GONE in sandbox.

4. Update API version in integrations

For each identified integration, update the version reference. [src4]

# REST API: Change version in URL path
# OLD: /services/data/v28.0/sobjects/Account
# NEW: /services/data/v66.0/sobjects/Account

# SOAP API: Regenerate WSDL from Setup > API > Generate WSDL

# Bulk API: Update version in job creation endpoint
# Recommend migrating to Bulk 2.0:
# NEW: /services/data/v66.0/jobs/ingest

Verify: Integration requests return 200 OK with expected data.

5. Regression test for breaking changes

Check release notes for behavioral changes between your old and new version. [src7]

# Test key operations against new version in sandbox
# 1. Authentication
curl -X POST https://YOUR_INSTANCE.salesforce.com/services/oauth2/token \
  -d "grant_type=password&client_id=...&client_secret=...&username=...&password=..."

# 2. Query a known record
curl "https://YOUR_INSTANCE.salesforce.com/services/data/v66.0/query?q=SELECT+Id,Name+FROM+Account+LIMIT+1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# 3. Create a test record
curl -X POST "https://YOUR_INSTANCE.salesforce.com/services/data/v66.0/sobjects/Account" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"Name":"API Version Test"}'

Verify: All operations return expected results. Compare response schemas between old and new versions.

Code Examples

Python: Check API version support and audit usage

# Input:  Salesforce access token and instance URL
# Output: List of supported API versions and deprecated version usage

import requests

def check_api_versions(instance_url, access_token):
    """List all supported API versions for the org."""
    headers = {"Authorization": f"Bearer {access_token}"}
    resp = requests.get(f"{instance_url}/services/data/", headers=headers)
    resp.raise_for_status()
    versions = resp.json()

    min_version = float(versions[0]["version"])
    max_version = float(versions[-1]["version"])
    print(f"Supported range: v{min_version} - v{max_version}")
    print(f"Total supported versions: {len(versions)}")
    return versions

def find_deprecated_usage(instance_url, access_token, min_safe="31.0"):
    """Query event logs for API calls using deprecated versions."""
    headers = {"Authorization": f"Bearer {access_token}"}
    soql = (
        "SELECT LogFile FROM EventLogFile "
        "WHERE EventType='ApiTotalUsage' "
        "AND CreatedDate=LAST_N_DAYS:7"
    )
    resp = requests.get(
        f"{instance_url}/services/data/v66.0/query",
        params={"q": soql},
        headers=headers
    )
    resp.raise_for_status()
    for record in resp.json().get("records", []):
        log_url = f"{instance_url}{record['LogFile']}"
        log_resp = requests.get(log_url, headers=headers)
        print(f"Log file: {log_url}")

JavaScript/Node.js: Version-aware API client

// Input:  Salesforce credentials, target API version
// Output: API client that validates version before making calls

// npm install [email protected]
const jsforce = require('jsforce');

const MINIMUM_SAFE_VERSION = 31;
const RECOMMENDED_VERSION = 66;

async function createVersionAwareClient(loginUrl, username, password) {
  const conn = new jsforce.Connection({
    loginUrl,
    version: `${RECOMMENDED_VERSION}.0`
  });

  await conn.login(username, password);

  // Verify the version is supported
  const versions = await conn.request('/services/data/');
  const supported = versions.map(v => parseFloat(v.version));
  const min = Math.min(...supported);
  const max = Math.max(...supported);

  console.log(`Org supports: v${min} - v${max}`);
  console.log(`Client using: v${RECOMMENDED_VERSION}.0`);

  if (RECOMMENDED_VERSION < min || RECOMMENDED_VERSION > max) {
    throw new Error(`Version ${RECOMMENDED_VERSION}.0 not supported`);
  }

  return conn;
}

cURL: Quick version check

# Input:  Instance URL and access token
# Output: List of all supported API versions

# Check supported versions (no version number needed in URL)
curl -s https://YOUR_INSTANCE.salesforce.com/services/data/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" | python3 -m json.tool

# Test if a specific version is still supported
curl -s -o /dev/null -w "%{http_code}" \
  "https://YOUR_INSTANCE.salesforce.com/services/data/v31.0/sobjects/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
# 200 = supported, 410 = retired

# Check API usage limits (version-independent)
curl -s https://YOUR_INSTANCE.salesforce.com/services/data/v66.0/limits/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" | python3 -m json.tool

Error Handling & Failure Points

Common Error Codes

[src1, src3]

Failure Points in Production

• Silent middleware failures: Some iPaaS platforms swallow 410 errors and return empty result sets instead of failing visibly. Fix: Enable alerting on zero-record API responses and 4xx/5xx status codes. [src3]
• SOAP login failure cascades: If SOAP login endpoint uses a retired version, all downstream operations fail. Fix: Separate login WSDL version from data API WSDL version. Update login WSDL first. [src2]
• Hardcoded versions in packages: Managed AppExchange packages may contain hardcoded API versions. Fix: Contact ISV for updated package version. Check package API version in Setup > Installed Packages. [src3]
• CI/CD pipeline breakage: Test environments may receive new releases before production. Fix: Include API version validation in CI/CD pipeline. [src4]
• Sandbox-production version mismatch: During preview windows, sandbox runs the new release while production runs the old one. Fix: Maintain version-flexible integrations or branch per environment. [src3]

Anti-Patterns

Wrong: Hardcoding the latest API version and forgetting about it

# BAD -- version will eventually be retired, breaking the integration
SALESFORCE_API_VERSION = "v55.0"  # Set once in 2022, never updated
BASE_URL = f"https://myorg.salesforce.com/services/data/{SALESFORCE_API_VERSION}"

Correct: Centralized version configuration with monitoring

# GOOD -- single config point, easy to update, with deprecation checking
import os

SALESFORCE_API_VERSION = os.environ.get("SF_API_VERSION", "v66.0")
BASE_URL = f"https://myorg.salesforce.com/services/data/{SALESFORCE_API_VERSION}"

def check_version_health(instance_url, token):
    """Run at startup to warn about approaching deprecation."""
    versions = requests.get(f"{instance_url}/services/data/",
                           headers={"Authorization": f"Bearer {token}"}).json()
    supported = [v["version"] for v in versions]
    current = SALESFORCE_API_VERSION.replace("v", "")
    if current not in supported:
        raise RuntimeError(f"API version {current} is no longer supported!")
    idx = supported.index(current)
    if idx < len(supported) * 0.2:  # Bottom 20% of supported range
        print(f"WARNING: Version {current} is aging. Consider upgrading.")

Wrong: Using different API versions across integration endpoints

// BAD -- mixing versions causes inconsistent behavior
const accountUrl = '/services/data/v50.0/sobjects/Account';
const contactUrl = '/services/data/v55.0/sobjects/Contact';
const queryUrl = '/services/data/v62.0/query';

Correct: Single version constant used everywhere

// GOOD -- one version, one upgrade path, consistent behavior
const SF_API_VERSION = 'v66.0';
const accountUrl = `/services/data/${SF_API_VERSION}/sobjects/Account`;
const contactUrl = `/services/data/${SF_API_VERSION}/sobjects/Contact`;
const queryUrl = `/services/data/${SF_API_VERSION}/query`;

Wrong: Skipping regression testing when upgrading versions

# BAD -- blindly changing version number without testing
sed -i 's/v50.0/v66.0/g' src/salesforce-client.js
git commit -m "Upgrade SF API version"
git push origin main  # Deploy to production untested

Correct: Systematic version upgrade with sandbox testing

# GOOD -- test in sandbox with retirement enforcement enabled
# 1. Update version in feature branch
sed -i 's/v50.0/v66.0/g' src/salesforce-client.js
# 2. Deploy to sandbox
npm run deploy:sandbox
# 3. Run integration test suite
SF_INSTANCE=sandbox npm run test:integration
# 4. Enable retirement enforcement in sandbox
# 5. Run tests again with enforcement enabled
# 6. Review release notes for behavioral changes
# 7. Only then merge and deploy to production

Common Pitfalls

• Not tracking API version in configuration: Many teams hardcode API versions in code rather than configuration. Fix: Externalize SF_API_VERSION as an environment variable. [src4]
• Assuming backward compatibility: Salesforce strives for compatibility but does not guarantee it. Field type changes and deprecated fields can break integrations. Fix: Review release notes for each version between current and target. [src7]
• Ignoring Winter release year convention: Winter '26 = September/October 2025, not 2026. Teams planning for "Winter '26 by January 2026" are 3 months late. Fix: Map release names to calendar dates. [src5]
• Upgrading SOAP without regenerating WSDL: SOAP integrations require new WSDL files — you cannot simply change a version number. Fix: Download fresh WSDL from Setup > API > Generate Enterprise/Partner WSDL. [src4]
• Not using Sforce-Call-Options header: Without this header, you cannot trace which application is making deprecated API calls. Fix: Add Sforce-Call-Options: client=MyApp header to all API calls. [src3]
• Ignoring AppExchange package versions: Managed packages contain their own API version settings. An unupdated package can break even if your code is current. Fix: Audit installed packages quarterly. Contact ISVs before retirement deadlines. [src3]

Diagnostic Commands

# Check all supported API versions for your org
curl -s https://YOUR_INSTANCE.salesforce.com/services/data/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Test if a specific version is supported (200 = yes, 410 = retired)
curl -s -o /dev/null -w "%{http_code}" \
  "https://YOUR_INSTANCE.salesforce.com/services/data/v31.0/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Check current API limits (use latest version)
curl -s "https://YOUR_INSTANCE.salesforce.com/services/data/v66.0/limits/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Query event logs for deprecated version usage (last 7 days)
curl -s "https://YOUR_INSTANCE.salesforce.com/services/data/v66.0/query?q=SELECT+LogFile,EventType+FROM+EventLogFile+WHERE+EventType='ApiTotalUsage'+AND+CreatedDate=LAST_N_DAYS:7" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Check Apex classes for hardcoded API versions
# SOQL: SELECT Name, ApiVersion FROM ApexClass WHERE ApiVersion < 31

# Check installed package API versions
curl -s "https://YOUR_INSTANCE.salesforce.com/services/data/v66.0/tooling/query?q=SELECT+Name,ApiVersion+FROM+ApexClass+WHERE+NamespacePrefix!=null+AND+ApiVersion<31" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Version History & Compatibility

[src1, src2, src5, src6]

When to Use / When Not to Use

Important Caveats

• The 3-year minimum support is a minimum — Salesforce has historically supported versions much longer (v31.0 was released in 2014 and is still supported in 2026). Do not assume retirement happens exactly at 3 years.
• Retirement waves have historically been announced at major events (Dreamforce, TrailblazerDX). The next wave (v31.0-v39.0) has not been announced — the projected timeline is speculative.
• Sandbox environments receive new releases 4-6 weeks before production. Your sandbox may enforce retirement before production does.
• API version availability varies slightly by instance — hyperforce instances may roll out at different times.
• This card covers platform API versioning only. Marketing Cloud, Commerce Cloud, and MuleSoft have separate versioning policies.
• Version numbers in this card are accurate as of Spring '26 (v66.0). Salesforce releases 3 new versions per year — check release notes for the latest.