OCAPI Optimistic Locking

OCAPI supports two independent levels of optimistic locking for data consistency. The first level is embedded in the Commerce Cloud Digital data layer itself. The second level is an optional feature of the Open Commerce API.

Digital uses optimistic locking for a wide range of resources in the data layer. This functionality can’t be adjusted or disabled, and it prevents concurrent threads from accidentally overwriting each other's changes (lost update problem).

In the data layer, each concurrent thread operates on the base of a known object state. If one thread changes the object state while another thread simultaneously changes the object state and then attempts to commit the changes within a transaction, an exception occurs.

This exception is exposed by various Commerce Cloud APIs (for example, the Digital Script API and OCAPI). OCAPI specifically exposes this exception as an HTTP 409 (Conflict) ConcurrentModificationException fault.

The easiest way for your client application to react to this fault is to simply retry the OCAPI call, because in most cases the fault is caused by bad timing.

However, a simple retry may not work for more complex cases, especially cases where an operation on one resource implicitly touches another resource. For example:

  • Updates of ProductCategoryAssignments, BundledProducts, Variations, VariationGroups, and ProductSets resources implicitly touch the parent Product resource.
  • Updates of a Profile resource implicitly touch the Customer resource.
  • Updates of ProductListItem, Registrant, and Address resources implicitly touch the ProductList resource.

For such complex cases, you might have to conduct a broader examination of your jobs and storefront/applications, including their customizations (for example, hooks) to find a solution.

Typical scenarios where optimistic locking exceptions occur:

  • Concurrent OCAPI requests
  • Concurrent Script API pipeline/controller requests
  • Concurrent OCAPI and Script API requests
  • Concurrent OCAPI requests, Script API requests, and job executions

The Resource States concept allows optimistic locking via conditional requests in OCAPI. If your client application has to explicitly support concurrent updates of the same resources, you should make use of Resource States. Instead of only a database transaction, this concept covers the whole HTTP request/response flow. Resource states reduce the possibility of ConcurrentModificationExceptions, but can’t completely prevent them.