Bitrix as a Headless API: What It Gives You and What It Does Not

What Bitrix Gives You Out of the Box

When talking about Bitrix as a headless backend, an important distinction comes first: we are not talking about the Bitrix REST API (Marketplace), but about direct access to the core through PHP endpoints. In this mode, Bitrix works well and reliably.

What works without significant customization:

• Iblocks as the catalog data source. CIBlockElement::GetList with the right parameters covers most product, category, and property retrieval scenarios. It needs a clean wrapper — but the underlying system is solid.
• User authentication. The standard session mechanism works, with caveats (more on that below). Registration, login, and password recovery can all be invoked through PHP without rewriting anything.
• Order management. The Bitrix e-commerce module has a mature API for creating and fetching orders, working with the cart, and applying discounts. For most B2B scenarios this is sufficient.
• 1C synchronization. This is one of the main reasons B2B clients choose Bitrix and do not want to replace it. Product, price, stock, and counterparty sync via CommerceML is stable and requires no work on the frontend side.

What Requires Custom PHP Development

This is where the real work begins. Standard Bitrix components are not enough for headless — you need to write your own thin JSON endpoints.

• Multi-property catalog filtering. CIBlockElement::GetList with property filters works, but becomes slow with a large catalog and complex filter combinations. You need a wrapper with caching, and for catalogs of 1,000+ SKUs — move search and filtering to Elasticsearch.
• Search. Bitrix's built-in search is not suitable for serious e-commerce. We write a separate endpoint that proxies queries to ES.
• Complex pricing rules. Individual prices for counterparties, cumulative discounts, and price lists all require a custom PHP layer on top of the standard pricing module.
• Personalized recommendations. Bitrix has no native recommendation engine. Either custom logic ("bought together" based on order history), or an external service.

What Not to Do

Do not try to use the Bitrix REST API (the one in the "Applications" and Marketplace section) for frontend page rendering. This API is designed for CRM, telephony, and external system integrations — it uses a different authorization model (OAuth), a different response structure, and is not intended for high-frequency requests from a user interface.

The right approach is to write your own PHP endpoints that use the Bitrix core directly. They are simple, stable, and do not depend on Marketplace updates.

Real Practice: How We Structure It

On each headless project we write an average of 5–8 thin PHP endpoints. A typical set:

Endpoint	What it does
/api/catalog/list	Product listing with filtering and pagination
/api/catalog/detail	Full product data by slug or ID
/api/search	Proxies the request to Elasticsearch
/api/categories	Category tree with product counts
/api/cart	Cart state (GET), add/remove (POST)
/api/user/profile	Authenticated user data
/api/orders	Counterparty order history

Each endpoint is 60–150 lines of PHP that use the standard Bitrix core and return clean JSON. They have no dependency on templates or components, and Bitrix updates do not break them.

A Common Pitfall: Sessions vs. ISR

Standard Bitrix authentication works through PHP sessions. Next.js with ISR (Incremental Static Regeneration) caches responses on a CDN — the session-based mechanism does not work in this setup: the CDN serves one version of the page to all users.

The solution: separate the public part (catalog, categories, static pages) from the private part (cart, profile, orders). Public pages use ISR without authentication. Private requests use token-based auth: on login, Bitrix generates a JWT token, Next.js stores it in an httpOnly cookie and passes it with every API request.

Verdict: What Works and What Does Not

Bitrix as a headless API covers roughly 80% of typical e-commerce scenarios without major surprises. The remaining 20% is search (use Elasticsearch) and complex recommendations (custom or third-party). 1C synchronization, order management, and pricing are its strengths — there is no good reason to replace them.

Want to understand what the API layer of your Bitrix project would look like? As part of the Catalog Probe, we analyze your Bitrix instance and map out a concrete endpoint structure for your use case.