DEV Community: Mariusz Szatkowski

Syncing a wholesaler's API into WooCommerce without overselling or melting the server

Mariusz Szatkowski — Tue, 07 Jul 2026 09:43:56 +0000

A common WooCommerce brief looks like this: the store does not own its inventory. A distributor does. The shop is a storefront on top of a wholesaler whose catalog, stock levels, and prices change daily, exposed through some REST or XML web service. The job is to make the store reflect the supplier's reality automatically, and to never sell something the supplier cannot ship.

We shipped exactly this for an automotive-parts store recently (client and supplier stay anonymous). Tens of thousands of indexes, a wholesaler REST API, and a hard requirement: no manual catalog work, and no orders for parts that are not actually in stock. Here is what the architecture looks like and the traps worth knowing before you start.

The store is a view, the wholesaler is the source of truth

The first mental shift is that WooCommerce is not the system of record for products. The distributor is. WooCommerce is a cache with a checkout attached. Once you accept that, the design falls out: a sync layer pulls from the supplier and writes into WooCommerce on a schedule, and you treat the WooCommerce product data as derived, not authored.

The integration answers three questions, and you should answer them explicitly before writing code:

What syncs - catalog, attributes, media, stock, price.
Which direction - here it is one-way (supplier to store); orders stay in WooCommerce.
How often - split it. Stock and price are cheap and change constantly, so poll them frequently. Full catalog and media are expensive, so refresh them rarely.

Map fields declaratively, or you will rewrite it every month

The supplier describes a product its way (its own index, EAN, attribute names, HTML description blobs, image URLs). WooCommerce wants its way (product, attributes, variations, media library). The bridge between them is a field map, and the single best decision we made was keeping that map declarative - a data structure, not a pile of if statements. When the wholesaler adds a new attribute, you extend the map; you do not touch the sync logic. EAN and the supplier index become the stable keys that let each cycle find "the same product" again instead of creating duplicates.

Stock protection is the whole point, so make it boring

The expensive failure mode is selling a part the supplier does not have. So the stock rule is deliberately dumb: every cycle, if the supplier says an index is unavailable, the product is hidden or set to out-of-stock in WooCommerce. When availability returns, so does the product. No cleverness, no "probably still has some." The customer literally cannot add an unfulfillable item to the cart, because it is not purchasable when the supplier is dry.

Price is cost plus rules, computed at write time

Wholesaler prices are cost, not what you sell at. Above the pull layer sits margin logic: the supplier's net price comes in, the store's margin rule is applied, and only the result is written to WooCommerce as the product price. The owner steers profitability by editing rules, not by touching thousands of prices by hand. When the supplier's price list moves, the next cycle recomputes and the store stays profitable without anyone noticing.

The part everyone underestimates: not melting the server

Tens of thousands of products times "poll often" is how you take down a shared-hosting WooCommerce site. A few things that mattered:

Do not do it in WP-Cron on page loads. Drive the sync from real scheduled tasks (system cron hitting WP-CLI, or Action Scheduler) so a burst of traffic does not trigger a burst of syncs, and a sync does not block a customer's request.
Batch and paginate. Pull and write in chunks; never load the whole catalog into memory.
Split the cadences. Stock/price on a short interval, full catalog/media on a long one. Most of your cycles should be small and cheap.
Be idempotent. A cycle that dies halfway must be safe to re-run. Keying on EAN/index makes that free.
Watch autoload and wp_postmeta. Large catalogs bloat both; a sync that writes sloppily to postmeta will quietly wreck query performance long before anyone blames the sync.

When this pattern generalizes

The interesting bit is that "wholesaler REST API" is not special. Swap the source for an ERP (Comarch, Dynamics, NetSuite, whatever exposes an API) and the shape is identical: pull, map, protect stock, compute price, schedule sanely, stay idempotent. The data source changes; the discipline does not. That is why we treat wholesaler-feed and ERP integrations as the same class of problem.

Written by WPPoland. We build WooCommerce ERP and wholesale-API integrations for stores that outgrew manual catalog work. Also on GitHub: a read-only WooCommerce MCP server for giving AI agents safe read access to a store.

