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. Whether this functionality is enabled for you, is controlled on the support-side.
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
Currently, the overall enablement of the caching feature has to be done by Salesforce Commerce Cloud Support or Product Management. Please reach out if you are interested.
After it is enabled, 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.
| API name | Expansion | Cache time-to-live, seconds (Defaults) | Is personalized (Defaults) |
|---|---|---|---|
| Categories | N/A | 86400 | No |
| Products | availability | 60 | No |
| bundled_products | 86400 | No | |
| images | 86400 | No | |
| links | 86400 | No | |
| options | 86400 | No | |
| prices | 900 | Yes | |
| promotions | 900 | Yes | |
| recommendations | 86400 | No | |
| set_products | 86400 | No | |
| variations | 86400 | No | |
| none | 86400 | No | |
| Product Search | availability | 60 | No |
| images | 900 | No | |
| prices | 900 | Yes | |
| represented_products | 900 | No | |
| variations | 900 | No | |
| none | 900 | No | |
| Search Suggestions | N/A | 900 | No |
| Promotions | N/A | 3600 | No |
| Campaigns | N/A | 3600 | No |
Due to how short the cache entry live time is for certain expansions, we recommend you make sure only necessary expansions are included in the request. For example, unnecessarily including the “availability” expansion in requests to the Products API reduces the cache hit rate drastically and negatively affect the overall performance of requests.
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.
Doing this also invalidates all existing pipeline cache, possibly resulting in a temporary decrease in performance.
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.