"Headless" gets thrown around as if decoupling your storefront from your commerce backend is always the right move. It isn't. But when it is the right move — a bespoke mobile app, a content-led site where the CMS drives the experience, an in-store kiosk, or a storefront with interaction patterns no template can express — you need a backend that treats its API as a first-class product rather than an afterthought bolted on to a monolith. Dirora is built that way: the same operations that power the admin dashboard and the default storefront are exposed over a clean REST API, so you can compose commerce into whatever surface you're building.
This guide is written for the engineer weighing that decision. We'll cover how the API is organised, how authentication and multi-tenancy work, the practical building blocks (catalogue, cart, checkout, webhooks), and — just as importantly — when you should not go headless and should lean on the built-in storefront instead.
What "API-first" actually means here
API-first is an architectural commitment, not a marketing label. It means every capability is designed as an API endpoint first, and the user interfaces are consumers of that same contract. In practice that gives you three properties that matter when you build on top of a platform:
Parity. If the admin can do it, your integration can do it. You're never blocked because a feature "only exists in the UI."
Stability. Because the platform's own front ends depend on the API, breaking changes are expensive for us too — which aligns our incentives with yours.
Composability. You can adopt one piece (say, read-only product data for a marketing site) without rebuilding checkout, and grow into more of the API over time.
Under the bonnet, Dirora runs a high-performance Go backend behind that API, so read-heavy endpoints — product listings, search, collection pages — stay fast under load. If you're curious about how the platform is structured internally, we've written about how we built our microservices architecture and how we handle multi-tenancy.
When headless is worth it — and when it isn't
Going headless buys you total control over the presentation layer. It also hands you responsibilities the built-in storefront handles for free: server-side rendering for SEO, image optimisation, structured data, caching, accessibility, and the long tail of edge cases in cart and checkout. Be honest about the trade.
Headless is usually worth it when: you're shipping a native mobile app; you already run a content platform and want commerce embedded into it; you have design or interaction requirements a theme genuinely can't meet; or you're integrating commerce into an existing product where the storefront is only one surface among many.
Headless is usually the wrong call when: you want a great-looking, fast, SEO-friendly store and you're reaching for headless mainly for "flexibility." Dirora's default storefront already ships server-side rendering, automatic image optimisation and structured data, and the Visual Theme Editor lets you customise it deeply — drag-and-drop layout, live preview, undo/redo history and 41 storefront widgets — without touching the API at all. If you don't need a custom front end, don't build one. You can also mix the two: run the standard storefront for your shop and use the API only for satellite surfaces like an app or a partner integration.
Authentication and multi-tenancy
Authenticated requests use bearer tokens, and every request is scoped to a single tenant so one store's data is isolated from another's. Public, read-only endpoints — product listings, collection pages — are designed to be called without authentication, which is what you want for a storefront that renders catalogue data to anonymous visitors. Write operations and anything customer-specific require a token.
Treat credentials the way you'd treat any secret: keep server-side tokens on the server, never ship privileged keys in client-side bundles, and use the public read endpoints for anything that runs in the browser. If you're building a front end that also needs to write (adding to cart, placing orders), route those calls through your own backend-for-frontend so the sensitive credentials never leave your infrastructure.
The catalogue: products, collections and search
The read side is where most headless projects start. You can fetch products with their variants, images, pricing and inventory state, and page through collections with filtering. Because these endpoints are public and cache-friendly, they're a good fit for statically generated or server-rendered pages that need to be fast and crawlable.
A few practical notes. Multi-currency and multi-language are first-class — if your store sells across markets, request the locale and currency you need rather than converting on the client, so prices and copy stay consistent with what checkout will charge. If you're populating a catalogue to build against, the product CSV importer can pull an existing catalogue in from Shopify, Etsy, Big Cartel, Gumroad or Sellfy, which is a faster way to get realistic data than hand-crafting fixtures. And if search is central to your experience, use the search endpoint rather than fetching everything and filtering in the client.
Cart, checkout and payments
The cart and checkout flow can be driven programmatically: create a cart, add and update line items, apply discounts, and move through to payment for both guest and logged-in customers. Payments run through Stripe, so a headless build inherits the same capabilities as the standard storefront — cards at standard rates with no markup, Apple Pay, Google Pay, and buy-now-pay-later via Klarna and Clearpay, with PayPal also available. Payouts land in two to seven days.
One number worth designing around: Dirora charges no transaction fees on any plan. The only cut is a small platform fee that falls as you grow — 1.5% on the free Starter plan, 0.75% on Pro, 0.25% on Business and 0% on Enterprise. On a headless build where you're already investing engineering time, it's worth checking exactly what a platform skims off each order before you commit; we break the industry norms down in what percentage ecommerce platforms take.
Webhooks: reacting to events in real time
Polling an API to find out whether something happened is wasteful and slow. Webhooks invert it: you subscribe to events — order created, payment completed, low inventory and the like — and Dirora posts to your endpoint when they occur. That's how you keep a warehouse system, CRM, accounting tool or fulfilment provider in sync without a constant stream of requests.
Build your receiver defensively. Verify the payload signature so you only act on genuine events, respond quickly (do the heavy work asynchronously after acknowledging), and make handlers idempotent — networks retry, and you don't want a duplicate delivery to create two shipments. If you'd rather use an existing connector than write your own receiver, the integrations directory and the growing app ecosystem cover many common tools already.
Rate limits, performance and going live
API access is included on every plan with sensible rate limits; high-volume integrations on Enterprise can arrange higher ceilings. Design as if limits exist even when you're nowhere near them: cache catalogue reads, back off and retry on transient errors, and batch where the API allows it. It keeps you well-behaved now and saves a rewrite when traffic grows.
Two more things headless teams routinely underestimate. First, performance is your job once you own the front end — the platform's default storefront is tuned out of the box, but your custom app's Core Web Vitals are on you, so our notes on store performance optimisation apply directly. Second, domains and SSL still need handling: Dirora supports custom domains with automatic SSL, and if you're pointing a headless front end at a subdomain or apex, our custom domains and SSL guide walks through the DNS side.
A pragmatic recommendation
Most stores don't need to be headless, and reaching for it by default trades weeks of engineering for flexibility you may never use. The strongest pattern we see is hybrid: run the standard, SSR storefront for your main shop — fast, crawlable and maintained for you — and use the API for the surfaces that genuinely need it, like a mobile app, a kiosk, or an integration into another product. That way the API earns its keep exactly where custom code adds value, and the platform carries the parts that are the same for everyone. If you're still deciding where to build at all, our honest platform comparison is a good place to weigh it up.
Veelgestelde vragen
Do I need to go headless to build on Dirora's API?
No. The API is available on every plan and you can use it alongside the standard storefront — for a mobile app, an integration, or a data sync — without replacing your front end. Full headless (bringing your own storefront) is one option, not a requirement.
What can the Dirora API actually do?
Because Dirora is API-first, the API mirrors the admin: reading catalogue data (products, variants, collections, search), driving carts and checkout, and subscribing to webhook events for orders, payments and inventory. If a capability exists in the dashboard, it is designed to be reachable over the API.
Will a headless storefront still be good for SEO?
It can be, but SEO becomes your responsibility. Dirora's built-in storefront ships server-side rendering, structured data and image optimisation by default; a custom front end has to implement those itself. If SEO is a priority and you don't have a specific reason to go headless, the standard storefront is usually the safer choice.
Are there transaction fees on API-driven orders?
No. There are no transaction fees on any plan, whether an order is placed through the standard storefront or your own headless front end. The only cut is a small platform fee that falls from 1.5% on the free plan to 0% on Enterprise.
How do I keep external systems in sync with my store?
Use webhooks. Subscribe to events such as order created, payment completed and low inventory, and post them to your warehouse, CRM or accounting tool. Verify the signature, respond fast, and make your handlers idempotent so retried deliveries do not cause duplicate actions.