Server-Side Web-Tier Caching

One of the Commerce Cloud application layer components performs web-tier caching of SCAPI requests, which affects GET requests to various API families.

This server-side caching mechanism, is only employed after a request reaches the Commerce Cloud server-side application layer. If there is another caching mechanism in place (for example, on the client side), it is still used independently. This has to be considered when dealing with multiple layers of caching on the front-end or client side of a storefront implementation.

Responses to GET requests of the following APIs are cached:

• /product/shopper-products/v1/organizations/{org-id}/categories/{id}
• /product/shopper-products/v1/organizations/{org-id}/categories

• /product/shopper-products/v1/organizations/{org-id}/products/{id}
• /product/shopper-products/v1/organizations/{org-id}/products

• /search/shopper-search/v1/organizations/{org-id}/product-search

• /search/shopper-search/v1/organizations/{org-id}/search-suggestions

• /pricing/shopper-promotions/v1/organizations/{org-id}/promotions/campaigns

• /pricing/shopper-promotions/v1/organizations/{org-id}/promotions/campaigns

• /site/shopper-seo/v1/organizations/{org-id}/url-mapping

• /configuration/preferences/v1/organizations/{org-id}/site-custom-preferences?{siteId}

• /configuration/preferences/v1/organizations/{org-id}/global-custom-preferences

For customers who enrolled in SCAPI (had their SCAPI zone provisioned with a respective short code) before March 12 2024, this feature can be enabled in Business Manager via Feature Switches. To do that, in Business Manager, navigate to Administration > Feature Switches and enable the SCAPI Server-Side Web-Tier Caching feature toggle.

For customers who enrolled in SCAPI after March 12 2024, this feature switch has no effect and caching is switched on by default.

Apart from that, page caching of dynamic content must be enabled for the specific site.

To do so, in Business Manager, navigate to Administration > Sites > Manage Sites > Site Name - Cache and select “Enable Page Caching”.

How long a cache entry lives and whether the response is personalized, depends on the API, or if there are expansions available on the API and the selected expansions. For instance, if a request is made to the Product API with the “availability” expansion selected, the cache entry is only stored 60 seconds by default.

If the API has expansions, the lowest time-to-live of all the expansions decides how long the cache entry stays alive. If at least one of the requested expansions isn’t marked as “personalized”, the whole response is considered to be non-personalized.

When personalization is enabled for a resource, the following information becomes part of the cache key in addition to the URL string:

• The complete set of active promotions.
• The complete set of active product sorting rules.
• The complete set of applicable price books.
• The complete set of active ABTest Groups.

The cache stores different response variations in the cache and delivers the correct version to the API user based on this additional information.

Let’s think of what it means for two shoppers accessing the same product API (as in, the same URL). In this case, shopper A is eligible for promotion X, and shopper B is eligible for promotion Y. The same product (no change in URL) is cached twice. All shoppers with the promotion X are subsequently served the same respective cache entry, as are the shoppers with the promotion Y. Depending on the number of price books and promotions, this scenario can lead to a large increase in the number of cache entries, regardless of the price of the product.

Script API provides options to control the cache settings programmatically.

The dw.system.Response#setExpires(milliseconds) method of the Script API makes it possible to set an arbitrary cache expiration timestamp. Since the method accepts the timestamp in milliseconds, a sum of the current timestamp and desired “time-to-live” has to be passed as a parameter.

For instance, if a response for the Category API should be only cached for an hour instead of the day, the following custom code can be used:

The cache time-to-live has to be at least one second and cannot exceed 86,400 seconds.

The dw.system.Response#setVaryBy(String varyBy) method of the Script API marks the response as personalized with the given variant identifier. Only price_promotion is supported, and any other value has no effect.

By default, product calls with prices and promotions expansions, as well as product search calls with the prices expansion are personalized.

At the moment there is only one way to invalidate cache manually - which is to invalidate the entire site page cache.

In Business Manager, navigate to Administration > Sites > Manage Sites > Site Name - Cache, and select the Cache tab. In the “Cache Invalidation” section there is a button to invalidate the site page cache. Once the invalidation has been triggered, the entirety of the site page cache is cleared within 15 minutes, including the cache related to SCAPI responses.

With the new server-side caching in place, responses of cached endpoints always return the Cache-Control header value: no-cache, no-store, must-revalidate. This is necessary to ensure a uniform behavior of SCAPI and Script Controller APIs, especially in the case of personalization.