SKU.md Is Not a Product Feed: Why Live Inventory and Transaction State Stay Out
v1.0.0 features
A responsibility map for product knowledge, commerce feeds, and transaction systems, with rules for keeping changing offers out of static Markdown.
Status: This article reflects the current v1.0.0-beta boundary. It reports a method and its evidence requirements, not unverified adoption, ranking, citation, recommendation, or sales outcomes.
The easiest way to make SKU.md unreliable is to treat it as a slower product feed. A Markdown file can look current while carrying yesterday’s stock, an expired promotion, or a delivery promise that no longer applies. The safer design is to separate product meaning from changing offers and transaction decisions.
Three layers answer three different questions
The knowledge layer answers “what is this product, and under which conditions does it fit?” A feed answers “which commercial fields should another channel ingest?” The transaction system answers “can this shopper buy this variant, at this price, in this market, right now?” Combining the three creates a document that becomes wrong faster than it can be reviewed.
| Layer | Typical contents | Change rate | Authority |
|---|---|---|---|
| Product knowledge | facts, guidance, limitations, compatibility, identifiers, sources | low | merchant-reviewed document |
| Product feed | offer fields, availability snapshots, channel attributes | medium to high | feed pipeline or platform catalog |
| Transaction system | executable price, stock allocation, tax, shipping, payment, order state | real time | commerce backend |
“Reference” data still needs a reason to exist
A value does not become safe merely because it is called a reference price or approximate availability. Readers and agents can still mistake it for a current offer. If a commercial value is useful only when fresh, it belongs behind an endpoint that can answer with its own timestamp, market, currency, and failure semantics.
SKU.md can link to a public product page or live service, but the stable document should explain the handoff. A consumer asking about price or stock should return a live-source requirement rather than recycling static Markdown.
Separation improves failure handling
When a descriptive fact is missing, the consumer can mark it unknown and ask a question. When a feed is delayed, the channel can report staleness. When checkout rejects a purchase, the commerce system can return the current reason. Each layer has a different recovery path; one file cannot represent all three without losing those distinctions.
This separation also makes audits meaningful. A merchant can review whether a limitation is accurate without mixing that review with hourly inventory changes. Operations teams can rotate pricing systems without rewriting product guidance.
A practical authority matrix
For every field, write down the system that is allowed to answer it and the maximum acceptable age. Product dimensions may be stable for a model revision. Compatibility can change when firmware support changes. Inventory may be valid for seconds. Delivery estimates can depend on the buyer’s address. The authority matrix should drive both publication and Agent behavior.
If two systems disagree, the consumer should not silently merge them. It should preserve provenance, prefer the designated authority for that question, and disclose the conflict when it affects a recommendation.
What belongs in SKU.md
Good candidates include materials, dimensions, supported use, explicit exclusions, compatibility requirements, care instructions, model identifiers, and source URLs. A dated Updated value says when the knowledge document changed; it is not an inventory freshness guarantee.
Keep executable price, stock, discounts, shipping estimates, tax, payment availability, checkout state, and order state in live systems. A link is enough when the Agent knows when to follow it.
Review test
Take every statement in the file and ask: “Would a reasonable shopper interpret this as true at the instant of purchase?” If the answer depends on time, market, customer, address, or remaining quantity, move the statement to a live authority. The resulting document will be smaller, more durable, and safer to cite.
The same product exists in three time horizons
Take a rechargeable camping lantern. Its waterproof rating, charging connector, dimensions, and warning against underwater use may remain stable for months. Its channel listing may change price, campaign copy, and regional availability during the week. Its checkout state can change within seconds when stock is reserved, tax is calculated, or a delivery address is entered. Treating those facts as one document gives every consumer the freshness requirement of the fastest-changing field.
Separating the layers creates a cleaner contract. SKU.md carries reviewed product meaning and points to sources. A feed distributes channel-specific offers at the cadence required by that channel. The transaction system confirms the final purchasable state. A consumer can combine the layers, but it should retain the origin and timestamp of each statement rather than flattening them into one apparently current record.
Failure modes created by mixing the layers
The first failure is stale confidence: an agent reads “in stock” from a cached Markdown file after the last unit has been reserved. The second is market ambiguity: a price that is correct in one currency or tax context is repeated as if it were universal. The third is policy drift: a shipping promise survives in a knowledge file after the carrier or cutoff changes. These are not formatting mistakes. They are authority mistakes.
Another failure is operational coupling. If every inventory event requires regenerating, reviewing, deploying, and invalidating a knowledge graph, the knowledge publication becomes noisy and expensive. Conversely, if a slow editorial workflow is allowed to update transaction state, shoppers receive obsolete answers. Different update rates are evidence that the systems need separate ownership.
A practical handoff contract
When a question concerns suitability, compatibility, limitations, identifiers, or stable facts, the agent may answer from SKU.md while citing the relevant source. When it concerns a current offer, inventory, tax, delivery, payment, or order, the answer should call or open the authoritative commerce surface. A mixed question can be split: first determine that the product fits; then confirm that the chosen variant can actually be purchased.
The handoff should carry the resolved product and variant identifiers, the user’s market and quantity when known, and the fact that still needs confirmation. It should not carry an invented price or availability value. This division lets merchants improve product understanding without turning a static document into a fragile transaction cache.
A maintenance test for every field
Before adding a field, ask four questions: who is authoritative, how quickly can it change, what happens if a cached value is wrong, and what interface can confirm it at decision time? A material composition with a reviewed product-page source belongs in knowledge. A stock count whose error can cause a failed order belongs in the inventory service. A manufacturer identifier may be stable, while a marketplace offer using that identifier remains channel-specific.
This test also guides caching. Stable knowledge may use normal web caching with an explicit update date and revision process. Live calls need their own freshness and failure policy. If the commerce service is unavailable, the agent may still explain product suitability, but it must not convert the outage into a guess that the product is available or purchasable.