VTEX IO headless: two sources of truth and the real cost

Headless commerce doesn’t fail on the front end. It fails when appearance and content live in two different bases. The storefront is one thing, the content schema is another. Keep them apart and you pay in rework every time a campaign needs a section the design system never planned for.

What actually changes when the store goes headless

VTEX describes headless commerce as using the core commerce features through REST APIs, with a storefront built outside the platform’s own storefront solutions. The same page also states that VTEX doesn’t support headless shopper authentication, so the login page stays native and the interface redirects the shopper to /login.

In short, that is the change. Catalog, price, inventory, promotion and order keep running in the commerce core. What leaves is the layer that rendered the page.

FastStore is the toolkit VTEX maintains for that layer: a Jamstack project with a Core, an SDK, a UI package and an API package. The UI package is where the design system lives, built on FastStore components and styled with Sass.

So the change isn’t that the store becomes code. The change is that page composition stops being a configuration inside the platform and becomes an artifact the team builds, reviews and deploys.

Editorial content isn’t catalog data

Two kinds of data travel through a headless storefront, and they obey different rules.

Catalog data is a fact about the product: name, price, stock, image, variant, category. It has one owner, the commerce core, and it changes through a catalog operation.

Editorial content is a decision about the page: which banner opens the home, the order of the shelves, the text of a landing page, the campaign stamp. It has no owner in the catalog because it doesn’t describe the product.

The VTEX CMS documents content types such as home, pdp, plp and landingPage, with components declared as JSON Schema. A component is a group of fields. A section is a component that acts as a container, and it is the unit editors drag and reorder.

A section can point to a collection, and that is where the confusion starts. The shelf is editorial. The products inside it are catalog. When the campaign team edits the shelf and the catalog team edits the collection, both believe they changed the page.

Mixing the two is the origin of rework. Not the volume of content, the ownership of each field. The NN/g taxonomy separates four models of organization: navigation, the information architecture structure, the taxonomy and the content model. The shelf belongs to the content model, and the filter the same word names belongs to the taxonomy.

Why two sources of truth produce rework

A field only exists for the reader if three things agree: the design system renders it, the content schema declares it, and the runtime maps it.

The VTEX guide on components and sections states that at runtime the storefront maps the hierarchy of content types, sections and components into actual UI components and HTML. That mapping is code.

When the schema lives in one base and the design system lives in another, the mapping is rebuilt by hand on every campaign. The editor sees a field the storefront doesn’t render, or the storefront ships a section no editor can fill.

The content plugin makes the direction explicit. The command generate-schema merges component schemas, content types and the FastStore base schema into one file, and upload-schema sends it to the Schema Registry. The schema is an artifact of the project, versioned with the code.

Keeping both in the same base makes the mapping reviewable, and that matters more than tool preference. NN/g treats content patterns as part of the design system, with the same roles, responsibilities and periodic review as interface components.

What breaks on every campaign

Three failures repeat, and all three come from the split.

The component that exists only in the storefront. Someone builds a hero for a launch directly in the front end, outside the content type. It works on the day. On the next campaign the CMS doesn’t offer it, and the work is repeated.

The field that only marketing uses. A campaign stamp, a badge, a countdown. If the field isn’t in the schema, it lives in a hardcoded value or in a spreadsheet that someone pastes by hand. If it is in the schema but no design token covers it, it renders with the wrong weight.

The promotion the catalog doesn’t know. Price and promotion live in the commerce core, not in the CMS. A page that displays a number typed by an editor creates a second source of truth for price, and the checkout will disagree.

The legacy CMS documentation adds a fourth trap: scopes. A content type with a pdp scope can only be used on product pages. The editor who wants a campaign block on the search page finds the type missing, and the ticket goes to the front-end team.

NN/g lists the same problem from the structure side, on sites that treat each item as an isolated unit and offer no path to what is related.

When the store shouldn’t go headless

Headless is a permanent engineering surface. It is the wrong answer in three common cases.

Small catalog. When a few dozen products cover the offer, the standard storefront already answers search, product page and checkout. A headless project buys a build pipeline to solve a problem the store doesn’t have.

Team without front-end ownership. Headless requires someone who owns the build, the deploy, the dependencies and the performance budget after launch. Without that person, the store keeps the cost and loses the gain.

Operation that changes little. Few campaigns per year and little editorial variation don’t justify a new composition layer. A theme customization solves it with less surface.

There is also a technical boundary to know before deciding. VTEX states that it does not support headless shopper authentication, so the login page stays native. If the brand needs a login screen designed from scratch, the platform doesn’t deliver it today.

What to measure to know the architecture works

Six numbers tell whether the project paid off. All of them come from the store itself, not from the vendor.

Sections declared against sections used. Count the sections and content types in the schema, then the ones that appear in published pages. A section nobody uses is weight in the repository and a wasted choice in the editor’s list.

Time from brief to page live. Measure the same team before and after, on the same kind of campaign. This is the number the project exists to move.

Tickets per campaign that need a developer. If the count stays the same, the project paid the cost and kept the problem.

Pages whose content changed without a deploy. This is the point of a decoupled CMS, and it is binary. Either it happens or the CMS is a formality.

Price conflicts found after a campaign goes live. The expected number is zero. Any occurrence means a second source of truth for price.

Core Web Vitals at the 75th percentile: LCP at or under 2.5 seconds, INP at or under 200 milliseconds, CLS at or under 0.1. FastStore states that it aims for high scores in tests such as Lighthouse and Web Vitals, so the metric is part of the promise.

Where the sources diverge

The NN/g articles don’t describe the same maintenance, and the difference changes the budget.

Content patterns in the design system treats content as part of the system, with annual maintenance. Taxonomy 101 puts the controlled vocabulary in a separate layer, maintained by whoever governs the vocabulary and not by whoever writes the page.

Web Vitals defines approval at the 75th percentile, measured in the field. All three agree that keeping quality up takes a named person who owns it.