---
# === IDENTITY ===
id: business/erp-integration/salesforce-api-versioning-deprecation/2026
canonical_question: "What is the Salesforce API versioning and deprecation policy - retirement timeline and minimum version?"
aliases:
  - "Salesforce API version retirement schedule"
  - "What is the minimum supported Salesforce API version?"
  - "Salesforce API deprecation timeline and sunset policy"
  - "How does Salesforce API version numbering work?"
entity_type: erp_integration
domain: business > erp-integration > salesforce-api-versioning-deprecation
region: global
jurisdiction: global
temporal_scope: 2017-2026

# === SYSTEM PROFILE ===
systems:
  - name: "Salesforce Platform"
    vendor: "Salesforce"
    version: "API v31.0-v66.0 (currently supported range)"
    edition: "All editions (Developer, Professional, Enterprise, Unlimited)"
    deployment: "cloud"
    api_surface: "REST, SOAP, Bulk, Bulk 2.0, Streaming, Metadata, Tooling, Connect, Pub/Sub"

# === VERIFICATION ===
last_verified: 2026-03-01
confidence: 0.92
version: 1.0
first_published: 2026-03-01

# === TEMPORAL VALIDITY ===
temporal_validity:
  status: volatile
  last_breaking_change: "Summer '25 (June 2025) — versions 21.0-30.0 retired"
  next_review: 2026-08-28
  change_sensitivity: high

# === CONSTRAINTS ===
constraints:
  - "Minimum supported API version is v31.0 as of Summer '25 — versions 21.0-30.0 permanently retired"
  - "3-year minimum support policy — versions older than 3 years may be deprecated at any time"
  - "1-year advance notice before retirement enforcement — but only for versions actively in use"
  - "Retired version calls return HTTP 410 GONE (REST), 500 UNSUPPORTED_API_VERSION (SOAP), 400 InvalidVersion (Bulk)"
  - "Version numbers are embedded in endpoint URLs — no automatic forwarding to newer versions"
  - "Salesforce releases 3 new API versions per year (Winter, Spring, Summer) — each increments by 1.0"

# === SKIP CONDITIONS ===
skip_this_unit_if:
  - condition: "User needs Salesforce REST API rate limits or integration patterns"
    use_instead: "business/erp-integration/salesforce-rest-api-capabilities/2026"
  - condition: "User needs Salesforce Bulk API guidance"
    use_instead: "business/erp-integration/salesforce-bulk-api/2026"
  - condition: "User needs versioning policy for a non-Salesforce ERP"
    use_instead: "business/erp-integration/{system}-api-versioning/2026"

# === AGENT HINTS ===
inputs_needed:
  - key: current_api_version
    question: "What API version is your integration currently using?"
    type: text
  - key: api_type
    question: "Which Salesforce API type are you using?"
    type: choice
    options:
      - "REST API"
      - "SOAP API"
      - "Bulk API v1"
      - "Bulk API 2.0"
      - "Metadata API"
      - "Tooling API"
      - "Streaming / Pub/Sub API"
  - key: concern
    question: "What is your primary concern?"
    type: choice
    options:
      - "Am I on a deprecated version?"
      - "When will my version be retired?"
      - "How do I upgrade API versions?"
      - "What changes between versions?"

# === DISTRIBUTION ===
canonical_source: "https://knowledgelib.io/business/erp-integration/salesforce-api-versioning-deprecation/2026"
suggested_citation: "Source: knowledgelib.io — AI Knowledge Library (verified 2026-03-01)"

# === RELATED UNITS ===
related_kos:
  depends_on: []
  related_to:
    - id: "business/erp-integration/salesforce-rest-api-capabilities/2026"
      label: "Salesforce REST API capabilities and rate limits"
  solves: []
  alternative_to: []
  often_confused_with: []

