Salesforce Platform API Versions 21.0 through 30.0 Retirement (May 10, 2023)

2024 Update: Final (maybe?) Retirement has been set for Summer ’25.

If you are interested in this article, I assume you received a “Salesforce Platform API Versions 21.0 through 30.0 Retirement” notification from Salesforce. Or maybe you noticed the release update and thought “uh oh”.

Spoiler Alert! Our free API Version Log Audit can identify and report on the impact of the API version retirement -> https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3u00000QrrhOEAR

Why did I receive a notification?

Salesforce has documented the pending API Version depreciation and retirement schedules for several releases.  However, due to the potential negative impact of these actions, Salesforce is now sending targeted emails to impacted instances.  Yes, make no mistake.  If you received the notification, you are most likely running processes leveraging API versions targeted for retirements. 

What exactly is Salesforce doing?

Plain and simple, API Versions 21.0 through 30.0 will be complete retired by the Summer ’23 release (May 10, 2023).  Any processes leveraging API versions lower than 31.0 need to be upgraded by their retirement date or they will fail. 

This includes:

In Summer ’22, the following API version will be depreciated.  They will be retired in Summer ’23.

  • SOAP: 21.0, 22.0, 23.0, 24.0, 25.0, 26.0, 27.0, 28.0, 29.0, 30.0
  • REST: v21.0, v22.0, v23.0, v24.0, v25.0, v26.0, v27.0, v28.0, v29.0, v30.0
  • Bulk: 21.0, 22.0, 23.0, 24.0, 25.0, 26.0, 27.0, 28.0, 29.0, 30.0

If you are interested in the complete Salesforce articles, check out the following on the topic:

API Versions 21.0 through 30.0 -> https://help.salesforce.com/s/articleView?id=000354473&type=1

For some perspective…

API Version 21.0 was released with Spring ’11.  2011!  The year Charlie Sheen was “Winning!” and planking was a thing.  

API Version 30.0 was released with Spring ’14.  2014!  The year we begged Pharrell to stop singing “Happy”.

What is Salesforce NOT doing?

This API Version retirement is specific to SOAP, REST and Bulk. Do not confuse this with internal API Versions related to internal apex classes, apex trigger, pages, etc.

What exactly do you need to do?

I’m going to break this down into two specific action items.

What exactly do you need to do… to ensure business continuity?

First and foremost, you obviously need to identify any processes running API Versions scheduled for retirement.  A step by step guide is provided below to extract your data.

Once identified, you need to devise a plan to upgrade to an API Version 31.0 or above (more on this in the next section).

Do not assume this is a basic task. Salesforce leverages API Versions to iterate and continually improve the platform.  Iterations can include the retirement/introduction of sObject and sObject relationships, retirement/introduction of sObject fields,  retirement/introduction on new processes, modification to existing processes, and changes to performance.

What exactly do you need to do… to get the most out of your instance?

As mentioned above, Salesforce leverages API Versions to iterate and continually improve the platform.  You are paying a premium for that constant innovation.  Take advantage!

Implement a process for constant improvement.  Implement a plan to consistently evaluate your API Versions to take advantage of improvements (versus constantly aiming for the bare minimum).

Every organization is different, so no plan fits all.  Consideration needs to be allotted to capacity, impact, etc.   I find a good rule of thumb to start with is to stay no more than 5 releases behind.  You can adjust from there for your specific implementation.  As of today, this means identifying and evaluating any API Version running 48.0 (Spring ’20) or below. (NOTE: This strategy should also apply to your apex class, apex triggers, pages, etc. but that is a topic for another day).

Again, this is a simplified catch all rule of thumb.  If for instance, you’re leveraging the REST API to execute a SOQL query such as “Select AccountNumber from Account where id = :id”, it’s unlikely an API Version upgrade on version provides much value.  However, if you’re leveraging the REST API to execute a SOQL query against the ContentVersion sObject, you’ll notice functionality changes in API Version 39.0 and  new fields introduced in API Version 31.0, 33.0, 34.0, 38.0, 40.0.  You will need to evaluate the impact of the version changes on your existing implementation.

Ok, Let’s get done to business.  How do I figure out what I’m up against?

Good News

If you are running Salesforce Shield, good news!  There are all sort of tools readily available for this analysis.  But, let’s be realistic, if you are running Salesforce shield, you probably have no need for this article.

Ok News

If you are not running Salesforce Shield, good news!  Salesforce has you covered but with some limitations that will defined later.  Let’s start with the good news.

Salesforce has introduced (in API Version 30.0) an Event Log Type called ApiTotalUsage which is available to all.  The Event Log Type is accessible via the EventLogFile object which is available via workbench.  To access this data, do the following:

  • Login into https://workbench.developerforce.com/ (follow the instructions to login in)
  • Navigate to Queries -> SOQL Query
  • Enter “SELECT id, EventType, CreatedDate FROM EventLogFile WHERE EventType = ‘ApiTotalUsage’ order by createddate desc”
  • Click on the Query button to execute the query.

SELECT id, EventType, CreatedDate FROM EventLogFile WHERE EventType = ‘ApiTotalUsage’ order by createddate desc

  • The query results will provide a list of all the ApiTotalUsage event files generated in the past 24 hours*.
  • To access the log file data, Navigate to Utilities -> REST Explorer
  • Enter the EventType ID corresponding to the event logs generated such as “/services/data/v52.0/sobjects/EventLogFile/0AT4p000009AAcWGAW/LogFile”
  • Review the results.  You are searching for any individual lines which have an API Version below your cutover. 
  • Trace the offending records back to their source.

That sounds pretty straightforward.  Is there a catch?

It’s a pretty straightforward process, but it has some limitations.

  • It’s manual.  An instance with heavy integrations maybe produce hundreds of event log file with thousands of individual log entry events.
  • Unless you are running Salesforce Shield, you only have access to the last 30 days of Event Logs.  If your integrations run s on demand or less than once a month, you will need to insure you monitor the logs daily in order to capture all the occurrences
  • If you set a API Version policy, new integrations can creep into your process.

Got a better option?

You bet. Introducing the API Version Log Audit now available on the app exchange (https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3u00000QrrhOEAR). The API Version Log Audit provides the ability to configure and schedule an automated API Version Audit.