A read-only MCP server for WooCommerce: what AI agents actually need from a store

Mariusz Szatkowski — Tue, 07 Jul 2026 09:38:47 +0000

Every WooCommerce integration project we take on now ends with the same question from the client: "can the AI just check the store for me?" What were last month's sales, which SKUs are out of stock, has order 48821 shipped. Reasonable questions. The tempting answer is to hand an agent full API access and let it figure things out. That is also how you end up with an LLM editing prices at 2am because it "helpfully" corrected what it thought was a typo.

So we built the boring version instead: woocommerce-mcp, a small Model Context Protocol server that gives Claude (or any MCP client) read access to a live WordPress + WooCommerce store, and nothing else. It is open source (MIT) and this post is about the design decisions, because the interesting part is not the code, it is what we deliberately left out.

Read-only is a feature, not a limitation

The single most important line in the whole project is that there are no write tools. Not "writes behind a confirmation," not "writes gated by a flag." None. The server exposes five tools and all five only read:

Tool	What it answers
`list_products`	search products by name/sku, with price, stock, permalink
`get_product`	full detail for one product
`list_orders`	recent orders, newest first, optional status filter
`sales_report`	totals for a period (week / month / last_month / year)
`search_posts`	published blog posts (public WP REST API, no keys)

The reasoning is blast radius. An agent that can only read cannot oversell inventory, cannot mangle a price, cannot cancel an order because it misread a prompt. When something inevitably goes sideways in the model's reasoning, the worst outcome is a wrong answer, not a wrong database. For a store owner deciding whether to point an AI at their production shop, "it physically cannot change anything" is the sentence that closes the conversation. You can always add a separate, explicitly-scoped write path later, with human confirmation, as its own project. Bundling it into the read tool by default is how you lose trust on day one.

Scope the keys, not just the code

Read-only tools are only half the guarantee. The other half is the credential. WooCommerce REST keys come in Read, Write, and Read/Write. The README is blunt about it: create the key with Read permission only. The server sends it to your own store over HTTPS as query auth. Even if a future bug or a prompt-injected tool call tried to POST, the key itself would be refused by WooCommerce. Two independent layers (no write tools, no write key) both have to fail for anything to change. That is the level of paranoia a production store deserves.

search_posts needs no keys at all - it hits the public WP REST API - so you can demo the thing against any WordPress site before you ever generate a credential.

No plugin, no lock-in

There is nothing to install on the store. The server talks to the REST endpoints WooCommerce already ships. That matters for two reasons: you are not asking a client to add PHP to their production site just to try an AI experiment, and you are not on the hook for a plugin's update treadmill. The MCP server runs wherever the agent runs (locally over stdio, or in a container - there is a Dockerfile), and the store stays untouched.

The stack is deliberately thin

TypeScript, the official @modelcontextprotocol/sdk, zod for tool input schemas, and that is the dependency list. stdio transport, so it drops straight into Claude Desktop, Cursor, or any MCP client config without a hosted endpoint. The whole thing is a few hundred lines. MCP rewards small, single-purpose servers: one that does WooCommerce reads well composes better with other tools than a monolith that tries to own the entire store.

Where this goes next

The read-only server is the safe entry point. In real projects it is usually step one of a bigger picture: syncing that same catalog and stock data the other direction, into an ERP or a wholesaler feed, where the writes are careful, queued, and reconciled. That is a different risk profile and a different piece of software. Keeping the read layer separate and trivially auditable is what makes the rest of the integration safe to reason about.

If you run a WooCommerce store and want to try it, the repo has the two-minute setup:

git clone https://github.com/wppoland/woocommerce-mcp.git
cd woocommerce-mcp && npm install && npm run build

Then point your MCP client at dist/index.js with WP_URL and your Read-only WooCommerce keys.

Code, issues, and the full tool reference: https://github.com/wppoland/woocommerce-mcp. Feedback welcome, especially on which read-only tools you would want next - refunds summary, customer lookup, coupon status are the three we hear most.

Built by the team at WPPoland, where we spend most of our time on the less glamorous half of AI commerce: wiring WooCommerce into ERPs and wholesaler APIs so stock and prices stay honest.