Understand universal price loading

Country-zone prices use one neutral public page for every country. The page contains accessible loading markers instead of customer-specific amounts, then asks the store for the current visitor's resolved prices after the page loads.

This guide is for store owners, product managers, and support teams who need to understand what customers should see and when a shared page cache is safe.

What customers see

  1. A public catalog or product page initially shows a neutral price placeholder.
  2. The store resolves the customer's WooCommerce country and enabled zone on the server.
  3. Prices, sale badges, product-card actions, and variable-product states update together.
  4. A network failure is retried once. If resolution still fails, the page shows Price unavailable without revealing a cached amount.

Products inserted later by a product feed, filter, carousel, infinite scroll, Quick View, or compatible WooCommerce block follow the same process. Cloned cards reuse an already resolved product response instead of requesting the same data repeatedly.

A product page may make one compact request for its complete product form and another for related product cards. This is expected: products are grouped by the exact data surfaces they need, so card-only products do not incur variable-form rendering work.

The country-price stylesheet and resolver are not requested on a page that contains no price marker. They are added automatically in the footer after the first marker is emitted, or when a compatible product archive declares that it can insert regional products later through AJAX. This remains automatic deferred loading: visitors never need to click a price before resolution starts.

Variable products hydrate only the choices WooCommerce made available in the original form. Country pricing can disable an existing choice for the resolved zone, but it does not reintroduce private, hidden, out-of-stock, or otherwise excluded variations.

The hydrated purchase form uses the same available width as the direct server-rendered form. Switching between an anonymous shared page and an authenticated page therefore does not change the add-to-cart control geometry.

With POM Theme, custom feed price, product-button, sale-text, and sale-amount tags participate in this neutral card state. POM Faceted Search obtains WooCommerce price ranges, price-filter matches, and price sorting from the current regional product index. A shared page does not serialize those regional facet values: the browser obtains them through a private Faceted Search refresh.

Accessibility and failure behavior

  • Loading markers announce Loading price or Loading purchase options.
  • A resolved marker stops reporting itself as busy.
  • A failed marker keeps a neutral text state and never restores a numeric page-cache fallback.
  • If JavaScript is blocked, the shared page continues to contain only the loading state.
  • If the stylesheet is blocked, the loading text remains understandable without the visual skeleton.
  • Variable choices and purchase controls do not become usable until the current regional state has been resolved.

The store always recalculates commercial amounts on the server. Browser markup is a presentation result, not an accepted cart price.

POM Composite products use the same rule. Shared HTML contains no parent price, regional fixed amount, component amount, total, or enabled purchase form in attributes, JSON, or inline scripts. The private regional response rebuilds the component form and totals for the resolved zone, and only that resolved form can enable add to cart. Cart and checkout then create a fresh server quote from the saved configuration and current country context.

Pages that do not use catalog hydration

Cart, checkout, My account, WooCommerce session requests, administration, email, feeds, REST operations, mini-cart fragments, and URLs with query parameters do not use catalog markers. Their output remains server-rendered because it can depend on quantities, coupons, taxes, filters, actions, an export market, or an authenticated session.

Shared universal HTML therefore applies to clean, query-free public URLs. Search, price-filter, sorting, action, and other query-driven requests must bypass the shared page cache and render their current regional result. Cache integrations may remove approved tracking-only parameters before this decision, but must not remove functional catalog or WooCommerce parameters.

Regional WooCommerce REST and Store API responses are always sent with private, no-store browser, CDN, and surrogate cache directives. The origin also removes response validators before serving them. A CDN or reverse proxy must preserve these directives and must not create its own cache rule for WooCommerce API paths.

Cart and checkout resolve the customer's current country again before calculating totals. See Buy with country-zone prices for country changes, unavailable products, mini-cart behavior, and order history.

Cacheable product structured data continues to use WooCommerce's canonical base price and the store currency. It is not changed by visitor IP in the browser.

Generic feeds also use the canonical base price. A market-specific XML or catalog exporter must request its explicit country-zone context on the server; it is never localized from a visitor IP or hydrated by JavaScript.

Check whether shared caching is ready

  1. Go to Tools → Site Health → Status.
  2. Find Country pricing universal cache safety.
  3. POM Cache automatically stores the shared HTML when the result is good.
  4. If the result recommends a bypass, POM Cache keeps product and catalog pages outside the shared cache until every listed active integration has its own neutral presentation.

