How a JSON cache request is served

One progressive archive URL can pass through several layers. Understanding their order helps you interpret headers, diagnose misses, and avoid configuring two layers with conflicting assumptions.

The request POM Cache recognizes

POM Theme normally creates a clean URL in this form:

https://example.com/pom-json/archive/product/<context-hash>/page-2-ppp-12.json

Translated sites can place one locale prefix before pom-json, for example:

https://example.com/es/pom-json/archive/product/<context-hash>/page-2-ppp-12.json

The REST-shaped progressive route is also recognized:

/wp-json/pom/v1/progressive-archive/archive/...

For static reuse, the request must resolve to a safe .json path and must not carry a query string. GET is supported throughout the normal lifecycle; PHP and the theme router also understand HEAD, while the generated direct-Apache rules are limited to GET.

The complete order

browser or CDN request
        │
        ▼
optional Apache file rule
        │ miss / not installed
        ▼
POM Cache early PHP check
        │ miss / bypass / disabled
        ▼
WordPress + POM Theme router
        │
        ├─ valid stored file through WordPress fallback → response
        │
        └─ no usable file → dynamic generation → optional write → response

The first layer that returns a valid hit ends the request. Later layers do not run.

Layer 1: Apache direct delivery

If the optional rules from POM Cache → Advanced → Progressive JSON Apache rules are installed before the WordPress rules, Apache checks:

• the method is GET;
• the query string is empty;
• no recognized login, password-protection, comment-author, WooCommerce session, or cart cookie is present;
• the matching cache file exists.

When all conditions pass, Apache returns the file as JSON without starting PHP. This is the lowest-origin-overhead path, but it is also outside the WordPress settings runtime. A copied rule remains active until you edit or remove it.

Apache delivery has no PHP-generated X-POM-Cache header. Use server access information, response timing, and the behavior described in Serve JSON cache files directly with Apache to verify it.

Layer 2: PHP early static serving

If Apache does not serve the request, the POM Cache drop-in checks the JSON route before WordPress finishes loading. It requires:

• Progressive JSON cache set to Enabled;
• PHP early static serving set to Enabled;
• a GET or HEAD request with no query string;
• no recognized bypass cookie;
• no DONOTCACHEPAGE instruction;
• a readable, non-empty, valid-size file.

A hit returns:

Content-Type: application/json; charset=UTF-8
Cache-Control: <configured JSON policy>
X-POM-Cache: Served static JSON cache from PHP; phase=early
Vary: Accept-Encoding

For HEAD, PHP sends the headers and content length without the body.

This path can work even when static HTML Caching is disabled, because the JSON master switch is independent.

Layer 3: WordPress read fallback

When the request reaches the POM Theme router, the router reconstructs the expected archive context from the URL. It checks that the context hash and items-per-page value still match the current configuration and that the response is eligible for caching.

With WordPress read fallback enabled, POM Cache reads the stored file, validates its size and JSON syntax, and hands it back to the router. The response can then report:

X-POM-Progressive-Archive-Cache: hit

This avoids the archive query and template rendering but not the WordPress bootstrap. It is a valuable compatibility path when early serving is unavailable.

Layer 4: dynamic generation and write

On a miss, POM Theme builds the response. Its diagnostic header distinguishes:

X-POM-Progressive-Archive-Cache: generated-cacheable
X-POM-Progressive-Archive-Cache: generated-dynamic

generated-cacheable means the route was eligible. POM Cache writes it only if the master switch and JSON writes are enabled and the response passes path, size, JSON, permission, and integration checks.

generated-dynamic means the theme intentionally considered that response unsuitable for shared storage. Repeating it should not be expected to produce a hit.

Why a stored file may still be bypassed

An existing file does not guarantee static delivery. POM Cache deliberately falls through when:

• the request has a query string;
• a recognized private-session cookie is present;
• the file is empty, unreadable, invalid JSON, or too large;
• the URL context no longer matches current archive settings;
• the relevant delivery switch is disabled;
• a supported integration marks the request or response non-cacheable.

Falling through is safer than returning a questionable shared response. WordPress can then produce the correct dynamic result.

Verify each layer independently

1. Clear only the progressive JSON cache.
2. Request one clean archive batch as a logged-out visitor.
3. Confirm a dynamic, cacheable response and a new file count.
4. Repeat the identical URL and check for the expected PHP or theme hit header.
5. If Apache rules are installed, temporarily verify the route at the Apache layer using the method in the Apache guide.
6. Repeat with an authenticated session and confirm it does not use the early shared path.
7. Add a harmless query parameter and confirm the request falls back to dynamic handling rather than a static file.

The next guide, How JSON cache entries are generated, explains the miss-to-write portion in detail.