Alan Vo

Available for remote roles

Menu
  1. Home
  2. Blog
  3. Magento
  4. Magento GraphQL staging queries for headless Adobe Commerce teams

Magento

Magento GraphQL staging queries for headless Adobe Commerce teams

Magento

Magento GraphQL staging queries are how I let a headless storefront or PWA show scheduled category prices before shoppers see them. I am Alan Vo, a Gold Coast web developer with 18 years on Magento, Shopify, and WooCommerce catalogues. Adobe documents staging GraphQL on GraphQL staging queries as a narrow pair of read operations: products and categoryList with admin auth plus a campaign timestamp header. This note is for teams who already use Adobe Commerce content staging preview in Admin but still ship React or Hyva frontends that never hit the preview Share link.

Why Magento GraphQL staging queries matter in 2026

Magento GraphQL staging queries matter in 2026 because catalogue delivery is split. Merchandising still lives in Adobe Commerce Admin campaigns, while the customer path may be Hyva, a React SPA, or an edge layer reading core GraphQL or Adobe Commerce Catalog Service. Admin preview tabs emulate Luma-style paths. They do not automatically prove that your custom query stack returns staged price_range or an enabled category tree at 00:01 on launch day.

Adobe Commerce 2.4.8 release notes also mention resolver cache invalidation fixes when staging updates are created or edited: cache should invalidate when an update applies to the entity, not on every draft save. That change matters for headless teams who mix FPC, Varnish, and GraphQL resolver cache. A green Admin preview plus stale GraphQL JSON is still a revenue incident.

Staging GraphQL is Adobe Commerce only, tied to Content Staging campaigns. Magento Open Source does not expose the same scheduled update model. If your licence is Open Source, treat this as a migration planning topic, not a toggle you can enable in composer.json.

How Magento GraphQL staging queries work

Magento GraphQL staging queries work only when you send two headers on otherwise normal products or categoryList operations, and you omit features staging cannot serve.

Adobe lists supported queries as categoryList and products. No other query or any mutation accepts the staging headers. If you attach them to cart or customer, the application returns an error, which protects live checkout from accidental preview scope.

| Header | Purpose | | --- | --- | | Authorization: Bearer <admin_token> | Admin REST token. Adobe's doc references 2FA-backed admin token endpoints such as POST /V1/tfa/provider/google/authenticate. | | Preview-Version: <unix_timestamp> | Seconds since 1970-01-01 UTC, falling inside the scheduled campaign window you want to simulate. |

If the token is invalid or either header is missing, you get an authorization error. If the timestamp is valid but not inside any campaign, results mirror the live storefront, which can look like "staging is broken" when the real issue is a typo in the epoch value or a campaign timezone mismatch.

Magento GraphQL staging queries catalogue work on a large monitor

The products staging query must filter by SKU, attribute, or category-style filters. Adobe states that search is not supported for staging products calls because staged content is not indexed for full-text search. Headless search widgets that rely on products(search: "...") cannot be validated through this path. Test SKU filters or category-driven PLPs instead.

The categoryList staging query returns category metadata and nested products when headers are valid. Adobe's End of Year Sale example shows an empty categoryList array without headers for a disabled staged category, and full product lists with discounted price_range when headers match the campaign window.

GraphQL product types can expose a staged boolean indicating whether an item is tied to a future campaign. That field helps diagnostic tools show which SKUs will flip on schedule without guessing from price alone.

Security posture: staging queries require admin credentials. Never proxy them through a public BFF without strict auth, rate limits, and audit logging. Merchandising previews belong on VPN or SSO-backed internal tools, not on customer routes.

Production checklist for Magento GraphQL staging queries

A headless stack is ready for staging GraphQL when campaigns exist in Admin, tokens rotate safely, and your frontend query shapes match the no-search constraint.

  1. Confirm Adobe Commerce with Content Staging enabled. Open Content > Content Staging > Dashboard and note campaign start/end in the merchant's trading timezone. Convert to UTC for Preview-Version tests.
  1. Mint a dedicated admin integration user for preview tools. Scope roles to staging preview needs. Rotate tokens on the same cadence as other integration users.
  1. Generate a Bearer token using your project's supported admin auth flow (2FA-aware REST as Adobe documents).
  1. Pick a Unix timestamp inside the campaign. I use date -u -d '2026-11-20 14:00:00' +%s on the build agent, then paste the value into Preview-Version.
  1. Run a baseline products(filter: {sku: {eq: "..."}}) query without staging headers. Capture final_price, percent_off, and category visibility.
  1. Repeat with both staging headers. Diff JSON. Discount lines should match the scheduled catalog price rule in Admin preview for the same date.
  1. Run categoryList(filters: {ids: {eq: "<id>"}}) with nested products sorting by price. Confirm total_count and discount fields align with the campaign example in Adobe's doc.
