What we kept on Bitrix when going headless: the honest list with reasoning

When a client says "we're going headless," the first question isn't "which framework." It's: what actually stays on Bitrix?

On a 28,000 SKU project, we spent three months making these calls. Some were obvious. Some weren't. Checkout stayed on legacy Bitrix templates. So did auth. So did pricing. The catalog moved to Elasticsearch in week one.

Here's what we did and why. No "modern architecture" marketing.

Why the boundary matters more than the framework

In a headless Bitrix architecture, the backend (Bitrix) and the frontend (Next.js) are deployed independently, communicating only through REST API. The critical architecture decision is not which frontend framework to use — it's exactly which business logic belongs on Bitrix and which moves to the frontend layer.

Most headless Bitrix discussions get stuck on "Next.js vs Nuxt" or "should we even bother." I've seen projects where teams chose the right framework and drew the wrong line through the system. The result was two years of integration hell.

The boundary is the answer to: what does Bitrix own, what does Next.js own, where do they overlap, and how do you minimize that overlap.

Our rule: Bitrix holds data and money. Next.js handles rendering and UX. Elasticsearch handles search and filtering. The reasoning behind this ownership split is in php-earns-money-nextjs-shows-it.

That sounds obvious. The decisions that came from it weren't.

What always stays on Bitrix

Pricing and discounts stay on Bitrix. It stores prices, personal discounts, campaigns, coupons. Moving this to a separate service early means duplicating discount calculation logic that Bitrix already handles correctly. We kept pricing where it was.

The 1C sync layer stays too. Bitrix Exchange is a black box with a good track record — products, stock, prices come in, and you pull them out via REST API. Don't touch this without a compelling reason.

Orders, cart, auth: same answer. This functionality has been tested across thousands of stores. On our project the account section still runs on legacy Bitrix templates. LCP is 2.8 seconds there. It works. Nobody's touched it in a year.

If it makes money or holds money, leave it on Bitrix.

What moves first: catalog and search

On a category page with 28,000 SKUs, Bitrix was running 40 SQL queries. These were live facets — every render recalculated available filters for the current selection. At 50 concurrent users, the server started struggling.

The catalog moved to Elasticsearch in the first two weeks.

Why first? Because this is the part where speed directly affects conversion. Category page LCP: 4.2 seconds before, 1.4 seconds after. Mobile conversion went up 23%.

Facets became Elasticsearch aggregation results. One query instead of 40 SQL. The indexer pulls delta updates every 15 minutes via Bitrix REST API.

Catalog, search, faceted filtering — these are the first candidates to move in any headless Bitrix project.

The gray zone: checkout and account pages

Checkout runs on legacy Bitrix templates. Not Next.js.

We made this call deliberately, not because we ran out of time.

Checkout was converting at 3.8% of visits to orders. It wasn't slow — no heavy queries, just a form. It was already wired to payment providers, SMS confirmation, and 1C. Rewriting it for architectural purity would have meant 2-3 months of work for zero conversion change. We spent those months on the catalog instead.

Before adding something to the headless perimeter: what do users come there for, and how often? If it's rarely, and there's no SEO traffic, leave it on Bitrix.

What the REST API boundary looks like in practice

In a headless Bitrix setup, the REST API is the only channel between the CMS backend and the Next.js frontend. The frontend has no direct database access — every product, price, stock level, and user record must be available via a configured Bitrix REST endpoint. If the endpoint isn't built, the data doesn't exist from the frontend's perspective.

In our project, Next.js touched nothing directly.

At the start we had 12 core endpoints: product list with facets, product card, search, categories, cart (read-only), user, orders, promo banners, navigation, page content, warehouse stock, cross-sells.

We documented every endpoint in a contract before writing frontend code. Saved us several rounds of rework. The specific gotchas we hit with Bitrix REST on this project are in bitrix-rest-api-headless-surprises.

If an endpoint takes 1.8 seconds, that's a backend problem, not a frontend problem. Don't optimize the symptom.

Three decisions I'd make differently

Start with an endpoint audit, not Next.js setup. We lost two weeks because the frontend was ready before the API was.

Add feature flags from day one. We switched between old and new frontend manually via nginx config. Rolling back was painful.

Define the API error format upfront. Bitrix REST returns errors in a non-standard format. We standardized this in month three, when the frontend had already accumulated 40 different ways of handling errors. Forty.

None of these were critical failures. But each one cost time.

What this actually means

Headless Bitrix works. But "works" doesn't mean "moved everything to Next.js." It means "drew the right line through the system."

Bitrix holds money and data. Next.js renders. Elasticsearch searches. Anything that doesn't fit this scheme is a reason to ask a question, not write code.

The boundary matters more than the framework.