# === SOURCES ===
sources:
  - id: src1
    title: "API End-of-Life Policy — REST API Developer Guide"
    author: Salesforce
    url: https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/api_rest_eol.htm
    type: official_docs
    published: 2025-10-01
    reliability: authoritative
  - id: src2
    title: "Salesforce Platform API Versions 21.0 through 30.0 Retirement"
    author: Salesforce
    url: https://help.salesforce.com/s/articleView?id=000389618&language=en_US&type=1
    type: official_docs
    published: 2024-10-01
    reliability: authoritative
  - id: src3
    title: "New Tools to Help Prepare for API Version Retirement"
    author: Salesforce
    url: https://developer.salesforce.com/blogs/2024/10/new-tools-to-help-prepare-for-api-version-retirement
    type: technical_blog
    published: 2024-10-15
    reliability: high
  - id: src4
    title: "Make API Version Retirements a No-Op"
    author: Salesforce
    url: https://developer.salesforce.com/blogs/2021/08/make-api-version-retirements-a-no-op
    type: technical_blog
    published: 2021-08-01
    reliability: high
  - id: src5
    title: "Salesforce Releases and API Versions — Complete Mapping"
    author: Agile Winds
    url: https://agilewinds.com/salesforce-releases-and-api-versions/
    type: community_resource
    published: 2025-01-15
    reliability: moderate_high
  - id: src6
    title: "Legacy API Versions 21.0 Through 30.0 Retirement — Release Notes"
    author: Salesforce
    url: https://help.salesforce.com/s/articleView?id=release-notes.rn_api_upcoming_retirement.htm&language=en_US&release=238&type=5
    type: vendor_release_notes
    published: 2024-06-01
    reliability: authoritative
  - id: src7
    title: "Understanding Salesforce REST API Versioning — Key Questions Answered"
    author: MoldStud
    url: https://moldstud.com/articles/p-understanding-salesforce-rest-api-versioning-key-questions-answered-for-developers
    type: community_resource
    published: 2024-12-01
    reliability: moderate_high
---

# 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. On-premise deployments do not exist for Salesforce — all instances are cloud-hosted. [src1]

