# Magento GraphQL staging queries for headless Adobe Commerce teams

Use products and categoryList with Authorization and Preview-Version headers so PWA and custom frontends preview scheduled campaigns before go-live.

- Date: 2026-11-14
- Category: Magento

## Table of contents

- Why Magento GraphQL staging queries matter in 2026
- How Magento GraphQL staging queries work
- Production checklist for Magento GraphQL staging queries
- What breaks when Magento GraphQL staging queries are misused
- How to measure Magento GraphQL staging queries in production
- Related work on this site
- FAQ
  - What are Magento GraphQL staging queries used for?
  - Can staging GraphQL use the products search argument?
  - Do Magento GraphQL staging queries work on Magento Open Source?
  - How do Magento GraphQL staging queries relate to Catalog Service?

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](https://developer.adobe.com/commerce/webapi/graphql/usage/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](https://alanvo.com/blog/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](https://alanvo.com/blog/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](../../images/blog/magento-graphql-staging-queries-1.jpg)

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.

2. 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.

3. Generate a Bearer token using your project's supported admin auth flow (2FA-aware REST as Adobe documents).

4. 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`.

5. Run a baseline **`products(filter: {sku: {eq: "..."}})`** query **without** staging headers. Capture `final_price`, `percent_off`, and category visibility.

6. Repeat with both staging headers. Diff JSON. Discount lines should match the scheduled catalog price rule in Admin preview for the same date.

7. 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](../../images/blog/magento-graphql-staging-queries-2.jpg)

8. Verify you did **not** pass `search` on staging `products`. Refactor PLP tests to `filter` or category nesting.

9. Test a timestamp **outside** the campaign window. Response should match step 5 so your tool can detect "no active campaign" vs "wrong SKU".

10. Confirm no other GraphQL operations in your preview app send staging headers. One stray `cart` preview call can throw errors in shared Apollo clients.

11. 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.

12. 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.

13. Pair results with [Magento product schema](https://alanvo.com/blog/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.

14. 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](../../images/blog/magento-graphql-staging-queries-3.jpg)

## 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.

## Related work on this site

On [retail conversion](https://alanvo.com/work/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](https://alanvo.com/work/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](https://alanvo.com/work/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](../../images/blog/magento-graphql-staging-queries-4.jpg)

### 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](https://alanvo.com/blog/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.



HTML version: https://alanvo.com/blog/magento-graphql-staging-queries/