Warehouse shelves standing in for a Magento inventory grid
  1. Verify you did not pass search on staging products. Refactor PLP tests to filter or category nesting.
  1. Test a timestamp outside the campaign window. Response should match step 5 so your tool can detect "no active campaign" vs "wrong SKU".
  1. Confirm no other GraphQL operations in your preview app send staging headers. One stray cart preview call can throw errors in shared Apollo clients.
  1. After 2.4.8 upgrades, watch resolver cache behaviour when editors save staging updates. Run staging GraphQL before and after apply-to-entity, not only on draft saves.
  1. If you route reads through Catalog Service, remember staging GraphQL is core GraphQL. SaaS feeds may not mirror scheduled prices until sync jobs run. Compare core staging headers against Catalog Service PDP reads and document any lag.
  1. Pair results with Magento product schema checks if JSON-LD modules read live GraphQL: structured data might stay on yesterday's offer while preview UI shows tomorrow's sale.
  1. Log preview requests without printing tokens. Store campaign id, timestamp, SKU, and store view in your ticket system.

What breaks when Magento GraphQL staging queries are misused

The first break is treating staging GraphQL like storefront GraphQL. Customer tokens and staging headers do not mix. A BFF that reuses the shopper session and adds Preview-Version will fail or leak admin scope if you shortcut auth.

The second break is search on staging products. Merchandising asks to preview "query hoodies" results. Staging cannot answer that. You need a SKU list from the campaign category or a filtered attribute set.

The third break is timestamp drift. Campaigns use Admin timezone configuration. A Brisbane merchandiser schedules 12:01 AEST while your script sends a UTC epoch for the previous calendar day. GraphQL returns live prices; the team blames the PWA.

The fourth break is disabled categories before go-live. Without headers, categoryList may return [] for a staged category that is off until the campaign starts. A headless route that caches "empty category" responses can poison edge cache unless you bypass cache for preview tools.

The fifth break is catalog price rule versus cart price rule. Staging products reflects catalog rule discounts in Adobe's examples. Cart rules still need checkout preview or separate testing. I have seen correct PDP staging JSON with wrong shipping threshold at payment.

The sixth break is concurrent campaigns on one entity. Adobe allows only one scheduled update per entity at a time in the content staging model. GraphQL preview at a timestamp shows the winning scheduled state, not a merge of two editors' drafts.

Boxed products on a packing bench

How to measure Magento GraphQL staging queries in production

Magento GraphQL staging queries are measured by parity tests and incident counts, not by public analytics.

Track preview parity: for each major campaign, store a JSON diff artifact (live vs staging headers) signed by merchandising. Count mismatches between Admin Share preview and GraphQL JSON as release blockers.

Monitor GraphQL error rates on internal preview endpoints. Spikes in authorization errors often mean expired admin tokens after password policy changes.

Use Action Logs (strengthened in recent Adobe Commerce releases for staging activity) to correlate editor schedules with your preview tool timestamps.

For headless performance, log p95 latency of staging products calls separately from shopper traffic. Admin-token queries should stay on internal networks, not on the same rate limit as public GraphQL.

After campaigns go live, sample live products queries without headers and confirm prices match what staging predicted at the launch timestamp. That closes the loop for revenue reporting.

On retail conversion Magento work, timed catalog campaigns had to match ERP special prices. GraphQL staging queries gave the frontend team a machine-readable check before Fastly warmed PLP HTML. Arteriors catalogue complexity is closer to B2B facets and large SKU sets: we leaned on SKU-filtered staging calls because search-shaped previews are unsupported. Never Never Distillery launches are date-bound; pairing Admin preview with headered GraphQL stopped a headless PDP from showing last season's gift set pricing during a staged window.

FAQ

What are Magento GraphQL staging queries used for?

Magento GraphQL staging queries let authorized integrations read products and categoryList as they will appear during a scheduled Adobe Commerce campaign. Adobe requires an admin Bearer token and a Preview-Version Unix timestamp inside the campaign window. They exist so headless frontends and QA automation can validate staged prices and category visibility without relying only on Admin Share preview links.

Can staging GraphQL use the products search argument?

No. Adobe documents that the staging context does not index staged content for full-text search, so you must omit the search input on staging products queries. Use SKU filters, attribute filters, or nested products under categoryList instead. That limitation is the main reason PLP search previews still need Admin or manual SKU lists.

Watch product still used as a Magento PDP example

Do Magento GraphQL staging queries work on Magento Open Source?

No. Content Staging campaigns and the staging query headers are Adobe Commerce capabilities tied to scheduled updates in Admin. Open Source storefronts do not get the same campaign model. Teams on Open Source should plan licence upgrade or accept that only production GraphQL reflects live data.

How do Magento GraphQL staging queries relate to Catalog Service?

Core GraphQL staging headers hit the Adobe Commerce GraphQL endpoint on your application. Adobe Commerce Catalog Service is a separate SaaS read path fed by product feeds. Scheduled prices may not appear in Catalog Service at the same instant as core staging GraphQL. Validate both paths if your PDP uses SaaS reads for production and core GraphQL only for legacy routes.

Keep reading

Contact if you want this kind of work on a live store.