| Property | Value |
|---|---|
| **Vendor** | Salesforce |
| **System** | Salesforce Platform (all cloud editions) |
| **API Surface** | REST, SOAP, Bulk v1, Bulk 2.0, Metadata, Tooling, Connect, Streaming, Pub/Sub |
| **Current API Version** | v66.0 (Spring '26) |
| **Editions Covered** | Developer, Professional, Enterprise, Unlimited, Performance |
| **Deployment** | Cloud |
| **API Docs URL** | [Salesforce REST API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/) |
| **Status** | GA — versioning policy active and enforced |

## 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]

| API Surface | Protocol | Version in URL? | Retirement Error Code | Bulk? | Notes |
|---|---|---|---|---|---|
| REST API | HTTPS/JSON | Yes (`/services/data/v66.0/`) | 410 GONE | No | Primary integration surface |
| SOAP API | HTTPS/XML | Yes (WSDL version) | 500 UNSUPPORTED_API_VERSION | No | Legacy; requires new WSDL per version |
| Bulk API v1 | HTTPS/CSV/XML | Yes | 400 InvalidVersion | Yes | Being superseded by Bulk 2.0 |
| Bulk API 2.0 | HTTPS/CSV | Yes | 400 InvalidVersion | Yes | Recommended for bulk operations |
| Metadata API | HTTPS/XML | Yes (WSDL version) | 500 UNSUPPORTED_API_VERSION | No | Deploy/retrieve metadata |
| Tooling API | HTTPS/JSON | Yes | 410 GONE | No | Development tools and debugging |
| Connect API | HTTPS/JSON | Yes | 410 GONE | No | Chatter, Communities, CMS |
| Streaming API | Bayeux/CometD | Yes | Connection refused | No | PushTopic, Platform Events (legacy) |
| Pub/Sub API | gRPC | No (uses API version in config) | UNSUPPORTED_API_VERSION | No | Modern event streaming replacement |

## Version Numbering System

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

### Release Cadence

| Season | Typical Release Month | Sandbox Preview | Year Convention |
|---|---|---|---|
| Spring | January-February | Previous December | Same calendar year (Spring '26 = early 2026) |
| Summer | May-June | Previous April | Same calendar year (Summer '26 = mid 2026) |
| Winter | September-October | Previous August | Next calendar year (Winter '26 = late 2025) |

**Important**: The Winter release carries the year of the *upcoming* year. Winter '26 was released in September-October 2025, not 2026. This catches many integration teams off-guard. [src5]

### Version-to-Release Mapping (2017-2026)

| Release | API Version | Release | API Version | Release | API Version |
|---|---|---|---|---|---|
| Summer '17 | v40.0 | Summer '20 | v49.0 | Summer '23 | v58.0 |
| Winter '18 | v41.0 | Winter '21 | v50.0 | Winter '24 | v59.0 |
| Spring '18 | v42.0 | Spring '21 | v51.0 | Spring '24 | v60.0 |
| Summer '18 | v43.0 | Summer '21 | v52.0 | Summer '24 | v61.0 |
| Winter '19 | v44.0 | Winter '22 | v53.0 | Winter '25 | v62.0 |
| Spring '19 | v45.0 | Spring '22 | v54.0 | Spring '25 | v63.0 |
| Summer '19 | v46.0 | Summer '22 | v55.0 | Summer '25 | v64.0 |
| Winter '20 | v47.0 | Winter '23 | v56.0 | Winter '26 | v65.0 |
| Spring '20 | v48.0 | Spring '23 | v57.0 | Spring '26 | v66.0 |

[src5]

## 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

Salesforce retires API versions in waves, not individually. Historical pattern: [src2, src6]

| Wave | Versions Retired | Enforcement Date | Notice Given | Affected APIs |
|---|---|---|---|---|
| Wave 1 | v7.0-v20.0 | Summer '22 (June 2022) | ~1 year | REST, SOAP, Bulk v1 |
| Wave 2 | v21.0-v30.0 | Summer '25 (June 2025) | ~1 year | REST, SOAP, Bulk v1, Metadata, Tooling, Connect, Tableau CRM |
| Wave 3 (projected) | v31.0-v39.0 | Not yet announced | TBD | Expected to follow same pattern |

**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

Calling a retired API version produces different error responses depending on the API surface: [src3]

| API Surface | HTTP Status | Error Code | Response Body |
|---|---|---|---|
| REST API | 410 | GONE | `[{"errorCode":"GONE","message":"This API version has been decommissioned..."}]` |
| SOAP API | 500 | UNSUPPORTED_API_VERSION | SOAP fault with `UNSUPPORTED_API_VERSION` faultcode |
| Bulk API v1 | 400 | InvalidVersion | `InvalidVersion` error in XML response |
| Login API (SOAP) | 500 | UNSUPPORTED_API_VERSION | Cannot authenticate — breaks entire integration |

**Critical**: Some middleware platforms (Zapier, Informatica, legacy MuleSoft connectors) do not surface these errors clearly. The integration may appear to succeed but return no data. [src3]

## Rate Limits & Quotas

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

### Per-Request Limits (Unchanged by Version)

| Limit Type | Value | Applies To | Notes |
|---|---|---|---|
| Max records per SOQL query | 2,000 | REST/SOAP | Use `queryMore` for pagination; unchanged across versions |
| Max composite subrequests | 25 | Composite API | Introduced in v34.0; not available on retired versions |
| Max batch file size | 150 MB | Bulk API 2.0 | Available from v41.0+ |
| Max records per DML | 200 | REST API (non-composite) | Standard `sobjects/` endpoint |

### Version-Related Limits

| Limit Type | Value | Notes |
|---|---|---|
| Minimum supported version | v31.0 | As of Summer '25; calls below this return errors |
| Versions available simultaneously | ~35 | v31.0-v66.0 as of Spring '26 |
| New versions per year | 3 | Aligned with seasonal releases |
| Minimum support window | 3 years | Per official policy |
| Deprecation notice period | 1 year | For versions actively in use |

[src1]

## Authentication

Authentication is version-aware — you specify the API version in the login endpoint or token request. If you authenticate against a retired version, the login itself fails. [src2]

| Flow | Version Impact | Notes |
|---|---|---|
| OAuth 2.0 JWT Bearer | Token endpoint is version-independent (`/services/oauth2/token`) | Version only matters for subsequent API calls |
| OAuth 2.0 Web Server | Same — version-independent auth | Pin API version in resource requests, not auth |
| SOAP Login | Version-dependent (`/services/Soap/u/{version}/`) | Retired version = cannot authenticate at all |
| Username-Password OAuth | Version-independent | Legacy; not recommended |

### 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+), Einstein features (v50.0+) all require minimum versions. [src5]
- Sandbox and production may be on different releases during the preview window — 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+ (skip intermediate versions)
|   |   +-- 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 3-year support window? Check: version + 3 years of releases
|   |   |-- 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 do you want to manage versions going forward?
|   |-- Pin to specific version (recommended for stability)
|   |   |-- Lock integration to a specific version (e.g., v62.0)
|   |   |-- Re-evaluate every 4-6 releases (~18 months)
|   |   +-- Test against latest version in sandbox before upgrading
|   |-- Always use latest (maximum feature access)
|   |   |-- Requires regression testing every release (3x/year)
|   |   +-- Higher maintenance cost but never hit deprecation
|   +-- Stay N versions behind (balanced approach)
|       |-- Target: latest minus 3-6 versions
|       |-- Benefit: stability + known-good version
|       +-- Risk: still need to upgrade before 3-year window closes
|
+-- What API type are you using?
    |-- 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 (available since v41.0)
    +-- Streaming → Consider migrating to Pub/Sub API (available since v53.0)
```

## Quick Reference

### Version Status Matrix (as of Spring '26)

| Version Range | Status | Retirement Date | Action Required |
|---|---|---|---|
| v7.0-v20.0 | Retired | Summer '22 (June 2022) | Upgrade immediately — calls fail with errors |
| v21.0-v30.0 | Retired | Summer '25 (June 2025) | Upgrade immediately — calls fail with errors |
| v31.0-v39.0 | Supported (aging) | Not yet announced | Plan upgrade within 12 months |
| v40.0-v55.0 | Supported | Not yet announced | Monitor deprecation notices |
| v56.0-v66.0 | Supported (current) | 3+ years from now | No action needed |

[src1, src2, src6]

### Key Version Milestones

| API Version | Release | Milestone Feature |
|---|---|---|
| v34.0 | Summer '15 | Composite API introduced |
| v41.0 | Winter '18 | Bulk API 2.0 introduced |
| v43.0 | Summer '18 | Change Data Capture (CDC) |
| v45.0 | Spring '19 | Lightning Web Components (LWC) GA |
| v47.0 | Winter '20 | Einstein Prediction Builder API |
| v50.0 | Winter '21 | Salesforce Functions (beta) |
| v53.0 | Winter '22 | Pub/Sub API introduced |
| v55.0 | Summer '22 | Wave 1 retirement enforced (v7.0-v20.0) |
| v59.0 | Winter '24 | Recommended minimum for new integrations |
| v62.0 | Winter '25 | Retirement enforcement toggle GA |
| v64.0 | Summer '25 | Wave 2 retirement enforced (v21.0-v30.0) |
| v66.0 | Spring '26 | Current latest version |

[src5, src6]

## Step-by-Step Version Upgrade Guide

### 1. Identify your current API version

Query your Salesforce org to see all available API versions and confirm which one your integrations use. [src1]

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

# Response includes array of supported versions:
# [{"version":"66.0","label":"Spring '26","url":"/services/data/v66.0"}, ...]
```

**Verify**: Response contains an array of version objects. Your current version should be in the list.

### 2. Audit integrations using deprecated versions

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

```bash
# 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"

# Download the CSV and filter for deprecated API_VERSION values
# Key columns: API_VERSION, CLIENT_NAME, CONNECTED_APP_ID, USER_ID, CLIENT_IP
```

**Verify**: CSV file downloaded. Filter `API_VERSION` column for versions <= 30.0 to find deprecated usage.

### 3. Test retirement enforcement in sandbox

Enable voluntary retirement enforcement in sandbox before production deadline. [src3]

```
Setup > Search "API Version" > Enable "Retirement Enforcement"
This makes deprecated API calls fail immediately in sandbox,
letting you identify all affected integrations before production enforcement.
```

**Verify**: API calls to retired versions (e.g., v28.0) return 410 GONE in sandbox.

### 4. Update API version in integrations

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

```bash
# 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
# Then update WSDL file in your integration codebase

# Bulk API: Update version in job creation endpoint
# OLD: /services/async/28.0/job
# NEW: /services/data/v66.0/jobs/ingest  (Bulk 2.0 recommended)
```

**Verify**: Integration requests return 200 OK with expected data from the new version endpoint.

### 5. Regression test for breaking changes

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

```bash
# 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 for any field additions, removals, or type changes.

## Code Examples

### Python: Check API version support and audit usage

```python
# 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()
    # Download and parse CSV log files
    # Filter for API_VERSION < min_safe
    for record in resp.json().get("records", []):
        log_url = f"{instance_url}{record['LogFile']}"
        log_resp = requests.get(log_url, headers=headers)
        # Parse CSV, filter deprecated versions
        print(f"Log file: {log_url}")
```

### JavaScript/Node.js: Version-aware API client

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

// npm install jsforce@1.11.1
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

```bash
# 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

| Code | API | Meaning | Cause | Resolution |
|---|---|---|---|---|
| 410 GONE | REST, Tooling, Connect | Version retired | Using API version below minimum | Upgrade to v31.0+ (recommended: v59.0+) |
| 500 UNSUPPORTED_API_VERSION | SOAP, Metadata | Version retired | WSDL generated from retired version | Regenerate WSDL from current version |
| 400 InvalidVersion | Bulk v1, Bulk 2.0 | Version retired or invalid | Version number in job URL is retired | Update version in job creation endpoint |
| 400 Bad Request | REST | Invalid version format | Malformed version string (e.g., `v66` instead of `v66.0`) | Always use `vNN.0` format with decimal |

[src1, src3]

### Failure Points in Production

- **Silent middleware failures**: Some iPaaS platforms (legacy MuleSoft, Informatica PowerCenter) 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 — not just the deprecated calls. 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 (and retirement enforcement) before production. Fix: `Include API version validation in CI/CD pipeline. Test against both current and upcoming versions.` [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 integration code per environment.` [src3]

## Anti-Patterns

### Wrong: Hardcoding the latest API version and forgetting about it

```python
# 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

```python
# 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

```javascript
// BAD -- mixing versions causes inconsistent behavior and harder upgrades
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

```javascript
// 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

```bash
# 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

```bash
# 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 (which has new release)
npm run deploy:sandbox

# 3. Run integration test suite against sandbox
SF_INSTANCE=sandbox npm run test:integration

# 4. Enable retirement enforcement in sandbox to catch any lingering old calls
# Setup > API Version Settings > Enable Retirement Enforcement

# 5. Run tests again with enforcement enabled
SF_INSTANCE=sandbox npm run test:integration

# 6. Review release notes for behavioral changes between v50.0 and v66.0
# 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. Update during maintenance windows.` [src4]
- **Assuming backward compatibility**: Salesforce strives for compatibility but does not guarantee it. Field type changes, deprecated fields, and new required parameters can break integrations. Fix: `Review release notes for each version between current and target. Focus on objects your integration uses.` [src7]
- **Ignoring the Winter release year convention**: Winter '26 = September/October 2025, not 2026. Teams planning for "Winter '26 changes by January 2026" are 3 months late. Fix: `Map release names to calendar dates in your planning tool. Winter = fall of previous calendar year.` [src5]
- **Upgrading SOAP without regenerating WSDL**: SOAP integrations require new WSDL files for each version — you cannot simply change a version number. Fix: `Download fresh WSDL from Setup > API > Generate Enterprise/Partner WSDL. Rebuild SOAP stubs.` [src4]
- **Not using Sforce-Call-Options header**: Without the `Sforce-Call-Options: client=MyApp` header, you cannot trace which application is making deprecated API calls. Fix: `Add Sforce-Call-Options header to all API calls for audit trail.` [src3]
- **Ignoring version retirement in AppExchange packages**: 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 for updates before retirement deadlines.` [src3]

## Diagnostic Commands

```bash
# 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
# In Developer Console or VS Code: search for pattern /v\d+\.0/
# 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

| API Version | Release | Status (as of Mar 2026) | Breaking Changes | Migration Notes |
|---|---|---|---|---|
| v66.0 | Spring '26 | Current | None yet | Latest recommended version |
| v65.0 | Winter '26 | Supported | SOAP login() removed for some contexts | Check login endpoint |
| v64.0 | Summer '25 | Supported | v21.0-v30.0 retired | Wave 2 retirement enforced |
| v62.0 | Winter '25 | Supported | Retirement enforcement toggle GA | Use for testing deprecation |
| v59.0 | Winter '24 | Supported | None significant | Recommended minimum for new integrations |
| v55.0 | Summer '22 | Supported | v7.0-v20.0 retired | Wave 1 retirement enforced |
| v41.0 | Winter '18 | Supported (aging) | Bulk API 2.0 introduced | Consider Bulk 2.0 migration |
| v31.0 | Spring '14 | Supported (oldest) | None | Current minimum — next retirement wave candidate |
| v30.0 | Spring '14 | **Retired** | — | Retired Summer '25 — upgrade to v31.0+ |
| v20.0 | Winter '11 | **Retired** | — | Retired Summer '22 — upgrade to v31.0+ |

[src1, src2, src5, src6]

### Deprecation Policy

Salesforce supports each API version for a minimum of 3 years from first release. Versions are retired in waves of approximately 10 versions. Customers using a version scheduled for deprecation receive at least 1 year of notice. Use the free ApiTotalUsage event log to monitor your org's API version usage proactively. [src1, src3]

## When to Use / When Not to Use

| Use When | Don't Use When | Use Instead |
|---|---|---|
| Planning an API version upgrade or migration | Need rate limits or integration patterns for a specific API | Salesforce REST API capabilities card |
| Checking if your current API version is still supported | Need authentication flow details | Salesforce authentication card |
| Understanding the retirement timeline before it breaks production | Need help with a non-Salesforce ERP's versioning | That ERP's versioning card |
| Auditing AppExchange packages for deprecated versions | Need Bulk API migration guidance | Salesforce Bulk API card |
| Setting up CI/CD pipeline version validation | Need Salesforce licensing/edition comparison | Salesforce edition comparison card |

## 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 based on historical patterns.
- 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 than legacy instances.
- This card covers platform API versioning only. Salesforce Marketing Cloud, Commerce Cloud, and MuleSoft have separate versioning policies and cadences.
- 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.

## Related Units

- [Salesforce REST API Capabilities](/business/erp-integration/salesforce-rest-api-capabilities/2026)