# Sfcc Caching > Unified caching playbook for SFCC (page cache vs custom cache vs service response cache). Use this when improving performance, reducing external calls, designing cache keys/TTLs, or debugging stale cache behavior. Use when this capability is needed. - Skill: `tomevault-io/sfcc-caching` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/sfcc-caching` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/sfcc-caching/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/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 ```text [ ] 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. ### 4) Treat cached values as immutable Values returned by `cache.get` are immutable copies. Do not mutate them in-place. If you need to update cached data, write a new object back with `cache.put(key, newValue)`. ### 5) TTL over invalidation Per-key invalidation across all nodes is unreliable. Design for a small staleness window using `expireAfterSeconds`. ### 6) Watch size limits and monitoring - Large entries can fail to store without throwing exceptions. - Use Business Manager stats (hit ratio, write failures) to validate effectiveness. ## Service Response Caching (LocalServiceRegistry) If your third-party data is stable for short periods: - Enable response caching on the underlying HTTP client in the service definition - Ensure you understand how to clear it (BM invalidation is typically global) Key warnings: - stale data risk - debugging surprises (you may not hit the network) - cached calls can still affect service stats / circuit breakers ## References - Rhino Inquisitor: Field Guide to Custom Caches - https://www.rhino-inquisitor.com/field-guide-to-custom-caches-in-sfcc/ - Rhino Inquisitor: Third-Party API Caching in Commerce Cloud - https://www.rhino-inquisitor.com/third-party-api-caching-in-commerce-cloud/ - SFCC Docs: Custom Caches - https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-custom-caches.html - SFCC Script API: `dw.system.Cache` (immutable copies + value constraints) - https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_system_Cache.html - SFCC Script API: `dw.system.CacheMgr` (cartridge `package.json` cache registration) - https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_system_CacheMgr.html --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/taurgis) — claim your Tome and manage your conversions.