SFCC Development MCP Server

---
name: sfcc-caching
description: 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.
---

# 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