TL;DR: We’ve moved the WooCommerce REST API documentation from its standalone site to our main developer documentation at developer.woocommerce.com/docs. The docs are now smaller, faster, searchable, and optimized for both human developers and AI coding assistants.
Why We Made This Change
If you’ve worked with the WooCommerce REST API, you’ve probably visited our original documentation. It’s served developers well for years, but we ran into a few problems:
The docs were massive. The v3 documentation alone was 4.2 MB—every endpoint, every parameter, every example, all bundled into a single comprehensive page with syntax highlighting, language tabs, and JavaScript interactivity.
The framework was abandoned. Our docs were built on Slate, which is no longer actively maintained. The original repository has been archived, making long-term maintenance a new concern.
AI agents were struggling. Tools like Claude Code, Cursor, and GitHub Copilot increasingly fetch API documentation to help developers write integration code. When an AI agent fetched our docs, it was downloading megabytes of HTML, CSS, and JavaScript just to extract the actual API reference content. That meant slower responses, higher token usage, and potential context window limits—all for features the agent didn’t need.
What’s New
The REST API documentation now lives at developer.woocommerce.com/docs/apis/rest-api/, fully integrated with our main developer documentation.
Individual endpoint files. Instead of one massive page, each endpoint is now its own file. The Products endpoint is separate from Orders, which is separate from Customers. Smaller files mean faster loading and clear context, whether you’re a developer or an AI assistant.
Raw markdown available. All of our developer documentation is available as raw markdown via the Accept: text/markdown headers or by appending .md to the end of the URL. Each page also has a “click to copy” button that adds the markdown to your clipboard.
Searchable. Endpoints now appear in the main documentation search results. We’ll also be tracking whether this makes endpoint documentation more visible in organic search and AI search overviews, which will take more time.
Better navigation. We’ve added a secondary navigation sidebar on each endpoint page, making it easy to jump between Create, Read, Update, and Delete operations.
Part of the contribution workflow. Because the docs now live in the WooCommerce monorepo, pull requests that add or modify API functionality can include documentation updates in the same PR. AI coding agents making changes to WooCommerce can read and update the docs too.
Migration Details
If you have bookmarks to the old documentation site, you should be automatically redirected to the new location. We’ve also added an alert banner on the old site for anyone whose browser doesn’t follow the redirect.
The original repo and docs site will remain open for the immediate future because it includes the legacy REST API documentation.
The documentation content itself remains the same—these are the same manually-written, comprehensive API references you’re used to. We’ve just moved them to a better home.
Leave a Reply