OCAPI Versioning and Deprecation Policy

This document describes the versioning and deprecation policy for the Open Commerce API (OCAPI). This policy is designed to

  • Be easy for customers and developers to understand
  • Allow Commerce Cloud Digital to make design changes to the API without affecting existing client applications
  • Allow Digital to delete outdated or unsupported features

A new OCAPI version is created whenever Digital:

  • Adds a new document property, resource parameter, or resource.
  • Modifies the type of a document property, resource parameter, or resource.
  • Modifies the name of a document property, resource parameter, or resource.
  • Deletes a document property, resource parameter, or resource.

Whenever Digital creates a new OCAPI version, it also deprecates the former OCAPI version. This encourages customers and developers to:

  • Implement new client applications on top of the current OCAPI version.
  • Upgrade existing applications on a regular basis.

Digital constructs OCAPI version numbers by taking the last two digits of the current year (“24” for 2024), adding a period (.), and adding consecutive numbers, starting with 1. For example, “24.1” is the first version of 2024.

Depending on the context, the version number is specified differently:

  • In URLs, the following syntax is used: v<year>_<consecutive number>. For example: “v24_5”.
  • In documents, the following syntax is used:<year>.<consecutive number>. For example: “24.5”.

Starting with B2C Commerce version 26.2, the platform provides a feature that strictly validates OCAPI version numbers. Any OCAPI request using a version number with leading zeros is now rejected with a 400 Bad Request response and an InvalidVersionException fault. Previously, version numbers containing leading zeros, for example: v024_05 instead of v24_5, were accepted. To enable this feature, contact your B2C Commerce Support representative.

OCAPI is deprecated as of April 2026. Salesforce continues to accept support requests and to provide bug fixes and security updates where applicable. OCAPI doesn’t receive further innovations, consistent with the approach in place for the past 18 months.

Salesforce isn’t establishing an end-of-life (EOL) date to retire OCAPI. This decision is subject to annual review. Salesforce sets any designated EOL date no earlier than two years from the date it formally decides to retire OCAPI.

OCAPI version metadata currently provides a list of version numbers, along with a state enum set to one of the following values: current, deprecated, obsolete