sfcc-caching

SFCC Caching (Unified Playbook)

Caching in SFCC has multiple layers. The most common failures come from:

• choosing the wrong cache layer
• unsafe population patterns
• invalidation assumptions (multi-node)
• caching the wrong data types (heavy API objects)

Quick Checklist

[ ] Choose cache layer: page cache (HTML) vs custom cache (data) vs service response cache
[ ] Design keys with site + locale scoping where needed
[ ] Use atomic get-or-load patterns (avoid double loaders)
[ ] Cache POJOs/DTOs, not dw.* API objects
[ ] Treat cache values as immutable snapshots; re-put updated copies
[ ] Design around TTL, not cross-node invalidation
[ ] Monitor hit ratios and write failures in Business Manager

Cache Layers (Pick the Right Tool)

Layer	What it caches	When to use
Page cache	Rendered responses / fragments	High-traffic pages where output can be cached
Custom cache (CacheMgr)	Application data	Expensive computations, repeated DB lookups, third-party responses
Service response cache	HTTP responses inside service framework	Repeated calls to stable third-party APIs

Scope: request vs session vs CacheMgr

• request.custom: per-request scratchpad
• session.custom / session.privacy: per-user, per-session data (keep small)
• CacheMgr: app-server local cache shared by users on the same node

Never store user-specific data in a global custom cache.

Custom Cache Mechanics (Non-Negotiable Rules)

1) Define caches in caches.json and register in cartridge package.json

• Cache IDs must be globally unique across the cartridge path.
• The package.json that declares "caches" must live in the cartridge root (cartridges/{{mycartridge}}/package.json), and the caches.json path is relative to that.

2) Use atomic “get-or-load”

Prefer cache.get(key, loader) (single step). Avoid:

• if (!cache.get(key)) cache.put(key, load())

3) Cache POJOs, not API objects

Don’t cache dw.catalog.Product, dw.order.Order, etc. Map to a lightweight object with only the fields you need.