Managing API versions

This topic covers Salesforce API versions, how they affect your Salesforce DevOps workflows, and how to use the settings provided by OrgFlow to manage API versions effectively and achieve the desired results in your metadata change flow.

API version layers

Salesforce API versions are used in several different layers of the Salesforce APIs and the metadata you retrieve and deploy. Though the API version numbers available to you are the same, what they actually mean and how they work differs between different layers.

Platform version

The platform version of a Salesforce org is the version of Salesforce that's physically installed on the org (or, more accurately, on the instance that the org is hosted on). For example, after the major Salesforce release Summer '25 (API version 64) is installed on an org, that becomes the org's platform version. An org's platform version can also be thought of as the highest API version supported by the org.

The platform version of a Salesforce org influences the payload of retrieved and deployed metadata, because when a new platform version is installed, the upgrade often modifies metadata content (for example, some new standard objects might be created as part of the upgrade). The platform version also (somewhat unintuitively) determines which metadata types are supported by source tracking.

There is nothing you or OrgFlow can do to influence the platform version — it is entirely determined by the scheduling of Salesforce's maintenance operations.

Metadata API endpoint version

Regardless of the platform version, the Salesforce metadata API itself is versioned in two different ways. The first is the endpoint version which corresponds to two things:

1. The version number specified in the endpoint URL when calling the metadata API (e.g. https://acme.my.salesforce.com/services/Soap/m/64.0 corresponds to metadata API endpoint version 64.0)
2. The corresponding version of the metadata API WSDL file that describes the supported operations, requests and responses

The endpoint version influences several limits that govern how OrgFlow can interact with the metadata API, such as the maximum number of metadata components that can be retrieved in a single batch, or the maximum allowable size of a deployment archive ZIP file. The endpoint version does not influence the payload of retrieved or deployed metadata.

The endpoint version used by OrgFlow is hard-coded and not configurable. It only affects OrgFlow's source code and internal processing, and has no impact on the metadata payload you care about.

Because the endpoint version and the corresponding metadata API WSDL file rarely change from one version to the next (at least not for the file-based and utility calls that OrgFlow relies on), we don't roll OrgFlow forward to newer endpoint versions very often. Whenever there are significant changes, and we feel that OrgFlow could benefit from them in some way, we will upgrade OrgFlow to use the newer endpoint version, but this will be transparent to you.

Metadata payload API version

The second way the Salesforce metadata API is versioned, is what we call the payload API version. It is independent of both the underlying platform version and the metadata API endpoint version used. The payload API version corresponds to three things:

1. The asOfVersion parameter provided when calling describe() and listMetadata()
2. The apiVersion property of a RetrieveRequest object provided when calling retrieve()
3. The <apiVersion> element in package manifests inside retrieved and deployed metadata archives

This is the most important API version layer to you, because it significantly influences the payload of retrieved and deployed metadata. Specifically, it determines the available metadata types, the structure and format of all metadata, as well as processing rules and semantics when retrieving and deploying. Because metadata flows between environments through Git merge, some care is needed to ensure that the same payload API version is used across all environments in your stack, also when they are on different platform versions.

Therefore, the payload API version used by OrgFlow is configurable in several ways.

Code API version

Though technically unrelated to the metadata API, we should also mention the code API version which is the API version against which a given code-based metadata component is compiled and executed. It is independent of both the underlying platform version, the metadata API endpoint version used and the metadata payload API version.

The code API version is determined by a developer when creating or editing a component, and is reflected in metadata payload through the <apiVersion> element inside the *-meta.xml file of the component. It can be specified for the following metadata types (list is not exhaustive):

• Apex classes
• Apex triggers
• VisualForce pages
• Aura apps and components
• Lightning web components
• Flows

The code API version is relevant in an OrgFlow context because it is reflected the payload of retrieved and deployed metadata and may cause deployment failures if metadata changes are flowed to environments where a particular code API version is not yet supported.

Salesforce preview windows

A new major Salesforce platform version is released to production three times per year:

Month	Release name
February	Spring 'XX
June	Summer 'XX
October	Winter 'XX

The last 4 weeks (approximately) before every major release is known as the preview window. At the start of the preview window, any sandboxes hosted on preview instances are upgraded to a preview of the upcoming release, so that customers can try out the new features and test their solutions and customizations on the upcoming version. This is illustrated in the following diagram:

Diagram courtesy of the Salesforce Sandbox Preview Guide

So how do we know which sandboxes are on preview instances? Well, that depends on when the sandbox was created or last refreshed. Sandboxes created or refreshed during a preview window are provisioned on non-preview instances, while sandboxes created or refreshed outside any preview window are provisioned on preview instances, as illustrated in the following diagram:

Diagram courtesy of the Salesforce Sandbox Preview Guide

Many Salesforce customers find this sandbox refresh behavior somewhat counterintuitive and confusing at first, but you will need to get used to it because there is no way to influence it. It would make Salesforce DevOps a lot easier if customers were allowed to choose when creating or refreshing a sandbox, whether it should be provisioned on a preview or non-preview instance, but sadly this is not possible.

As a result, you will need to plan your sandbox creation in relation to preview windows. Sometimes you may need to create a sandbox before you actually need it, to ensure it's provisioned on the right type of instance. See the topic managing Salesforce version upgrades for guidance and strategies you can use, including timing the creation of sandboxes ahead of time, as well as downgrading sandbox environments back down to non-preview version while retaining their unmerged changes.

Metadata deployment compatibility

During Salesforce preview windows, you may find yourself in the situation where some of the orgs in your stack are on the preview platform version (i.e. sandboxes on preview instances) while others are on the non-preview platform version (i.e. production org, sandboxes on non-preview instances). This introduces some potential compatibility challenges when flowing changes between orgs.

Metadata retrieved from an older platform version can generally be deployed to a newer platform version without any issues. Merging changes from a non-preview environment to a preview environment in OrgFlow is therefore fully supported and generally trouble-free.

Going in the other direction, i.e. retrieving metadata from a newer platform version and deploying it to an older platform version, can range from fully successful in some cases to very problematic in other cases, depending on factors such as:

• The payload API versions being used to retrieve and deploy
• The amount of non-structural changes introduced in the newer version
• Whether the newer code API version was used for any code-based components in the deployment
• The size and scope of the deployment (i.e. how many types and components are being deployed)

OrgFlow tries to maximize the success rate by using a common payload API version supported by all environments in a stack (referred to as the baseline API version) by default. This ensures that any new metadata types, as well as any structure and format changes introduced in the newer version, are kept out of the metadata in your Git repository (and thus also not brought along when merging to other environments) until all environments support the newer version and it becomes the new baseline.

As a safeguard, OrgFlow also prevents merging metadata with a given payload API version into an environment whose org doesn't yet support that payload API version.

However, these default settings can be overridden to instruct OrgFlow to use the newer payload API version (referred to as the latest API version) for some or all environments in your stack, and also to allow merging metadata with the newer payload API version into an environment that doesn't yet support it.

Furthermore, using the baseline payload API version does not insulate your metadata from non-structural changes (such as customizations of new standard objects created by a version upgrade), nor from using the newer code API version in code-based components. See the cross-version bleed-through section below for more information.

Therefore, we recommend that you think twice before planning to merge changes from a preview environment to a non-preview environment in OrgFlow, and exercise caution when you do — even if you have configured both source and target to use the baseline API version.

With that said, remember that deployments are not all-or-nothing in OrgFlow (unless you ask for it). Sometimes, a best-effort merge from a newer to an older platform version is warranted, even if a significant portion of the merged changes fail to deploy to the target org. Perhaps the failed components happen to contain changes you don't deem crucial, or perhaps they can be deployed to the target org later once it has been upgraded to the newer platform version.

API version settings

The API version settings provided by OrgFlow pertain to the metadata payload API version, because this is the only API version layer over which OrgFlow has any influence, and it's also the layer with the most significant impact on the structure and format of the metadata in your Git repository, and hence your ability to flow that metadata between environments.

API version selection mode

OrgFlow can use one of two API version selection modes when connecting to an environment's Salesforce org:

• Baseline mode uses the latest API version supported by both OrgFlow and all environments in the stack
• Latest mode uses the latest API version supported by both OrgFlow and the environment in question

The baseline API version is continuously determined by OrgFlow by querying for the supported API versions of all the Salesforce orgs in your stack, and checking which supported versions they have in common. The baseline version will usually correspond to the current non-preview version. In rare circumstances (such as when your production org is upgraded before all your sandboxes have been upgraded, or when you have no production org in your stack) OrgFlow may determine a preview version as the baseline, but this is usually inconsequential in such cases.

Once an API version has been determined by OrgFlow as the baseline, the baseline can never drop down below that version. This is to prevent the baseline from potentially fluctuating as environments are added and removed from the stack, which could cause the structure and format of the metadata in your Git repository to change back and forth, and ultimately end up causing merge conflicts and deployment problems.

The default API version selection mode is baseline mode. This mode maximizes metadata deployment compatibility between environments in your stack, by providing some insulation of your metadata from disparate platform versions during preview windows.

The API version selection mode for your stack can be configured on the stack settings page under the Salesforce connection section:

The stack setting applies to all environments in the stack by default, but you can also override the API version selection mode for individual environments on the settings tab on the environment page, under the Salesforce connection section:

By default, all environments inherit the API version selection mode from the stack. This is recommended as it makes administration easier to manage API version settings for all environments in a single place. However, there are scenarios where you might like specific environments to use a different API version selection mode than the rest of the stack, such as during Salesforce preview windows.

Allowing unsupported API versions in merge operations

As mentioned earlier, OrgFlow prevents merging metadata with a given payload API version into the Git branch of an environment whose org doesn't yet support that payload API version.

This is a safeguard designed to help protect you from inadvertently merging preview metadata into a non-preview environment's branch, only to realize later that it cannot be deployed to the target Salesforce org. (This safeguard applies only for merge operations initiated from OrgFlow Web or OrgFlow CLI - not for merge operations performed outside of OrgFlow.)

There are legitimate cases where you might want to perform such a merge. If you know what you're doing, you can override the safeguard when starting a flow merge job in OrgFlow Web:

In the OrgFlow CLI you can do the same using the --allowUnsupportedApiVersions option:

$ orgflow env:flowmerge --from=Development1 --into=Production --allowUnsupportedApiVersions

Viewing API versions in use

OrgFlow makes it easier for you to keep track of Salesforce versioning by providing an overview of all your sandboxes on the environments page. For each sandbox you can see which instance it's hosted on, which platform version it's running, and which metadata payload API version OrgFlow will use when retrieving and deploying metadata:

API version support

In OrgFlow

The metadata structure and format for a given metadata payload API version is described by the metadata description, which OrgFlow fetches from the metadata API and uses to drive metadata processing. There are many quirks and omissions in the metadata description, however, so OrgFlow also contains a set of processing rules for every payload API version, which capture those omissions and ensure metadata is processed correctly.

As a safety precaution, regardless of the API version selection mode in effect, OrgFlow will never use an API version than it does not have processing rules for. Instead, it will always select the newest API version supported by both the relevant orgs and its built-in ruleset.

OrgFlow always contains support for the current non-preview version.

OrgFlow normally also contains support for the current preview version. This support may not always be available on the first day of the preview window, but typically no later than the middle of the preview window. Until then, OrgFlow will simply continue to interact with preview sandboxes using the current non-preview payload API version, even for environments using the latest API version selection mode.

OrgFlow normally also contains support for a number of older versions. These are typically never used because no Salesforce orgs exist which require them, however they may be used if you attempt to have OrgFlow process older metadata archives stored in a Git branch or on your local file system. We continuously deprecate these as needed.

OrgFlow currently contains supporting processing rules for the following metadata payload API versions:

Release name	API version	Status
Summer '25	64.0	Current non-preview
Spring '25	63.0	Superceded
Winter '25	62.0	Superceded
Summer '25	61.0	Superceded

As for metadata API endpoint versions, OrgFlow always contains support for the version it uses to connect. However, this is an internal implementation detail that doesn't influence the metadata in your Git repository or anything else you see. As for code API versions used in your code-based metadata components (such as Apex classes and triggers), these are opaque to OrgFlow and require no explicit support.

In Salesforce

Metadata API endpoint versions, metadata payload API versions and code API versions are all subject to the same availability and support lifecycle in Salesforce. The versions available in any given org ranges from the current platform version of the org, all the way back to the oldest supported version.

Salesforce maintains compatibility with older versions for a long time, and then eventually deprecates them in a controlled manner, with plenty of advance warning, when they become so old that it is no longer feasible to support them.

Cross-version "bleed-through"

The settings and mechanisms described in this topic go a long way towards minimizing the impact of API and metadata version differences between environments, but they cannot completely insulate you even if you always use baseline mode for all your environments.

Differences in metadata content from orgs that are on different platform versions sometimes "bleed through" even if OrgFlow uses the same API version when retrieving from them. This is just inherent behavior of the metadata API, and beyond OrgFlow's control.

Let's look at a couple of examples, assuming the current major version in production is Spring '25 (API version 63.0) and we are entering the preview window for Summer '25 (API version 64.0).

One case is when the upgrade itself modifies metadata content, but not necessarily its structure or format. For example, when a sandbox on a preview instance is upgraded to version 64.0, some new standard objects might be created as part of the upgrade. These standard objects will appear in retrieved metadata even if using API version 63.0 when retrieving, because standard objects as a metadata type is supported in both versions, and not something new to the preview. Any customizations you make to these standard objects in a preview environment (for example, adding a custom field) will be retrieved, but will fail to deploy to non-preview environments, because those standard objects don't exist there yet.

Another case is explicitly configured API versions for code-based components, which is completely independent of the API version used to retrieve. For example, if you create an Apex class in a preview environment targeting version 64.0 (in fact, a new Apex class will target the latest available API version by default) then, even if OrgFlow retrieves it using version 63.0, it will still target version 64.0 in its *-meta.xml file and therefore fail to deploy to non-preview environments.

These were just two examples; there are several other cases where modifications caused by upgrading an org to a preview platform version will "bleed through" into non-preview metadata, in ways that will fail to deploy to a non-preview org.

For this reason, some care is needed when you are planning your release timeline. You must consider which environments your changes will flow through, and when to create those environments to ensure they end up the correct instance type with respect to how metadata should flow to and from them. Each environment may need to be on either a preview or a non-preview instance, depending on how downstream merges will align with the beginning and end of any preview windows that happen to overlap with your release cycle.

See the topic managing Salesforce version upgrades for guidance and strategies you can use, including timing the creation of sandboxes ahead of time, as well as downgrading sandbox environments back down to non-preview version while retaining their unmerged changes.