WooCommerce dual API: GraphQL lands in core (10.9)

Every couple of years a piece of WooCommerce news lands that is, on its face, “yet another API.” I have learned to read those slowly. Most of the time they amount to a new endpoint or two. Now and then they reset how the next decade of integrations will be built. This one falls in the second camp, and I would rather you hear it from someone who has shipped enough custom REST extensions to have opinions.

For years, the honest answer to “how do I get a real GraphQL layer on top of WooCommerce?” was: install WooGraphQL on top of WPGraphQL, accept the maintenance debt, and hope your edge cases hold. That stack has done remarkable work and still does. But it lived next to Woo, not inside it. As of WooCommerce 10.9, that changes — quietly, experimentally, and on terms that any agency building headless storefronts should pay attention to.

I spent the week reading the proposal and the developer docs, then sketching what the migration path looks like for two of our headless clients. Here is what is actually shipping, what it is not, and what I would do about it on Monday.

What is actually new

On June 4, the WooCommerce team published Introducing the WooCommerce dual API, announcing a new “code-first API architecture” that lands in WooCommerce 10.9. Beta 1 dropped on June 8 and the final release is scheduled for June 23, 2026. The piece worth underlining is not the timeline — it is the shape of the thing.

The dual API is three components working together. First, an authoritative code API: plain PHP classes decorated with PHP attributes, where executable classes follow a command pattern and data classes act as DTOs. Second, an autogenerated GraphQL API that mirrors that code API one-for-one — commands become queries and mutations, DTOs become input and output types. Third, a build script that generates the GraphQL schema from the PHP at development time, so the two sides never drift.

The official documentation is blunt about scope and stability: this is “experimental and a proof of concept,” everything under the Automattic\WooCommerce\Api namespace can change in backwards-incompatible ways in any release, and the feature is hidden behind a flag. You enable it with wp option update woocommerce_feature_dual_code_graphql_api_enabled yes. The 10.9 surface area is intentionally small — products and coupons — so you can kick the tires without betting a store on it.

Two more constraints matter. The dual API requires PHP 8.1 or newer, because it leans on attributes, enums, and named arguments. And it is being designed so plugins can do the same trick — define your own code classes, run the build script, and your plugin ships its own GraphQL surface that hooks into the rest of the Woo schema. That extensibility model is the bit that most developers will miss on first read and care most about by quarter four.

For context, this is one of the more durable outputs of Automattic’s Radical Speed Month, the April–May initiative that paired employees into autonomous teams to ship over four hundred experiments. Many of those were toys. This is not.

Why it matters for WordPress and WooCommerce people

Three things change, in order of how soon you will feel them.

Headless storefronts get a first-party answer. Until now, every headless Woo build had to make a choice: lean on the REST API and Store API and pay for the chattiness, or layer WPGraphQL plus WooGraphQL plus a maintenance plan. Both are valid. Neither is owned by the Woo core team. A native GraphQL surface that is generated from the same PHP that runs the store removes a class of “did the third-party schema drift from core?” bugs. It does not eliminate the third-party stack — WPGraphQL is far more mature today — but it gives Automattic skin in the GraphQL game, which is overdue.

Extension authors get a sane new contract. If you maintain a Woo extension, you already know the dance: write business logic, expose it through actions and filters, then write a parallel REST controller, then write parallel docs, then field issues when the two drift. The dual API’s pitch is “write the code class once with attributes, get the API surface for free.” That is the part I want to test in production before celebrating, but the design intent is the right one.

AI agents get a typed, introspectable surface. This is the line item nobody is leading with, but it is real. The Woo team has been steadily building toward agent-friendly commerce — the Abilities API expansion earlier this month, the MCP work before that. A typed GraphQL schema with built-in introspection is exactly what an LLM tool-calling layer wants to consume. Read the two announcements side by side and the strategy reads cleanly: abilities for high-level intent, a typed API for the actual work.

One thing this does not change: your existing REST and Store API code keeps working. The dual API is additive. Nothing is being deprecated in 10.9.

What I would do (or not do) about it

If you are running a production WooCommerce store, do nothing in 10.9. Read the announcement, bookmark the docs, move on. “Experimental, no backward compatibility guarantees, behind a feature flag, PHP 8.1+ only” is the WooCommerce team telling you in three different ways that this is not what you ship on Friday.

If you build or maintain a Woo extension, this is the right moment to spin up a staging site on PHP 8.2, enable the feature flag, and look at how the products and coupons code APIs are decorated. The patterns you learn now are the patterns you will have to support when one of your clients files a ticket asking why your plugin is not in the GraphQL schema. Six months ahead of that conversation is better than two weeks ahead.

If you are planning a new headless storefront in the next two quarters, I would still build it on the Store API plus, if you need it, WPGraphQL and WooGraphQL. Not because the dual API is bad — it is well-designed — but because “proof of concept, products and coupons only” is not a foundation for a launch you want to keep up for three years. Watch what lands in 10.10 and 11.0. If the surface area widens to orders, customers, and subscriptions without major API rewrites, that is when the conversation flips.

And if you are in an enterprise procurement meeting where someone is comparing WooCommerce to a hosted commerce platform on the “do you have a real GraphQL API?” line — you now have a better answer than you did last month. Not a finished one, but a credible roadmap from the core team, not a third-party bet. That changes the meeting.

Two decades into this, the pattern I trust is: WordPress and WooCommerce rarely arrive first, but they arrive with governance, an extension ecosystem, and a contract you can build a business on. The dual API is the early version of that contract for the GraphQL era. Worth tracking. Not yet worth betting on.