Headless commerce cache and preview QA checklist before launch

Headless commerce usually adds at least three places where content can get out of sync: the commerce platform, the CMS, and the front-end cache. A page can look fast in testing while showing yesterday's price, an old product image, a missing translation, or metadata that never refreshed after a campaign update.

This checklist is for Shopify headless builds, composable commerce sites, Next.js storefronts, CMS-powered product stories, and redesign launches that depend on static generation, edge cache, API cache, or on-demand revalidation. Run it before launch, before a major campaign, and whenever the content model or cache rules change.

Do not start by testing one product page refresh. List every surface that can be cached and every system that can change it. Product detail pages, collection pages, search results, navigation, footer links, recommendations, content blocks, image transforms, SEO metadata, structured data, XML sitemaps, feeds, and localized routes can all have different freshness rules.

The inventory should name the source system, the front-end route, the cache type, the expected update speed, and the owner. Without that map, launch QA turns into random page refreshing.

• Commerce data: title, handle, price, compare-at price, inventory, availability, variants, options, images, collections, tags, metafields, and selling plans.
• CMS data: landing pages, buying guides, editorial modules, banners, FAQs, store settings, translations, navigation, and reusable proof blocks.
• SEO data: title tags, meta descriptions, canonicals, hreflang alternates, schema, Open Graph images, robots rules, and sitemap entries.
• Infrastructure: static generation, edge cache, API cache, image cache, CDN rules, preview cookies, webhook handlers, queues, and manual purge tools.

Not every route needs the same cache behavior. A homepage campaign banner may need to update within one minute. A size guide can wait longer. Product price and availability may need tighter rules than editorial copy. The point is to agree on the business expectation before developers choose cache headers or revalidation intervals.

Create a small rule table with page type, trigger source, expected freshness, fallback behavior, purge method, and launch owner. Use real numbers instead of vague labels. A rule like product price updates within two minutes is easier to test than product pages should be fresh.

• Mark critical revenue pages separately from low-risk evergreen content.
• Set different rules for product, collection, cart-adjacent, campaign, blog, resource, policy, and localized pages.
• Record what should happen when an API is down: serve stale content, hide a module, show fallback data, or block publishing.
• Confirm whether previews bypass cache, use draft data, or only preview CMS content while commerce data stays live.

Preview mode should be tested with content that behaves like real operations, not a perfect sample page. Editors need to preview unpublished pages, scheduled modules, translated copy, long product names, unavailable products, draft SEO fields, and content blocks that reference commerce data.

A useful preview test answers two questions. First, does the editor see the correct draft state? Second, is the preview clearly separate from the live storefront so nobody mistakes draft content for published content?

• Preview a new landing page, an edited product story, a hidden module, a scheduled promotion, and a localized page.
• Check that preview cookies, authentication, draft APIs, and noindex rules do not leak into public pages.
• Test long titles, missing images, empty optional fields, unpublished references, and products that are out of stock.
• Give editors one preview URL pattern and document when it should be regenerated or shared.

Webhooks are where many headless launches become unreliable. A product update may fire from Shopify, a content update may fire from the CMS, and a collection update may require both route-level and listing-page revalidation. If the handler only refreshes the obvious page, related surfaces stay stale.

Build a test sheet where each row changes one field and lists every route that should refresh. Then make the change in the source system and verify the live storefront, rendered HTML, API response, and sitemap where relevant.

• Product tests: price, sale price, inventory, variant title, product image, metafield, SEO title, handle, and collection membership.
• Collection tests: sort order, filter value, collection description, hero image, pagination, and product availability.
• CMS tests: campaign module, homepage block, resource page, navigation item, footer link, reusable testimonial, and localized content.
• Route tests: direct PDP, collection card, search result, recommendation module, sitemap URL, schema output, and Open Graph metadata.

The hardest bugs often appear when updates happen close together. A merchandiser changes price, then inventory, then collection membership. A content editor publishes a campaign while product data is still syncing. A translation is approved after the English page has already revalidated.

Run a few intentional race-condition tests. Publish two related changes within the same minute, update a product used on multiple pages, unpublish a referenced CMS entry, and change a product handle. Watch whether the storefront lands in a consistent state or mixes old and new data.

• Confirm related pages refresh together when the source change affects multiple routes.
• Check whether queues retry failed webhook jobs and whether failures are visible to the team.
• Test manual purge for one URL, a route pattern, product-dependent pages, and the full site.
• Make sure deleted or unpublished content removes links, cards, schema references, and sitemap entries.

A page body can refresh while SEO output stays stale. That is a real launch risk for headless sites because metadata, structured data, sitemaps, image URLs, and canonical tags may be generated in a different part of the application than the visible product or CMS content.

After each important revalidation test, inspect the rendered HTML and API output. Look for the final title tag, meta description, canonical URL, hreflang alternates, product schema, availability, price, Open Graph image, robots directives, and sitemap inclusion.

• Confirm sale price and availability in structured data match the visible page.
• Check that changed handles redirect or canonicalize cleanly instead of producing duplicate URLs.
• Validate localized metadata and hreflang after translation updates.
• Re-crawl a sample URL list after cache clears so you catch stale metadata, not only stale UI.

Do not wait for launch day to decide who can purge cache or roll back a bad publish. Headless commerce needs an operations plan because stale content can affect revenue, SEO, support tickets, and campaign trust.

Before launch, document the manual purge path, rollback path, webhook logs, failed job alerts, uptime checks, error dashboards, and escalation owner. The team should know how to answer a simple question quickly: is the source content wrong, the webhook delayed, or the cache still serving old output?

• Monitor 404s, API errors, revalidation failures, webhook retries, stale inventory reports, and high-value product pages.
• Keep a list of revenue-critical URLs for manual checks during the first 24 hours.
• Assign owners for commerce data, CMS content, front-end deployment, SEO checks, and cache purge access.
• Write a one-page incident routine for stale prices, wrong inventory, broken previews, and failed campaign updates.