One catalogue, five readers

A shop is usually built as a website that happens to hold a catalogue. This one was built as a catalogue that happens to have a website, and the difference shows up in places a client rarely thinks to ask about until a partner asks for something the shop cannot give them.

Right now the same WooCommerce data is read by five different consumers. None of them is a theme, and none of them required the catalogue to be duplicated anywhere.

The five readers

The storefront. The obvious one. Pages, product detail, filtering, cart, checkout.

A product feed for Google Shopping. A hundred and fourteen items, which is thirty eight drinks across three caffeine strengths, generated from live data with the attributes Merchant Center requires: identifiers, availability, price, brand, shipping per country, unit pricing, and the grouping that tells Google these three items are variants of one product. A price change on the site is a price change in the feed. Nobody re-uploads a spreadsheet.

A reseller API. A documented interface with a handful of endpoints: who am I, what can I buy at my tier, place an order, list my orders, read one order. That is enough for a partner to run dropshipping against this catalogue without ever opening the shop.

A machine readable catalogue for AI assistants. A plain description of the site and its products in formats that language models read directly, alongside a published interface description. When somebody asks an assistant to compare energy drinks, being legible at that moment is the entire game.

The sitemap and the feeds for search. Generated from the same content rather than maintained separately, which is why one cannot drift from the other.

Five surfaces, one source of truth. That sentence is the architecture.

Why this is only possible if it is decided early

In a themed shop the catalogue and its presentation are the same object. Product data becomes HTML inside a template, and the template is where the knowledge lives: which attribute is the size, which taxonomy is the collection, what the price means when a discount applies.

When a partner then asks for a feed, somebody writes a second piece of code that re-derives all of that from the database, and now there are two places that know what a price means. They agree on the day they are written. They stop agreeing about four months later, usually on a Friday.

Splitting rendering out forces the knowledge to sit below the presentation, where every reader can use it. The tiered pricing on this site is the clearest example: the ladder that makes a case of cans cheaper than a single can is defined once, in WordPress, and published as data. The shop shows it, the cart charges it, the feed reports it and the reseller API quotes it. There is no second implementation to keep in step, because there is no second implementation.

What a reseller API actually needs

The endpoint list is short and misleading. The work is in the rules behind it.

• Identity and authority. A partner is an account, the account carries a discount tier, and every price the API quotes has to be the price that account will actually be charged. If the API and the cart can disagree, you have built a dispute generator.
• Prices that are not public. Wholesale pricing is per partner. The same product endpoint returns different numbers to different callers, and must never return the wrong ones.
• Orders placed by machines. No cart, no session, no browser. An order arrives complete and has to be validated as strictly as a checkout would validate it, including stock, shipping destination and tax.
• Idempotency. A partner’s system will retry. The same order submitted twice because of a timeout must not become two orders.
• Documentation somebody can build against. A published interface description, not a document describing one.

That is a feature with a real cost, and it is one of the things that separates a storefront project from a platform project.

The reader that did not exist three years ago

There is now a category of visitor that is neither a person nor a search crawler: an assistant acting for somebody, asked to find, compare or buy something.

It behaves differently from both. It does not scroll. It reads the document and the structured data, and if the useful facts are only available after a script runs, or the price is behind a contact form, it moves on to a competitor whose numbers it can read.

Preparing for that is not speculative and it is not expensive: publish the catalogue in a machine readable form, keep prices on a public page, describe the interface, and make sure the page makes sense as text. It is a day of work during a build and a retrofit afterwards.

The pattern is the same one search rewarded twenty years ago. The sites that put their information where it could be read won, and the sites that hid it behind presentation did not.

What this generalises to

Wholesale alongside retail. The most common version. One catalogue, two audiences, two price books, one place that decides what a product is.

Marketplace listings. Amazon, eBay, a comparison engine, a regional marketplace. Each is a feed with its own required attributes, and each is a new reader rather than a new project.

Physical retail. A point of sale that needs current stock and current prices, and that writes orders back.

A second brand or a second country. A different storefront over the same catalogue, with its own design and its own language, which is far cheaper than a second shop.

In every one of those, the expensive mistake is the same: building the first surface in a way that assumes it is the only one.

The question worth asking before the build

Not what the website should look like. This one: in three years, what else will need to read this catalogue?

If the honest answer is nothing, a good theme is a perfectly rational choice and this article does not apply to you. If the answer includes a partner, a marketplace, a shop floor, a second market or an assistant, then the decision about where the knowledge lives is being made now whether or not anybody says it out loud.

What an integration actually looks like

Abstract architecture arguments are easy to nod along to and hard to price. Here is the concrete version: a distributor wants to sell these drinks through their own site and have them shipped directly to their customers.

They create an account and are put on a discount tier. They ask the interface who they are and get back their tier and their terms. They ask for the product list and receive the catalogue with their prices, not the public ones, including which items are in stock right now. They import that into their own system.

When one of their customers buys, their system posts an order: the items, the quantities, the delivery address, and a reference of their own so the same order submitted twice during a network timeout does not become two shipments. They get back an order number. They can ask about that order later, and they can list everything they have placed.

That is five endpoints and perhaps a week of the partner’s time. There is no export, no spreadsheet, no nightly synchronisation and no second catalogue drifting out of date. It works because the prices the interface quotes are produced by the same code that prices the cart, and the stock it reports is the same stock the shop reports.

Build the shop first as a website and this is a project. Build it as a catalogue and this is a reader.

The obligation you take on

Publishing an interface is a commitment, and it is worth understanding before the first partner connects.

The moment somebody else’s software depends on the shape of your data, that shape is no longer yours to change casually. Renaming a field breaks their site, not yours, and you will hear about it on a Monday. That is why the interface on this site carries a version in its address: it creates somewhere to put the next shape without removing the current one.

Three rules keep this cheap:

• Add, do not rename. New fields are free. Changed fields are a migration for everybody who reads you.
• Publish a description, not a document. A machine readable specification lets a partner generate their client and test against you without asking questions.
• Decide what is guaranteed. Which fields will always be there, what the rate limits are, how errors are shaped. A partner who knows the rules does not need support.

None of that is expensive at the start. All of it is expensive to introduce once three partners are live.

The smallest version of this idea

Not every business needs a partner interface, and this article is not an argument that they do. It is an argument about where knowledge lives.

Even a shop that will never publish an interface benefits from defining what a product is, what a price means and which attribute is which, in one place, below the presentation. It costs nothing extra during the build. It is what makes the second surface cheap, whatever that surface turns out to be, and in practice there is always a second surface.

This shop is a working demonstration of what a headless WooCommerce build is capable of, and everything described here is running on it. If you are weighing a build of your own, it was made by Pavels Web Solutions.