Adding WooCommerce stores to a marketplace: what the Store API gives you (and what it doesn't)

WooCommerce powers an enormous share of independent stores, which makes it the catalog you will integrate most often when you build a marketplace on top of existing vendors. The good news: the WooCommerce Store API gives you a clean, read-only seam into products, variants, prices and stock without touching the vendor's admin. The catch: two of the fields you care about most — the true tax treatment of a price and the real shipping cost — are not where a newcomer expects them. This is what the Store API hands you, what it withholds, and how to fill the gaps without asking the vendor to change anything.

What the WooCommerce Store API actually exposes

The Store API is the front-end commerce API — the one a headless storefront uses — so it is designed to be read without authentication for public catalog data. For ingestion, the useful surface is:

• Products and variations. A parent product with its variations (the size/flavor/colour combinations) attached, each with its own SKU, price and stock, so you can reconstruct the variant family rather than treating eighteen combinations as eighteen products.
• Prices. Regular price, sale price, and the currency minor-unit precision, returned as structured fields rather than scraped strings.
• Stock. Availability and, where the store enables it, quantity — the fast-moving field your hourly sync exists to keep fresh.
• Categories and attributes. The vendor's own category tree and product attributes, which you will need to map, not adopt.

That is enough to build a listing. It is not enough to build a correct one, because of what the price field does not tell you on its own.

What the Store API won't hand you

Just as important as the fields it exposes is knowing what it withholds, so you plan around the gaps instead of discovering them in production:

• Cost price and margin. It is a storefront API — it returns what a customer sees, not what the product cost the vendor. If your marketplace economics need cost data, that is a separate conversation with the vendor, not a field you read.
• Per-location inventory. You get an availability signal, not a warehouse-by-warehouse breakdown, which matters if a vendor fulfils from several locations.
• Review and rating data. Not part of the catalog surface; if you want to show a vendor's reviews you source them separately.
• Guaranteed freshness. The API answers when asked; it does not push you changes. That is precisely why ingestion runs on a schedule rather than waiting to be told, a point we labour in product feed ingestion.

The VAT-inclusive vs exclusive trap

Here is the mistake that ships to production quietly: a WooCommerce store configured for a consumer market usually returns tax-inclusive prices — the number already contains VAT. If your marketplace stores prices ex-VAT and adds tax at checkout, ingesting those numbers as-is double-counts nothing on display but silently misprices the product relative to the vendor's own shop, or overcharges at the till. The reverse — a store returning ex-VAT prices that you treat as inclusive — undercharges.

The fix is boring and mandatory: determine each store's tax mode during onboarding and normalise every ingested price to one internal convention before it is listed. This is doubly important because shipping has its own tax treatment — a shipping fee returned by the cart is typically VAT-inclusive even when product prices are handled net. Getting VAT right across products and shipping is enough of a topic on its own that we treat it separately in VAT for online marketplaces.

Category mapping to a shopper-first taxonomy

The Store API gives you the vendor's category tree, and it is tempting to reuse it directly. Resist. Every vendor's tree was built for their shop alone, so five vendors give you five incompatible taxonomies where "recovery", "amino acids" and "sports nutrition > other" all mean the same shelf. Shoppers browsing a marketplace need one coherent tree, not a union of six.

The move is to map each vendor's source categories into a taxonomy you designed for shoppers, and to treat unmapped categories as a launch blocker — an unmapped source category becomes an empty filter chip, which looks broken. How to design that tree, and how AI classification fills it, is its own discipline covered in designing a product taxonomy.

Pulling real shipping rates from the vendor's own checkout

This is the part the product endpoint cannot answer: how much does shipping cost? In WooCommerce, shipping rates are computed by the cart, against a destination, using the vendor's own shipping zones and methods. They are not a property of the product. So if you want to charge a vendor's real fee — and on a multi-vendor cart you must, because you charge shipping per vendor — you read it from the same place the vendor's own shop does.

Routing orders back to the vendor

Reading is half the loop; the order has to get back. On a multi-vendor marketplace a single customer payment fans out into per-vendor sub-orders, each of which needs to reach the vendor who fulfils it, with the right line items, the right shipping choice and a VAT-correct invoice. WooCommerce vendors can receive that as a structured hand-off — the marketplace stays the merchant the customer paid, and the vendor gets a clean instruction to pick, pack and ship their portion. The split-payment, split-fulfilment mechanics are involved enough that we give them their own article: multi-vendor checkout.

Keep the boundary clean: the marketplace owns the customer relationship and the payment; the vendor owns the stock and the parcel. The Store API is how you read the catalog; a structured order hand-off is how you close the loop. Neither requires the vendor to adopt your systems, which is the entire reason WooCommerce vendors say yes to onboarding.

Frequently asked questions