The safety check remains conservative when it observes an unsupported product type, a conflicting country-pricing engine, WooCommerce cache-compatible geolocation, a proxy chain that fails configured strict validation, a missing country-price product index, an outdated POM Theme integration contract, a pricing integration whose public data has not yet been neutralized, or an explicit operator cache bypass.

Default compatibility proxy handling does not by itself make universal HTML unsafe: the shared document contains no country-specific amount and the regional response remains private and non-cacheable. Site Health still reports the compatibility security trade-off as a recommendation because an unauthenticated forwarding header can select a different country zone. Configure trusted proxies when the deployment requires that country signal to be authenticated.

A migrated store also uses automatic safety checks. Migration, subsequent zone edits, and the commercial observation record do not block universal HTML by themselves. While the legacy country-pricing plugin is active, the conflict check prevents shared caching; after the legacy plugin is disabled, POM Cache can begin storing neutral HTML as soon as every live safety check passes.

Selecting Geolocate (with page caching support) in WooCommerce adds the woocommerce_cache_geolocation blocker and therefore disables shared HTML storage. Select Geolocate to use universal HTML. This is independent from POM Cache's manual emergency bypass.

Automatic caching and emergency bypass

  1. Review the proxy recommendation and either accept zero-configuration compatibility mode for the store's risk profile or configure strict trusted-proxy mode.

  2. Confirm Country pricing universal cache safety is good and inspect the current mode:

    wp pomtweaks country-zone-pricing rollout --url=https://example.test

  3. When cache_mode=automatic and technical_ready=yes, no activation command is required. Request a clean anonymous product or catalog URL twice, then confirm POM Cache created and reused the neutral HTML file.

  4. Purge the origin and CDN cache after changing the mode or correcting a blocker, then validate one clean product URL from two real regions. Confirm both source documents are neutral and each browser hydrates the correct regional result.

  5. Keep regional resolver, Store API, cart, checkout, and other private WooCommerce responses outside every shared cache.

To return immediately to bypass mode during an incident, run:

wp pomtweaks country-zone-pricing rollout --force-bypass --reason=INCIDENT-REFERENCE --yes --url=https://example.test

After resolving the incident, return to automatic safety checks with:

wp pomtweaks country-zone-pricing rollout --automatic --yes --url=https://example.test

The former --enable-universal action remains a compatibility alias for --automatic. Neither action overrides a failed safety check: POM Cache resumes only when the live result is good.

Verify a storefront

  1. Open the same clean catalog URL from two configured country zones.
  2. Use View source before JavaScript changes the page.
  3. Confirm both sources contain neutral country-price markers and no regional product amount in visible price markup, variation data, attributes, JSON, or inline scripts.
  4. Confirm each browser displays the expected regional price after loading.
  5. Inspect the regional request and a representative Store API product request. Confirm both are marked private and not stored by browser, CDN, or surrogate caches.
  6. Test a regional sale, an unavailable product, and a variable product with both available and unavailable variations. Confirm an available selection enables Add to cart after regional loading, while an unavailable selection remains blocked.
  7. Insert another product card after the page loads and confirm it resolves without reloading the page.
  8. Temporarily block the regional request and confirm the page shows Price unavailable after one retry.
  9. If the page uses POM Faceted Search, compare the price range, filtered result set, and low-to-high order in two zones with intentionally different regional prices. Confirm the Faceted Search response includes private, no-store cache headers.
  10. For a POM Composite product, confirm the shared source contains no purchase form or configuration amount, then verify that the resolved form remains disabled until its first regional quote is valid and that cart totals are recalculated after changing country.

Troubleshooting

A price remains in its loading state

Confirm the country-zone product index and Country pricing universal cache safety Site Health checks are available. Then verify that the browser can reach the store's regional price service and that no CDN rule stores or blocks that response.

A cached amount appears before loading

Purge the page cache immediately and keep WooCommerce product pages bypassed. Review theme, block, analytics, and SEO output for a custom numeric price that does not use WooCommerce's normal price HTML filter.

The sale badge or button is stale

Confirm the card contains a country-price marker and that the active product type appears as supported in Site Health. Custom card templates that do not expose normal WooCommerce price output require a compatible integration before shared caching is safe.

A variation cannot be selected

Wait for the loading state to finish. If the regional response says that the variation is unavailable, select another option. If every option remains disabled, review the product's country-price rows and the product index.

Recover from a media rename
Previous
REST and Store API integration
Next