WooGraphQL: exposing WooCommerce through a GraphQL schema

What the plugin adds to a WPGraphQL server

The plugin exists to put the WooCommerce data model on a GraphQL endpoint. Its own description is to add WooCommerce support and functionality to your WPGraphQL server, and the project site is woographql.com.

The list of what you can do is the best description of the scope. You can query your shop's products and variations with detailed filtering options. You can query customers, orders, coupons and refunds. You can create and delete refunds on orders. You can manage customer sessions using JWTs or WooCommerce Store API Cart-Tokens and use cart and customer queries and mutations. You can manually create orders, automate order creation with the checkout mutation, or delegate a customer's session to the WooCommerce checkout page in your theme. And you can query and update WooCommerce settings through the GraphQL API.

Two annotations on that list are worth pausing on, because they apply to a lot of the surface area. Operations have user restrictions, mentioned against customer, order, coupon and refund queries, and again against the session and cart operations. GraphQL makes it easy to expose an entire data model, and this plugin is a good illustration of why authorisation is the hard part of doing that rather than the schema itself.

The project is a WordPress plugin written in PHP, licensed GPL-3.0, and the repository default branch is develop rather than main. Recent releases are v1.0.1 on 2026-04-01, v1.0.2 on 2026-04-02 and v1.0.3 on 2026-06-30, and the last push was on 2026-06-30, the same day as the newest tag.

Two checkout strategies, and the one the documentation recommends

Headless checkout is where most GraphQL commerce work actually lives, and WooGraphQL offers two approaches with a clear preference between them.

The recommended method to checkout, taking full advantage of WooCommerce's payment gateways for payment process and other checkout-related extensions, is to pass the session back to the WordPress installation and let WooCommerce take over from the traditional checkout page.

The reasoning is straightforward. Payment gateways are the part of a checkout that touches money, and the plugins that implement them hook into WooCommerce's own checkout flow in ways that a custom form cannot easily reproduce. By handing the session back, the gateway code runs exactly as it does in a non headless store.

The alternative is to create a custom checkout form and process payments externally. The documentation links resources for that too, including a post on headless WooCommerce checkout with Gatsby and Stripe.

The trade is that the recommended route gives up the fully custom frontend at the final step, in exchange for payment correctness. For a store with a handful of standard gateways, that is usually the right call. For a store with a bespoke checkout experience, a saved card flow or an unusual subscription, the external route exists but you are on your own for the parts WooCommerce plugins expect to control.

The session is the mechanism that makes either route work, and the documentation covers the whole lifecycle: configuring a GraphQL client for WooCommerce user session management, handling user authentication, handling user session and using cart mutations, using the checkout mutation and order mutations, and using order data.

Why the schema is not as complete as plain WordPress

This is the most interesting section of the readme, because it explains a design constraint instead of apologising for a bug.

WooCommerce's Custom Post Types and most data objects are managed by a data store system. This system allows for flexible data object definitions. While objects like products, orders and coupons are defined as WordPress CPTs by default, they don't have to be. That flexibility also lets WooCommerce store metadata for these CPTs in separate tables, and the data doesn't necessarily have to reside in the same database.

The data store system and its object managers are WooGraphQL's primary contact points. Unlike standard CPTs, which use a WP_Post object for data sourcing and a WPGraphQL\Model\Post object for modeling, WPGraphQL for WooCommerce engages object managers for its data source. Each object type has a unique model with distinct permissions and restrictions.

So the gap is structural. When WooCommerce decides that a piece of data lives in its own table rather than in wp_posts, the generic WordPress custom post type path in WPGraphQL no longer applies, and the plugin has to reach the data through the object manager instead. Every place where a schema feature depends on the WP_Post shape is a place where this plugin has to reimplement it, and any gap in that reimplementation shows up as a missing field or a missing argument.

The project says such a setup has resulted in some disparities between the schema where WPGraphQL for WooCommerce support might be lacking, and that both the author and the WPGraphQL team are actively working to harmonize the plugin with all WPGraphQL and WPGraphQL ACF features. The note is signed by @kidunot89.

For an adopter, the practical consequence is that you should check the schema for the specific field or argument you need rather than assuming parity with the WordPress side of WPGraphQL.

Installing the plugin, and the Composer route for Bedrock and SpinupWP

Installation is straightforward in the manual route, and the Composer route is the one the documentation recommends for unusual setups.

The manual route: install and activate WPGraphQL and WooCommerce. Download the wp-graphql-woocommerce.zip file from the Assets section of the most stable release and activate the plugin in your WordPress directory. Then set your GraphQL client endpoint to your site's GraphQL endpoint, which is typically your-store.domain/graphql.

The Composer route is described as recommended for users with unique installations like WP Bedrock or SpinupWP. There you install WordPress and WooCommerce through Composer, then install both plugins by running:

composer require wp-graphql/wp-graphql wp-graphql/wp-graphql-woocommerce

The endpoint differs in that setup, because the WordPress core files are not in the document root. For typical Bedrock or SpinupWP setups, the default will be your-store.domain/wp/graphql, which is the detail that catches people out when the plugin appears to be installed and the endpoint returns nothing.

