Key takeaways
- Our store is headless, which means the storefront and the commerce engine are two separate products with two separate sets of records.
- Three systems hold pieces of the truth, and each one will happily answer a question it has no business answering.
- Stock is the sharpest example. The API returns a confident number even for items the platform is not tracking.
- An untracked number never goes down on a sale and never blocks an order, so it looks exactly like real stock and is not.
- Writing down which system owns which question is most of the fix, and it takes an afternoon.
Our review card store runs headless. That is a deliberate technical choice and a good one, but it comes with a bill, and the bill is not performance or cost. It is knowing where the truth lives.
A normal online store is one product. Pages, catalog, cart and orders all sit in the same system, so there is one place to look and one answer to any question you ask it.
Headless splits that apart. The storefront is its own application, written and styled and hosted by us. Behind it, a commerce platform holds the products and runs the checkout. Alongside both, our own database holds the order records and the affiliate credit attached to them.
Three systems. Three sets of records. No single screen that shows all of it.
Each one answers questions it should not
This is the part that catches people, and it caught us. None of these systems refuses a question. Ask any of them anything and you get a clean, confident, well formatted answer.
The commerce backend knows products, prices, variants and checkout. It does not know what the page looks like, and it does not know which affiliate sent the buyer, because that attribution happens in our storefront before the order ever reaches it.
The storefront app knows layout, copy, cart behaviour and tracking. It does not know what is genuinely in stock, and it does not know what an order contained after the fact, because it hands the cart off and stops being involved.
Our order records know what actually sold and who earned commission on it. They do not know the live catalog price, and they cannot tell you whether a product still exists.
Every one of those blind spots returns something rather than nothing when you ask the wrong system. That is the whole problem.
The number that is not stock
The clearest version of this is inventory, and it is worth spelling out because it is the kind of thing that quietly oversells a product.
We asked the commerce API how many of an item we had. It gave us a number. The number was real in the sense that it was stored, and meaningless in the sense that nothing was maintaining it.
Most of our catalog has inventory tracking switched off. When tracking is off, the platform still keeps whatever quantity was typed in at some point, and still returns it. But it never decrements that number when something sells, and it never blocks an order when the number reaches zero.
So you have a figure that looks exactly like stock, sits in the same field as stock, and answers the same question as stock, while being a note somebody left behind. Build a low stock alert on it and it never fires. Put it on the product page and it is wrong the first time anything sells.
There is a second trap on the same screen and it is easy to trigger. The default write mode for a quantity field is adjust by, not set to. Type five hundred and fifty into a field that already holds four hundred and ninety, expecting to correct it, and you now have one thousand and forty. The field looks the same in both modes. Only a small selector says which one you are in.
The other split: which copy is live
The same lesson shows up in a different place. The storefront application has a working version and a published version, and they are not the same thing.
Changes commit to the project immediately. The public site keeps serving the last published build until somebody deploys. Which means you can look at the source, see your fix, and be looking at something no customer can see yet.
The honest check is not reading the code. It is fetching what the live site actually serves and looking for the change in there. Two systems, two answers, and only one of them is what your customers are getting.
What this means if you run a business here
You may never run a headless store. The pattern shows up anywhere you have more than one system, which is almost everybody in San Jose running a business today.
Your booking tool, your CRM, your accounting software and your point of sale all hold a version of your customer list. Ask any one of them how many customers you have and it will give you a number. Those numbers will not match, and none of them is lying. They are answering different questions that happen to sound identical.
The fix is not more software. It is one page, written once, that says which system is the authority for each question. Who owns the customer record. Who owns revenue. Who owns stock. Then everything else is a copy, and a copy that disagrees with the authority is a bug rather than a debate.
It took us an afternoon to write ours and it has settled more arguments than any tool we have bought.
Want this sorted out for you
We build marketing automation in San Jose and across the Bay Area, including the unglamorous work of deciding which of your systems is allowed to answer which question. See what we do at optechsol.llc.