Three optional companion plugins extend the API, and the documentation is careful about one incompatibility. WPGraphQL-JWT-Authentication introduces a login mutation that returns a JSON Web Token. WPGraphQL Headless Login introduces a login mutation with OAuth2 client support, and it shouldn't be used with WPGraphQL-JWT-Authentication. And WPGraphQL-CORS is there for enhanced security via HTTP CORS and to utilise some advanced WPGraphQL features.

That last one deserves a note. Headless frontends are usually on a different origin, and the CORS configuration is what decides whether your browser is allowed to talk to the endpoint at all.

The schema is published, so you can read it before you install

One of the more useful things the project publishes is not code but a browsable schema. The readme links a Schema page at woographql.com/schema, alongside Docs, a Playground, and an About page.

This matters given the point about the schema not being at parity with the rest of WPGraphQL. If you are evaluating whether a field you need exists, a published schema is the document to check, and it removes the guesswork that would otherwise mean installing the plugin and introspecting.

The Playground is the other one worth knowing about. It is a hosted environment where you can issue queries against the schema without a WordPress install of your own, which is the fastest way to answer the question of whether the type you need is exposed and what its arguments look like.

Together, schema and playground are the reasonable way to evaluate this plugin. A GraphQL plugin is not something you adopt on trust, because the shape of the schema is the product, and a schema you can read is worth more than any amount of prose about it.

The site also runs a Slack workspace for support, and the project has an OpenCollective page for financial contributors, so there is a community behind it rather than a single maintainer.

What the repository shows about how the plugin is tested

The repository tree is where you can see the engineering setup, and it is more substantial than a typical WordPress plugin.

The entry point is wp-graphql-woocommerce.php, with access-functions.php alongside it, and the bulk of the code under includes. There is a Dockerfile and a docker-compose.yml, a Dockerfile is used with a PHP_VERSION build argument on top of the wordpress image, and the compose file wires up a MySQL 5.7 application database, a MailHog service to capture and display all email sent by WordPress, and a testable_app service built from a woographql/wordpress-dev image with the plugin mounted into the WordPress plugins directory.

The compose file has a second database, testing_db on mariadb:10.6, described as a main application database clone for testing inside the main application service. The XDEBUG_CONFIG environment points at the Docker gateway host so an IDE can attach.

The test stack is Codeception, with codeception.dist.yml at the root and a local directory holding the WordPress core files. The continuous integration workflow is named continous-integration.yml, with a separate lint-code.yml for coding standards and a coveralls badge for coverage status. There is also a phpstan.neon.dist with a phpstan directory, and a phpcs.xml.dist.

So the plugin is developed against a real WordPress in Docker, with PHPStan for static analysis, PHPCS for style, and Codeception for functional tests. That is a meaningful signal for a plugin that has to work against a moving target in WooCommerce, though it says nothing about how quickly the schema gaps get closed.

Where WooGraphQL is the wrong choice

There are situations where this plugin will cost you more than it saves, and the readme points at the largest one itself.

The first is third party extensions. The plugin's own answer to the question of extension support is WooGraphQL Pro, an extension of WPGraphQL for WooCommerce that provides compatibility with a variety of popular WooCommerce extensions. The readme describes that compatibility as empowering you to leverage those extensions within the context of the GraphQL API.

That is a significant boundary. A real WooCommerce store usually runs some extension, whether a subscription plugin, a marketplace add-on, a product customisation plugin or an accounting integration, and the free plugin does not cover them. If your revenue depends on those extensions being visible through your headless frontend, the free version is not the product you need.

The second is the schema gaps themselves. The data store design means some parity is missing, and the project is candid that it is working on harmonizing it. If your frontend needs a field that is not in the published schema, you are either waiting for the project or for WooGraphQL Pro, and you should know which before you commit to a build schedule.

The third is the WordPress dependency itself. This is a WordPress plugin, so it needs WordPress running, and if your goal was to get away from WordPress rather than to headless it, this is the wrong direction.

The fourth is the two plugin requirement. WPGraphQL and WooCommerce both have to be installed, and then a third plugin for authentication and a fourth for CORS in most real deployments. That is a chain of dependencies, and each one is a version to track and a thing to break on a WordPress update.

And the fifth is the operational side of GraphQL on WordPress. A GraphQL endpoint on a WordPress site is reachable by anyone who can reach the site, and the authorisation model here is per operation with user restrictions rather than a single policy. Securing it is your job, and the CORS plugin exists precisely because the default is not right for a headless setup.

Editorial conclusion

Adopt WooGraphQL if you are running WooCommerce and want a headless storefront without hand writing an API layer, and you are willing to work within the plugin's data store model. Skip it if your catalogue depends on many third party WooCommerce extensions, because support for those is a separate paid product. Verify first that the specific product, order and cart operations you need are present in the schema, and read the section on the WooCommerce data store before you assume the standard WordPress custom post type behaviour applies.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. wp-graphql/wp-graphql-woocommerce on GitHub