Headless Checkout: What It Is and How to Build One
Updated: 2 days ago
A headless checkout is a checkout flow whose user interface is separated from the commerce backend that prices the cart, takes payment and creates the order.
The frontend you build collects the shopper's details and shows the order summary. The backend does the parts that have to be correct every time: tax, shipping rates, discounts, payment authorization and order creation. The two talk over APIs.
That split is the whole point. You get full control over how checkout looks and behaves, without writing your own payment and order logic. The question for most teams isn't whether to go headless at checkout, but how much of the checkout UI they actually want to own.
Quick Answer: A headless checkout decouples the checkout screens from the commerce engine behind them. You either build the checkout UI yourself on top of checkout APIs, or send shoppers to a hosted checkout page and bring them back to your frontend when payment is done. Hosted is faster and keeps most payment compliance off your plate; fully custom gives you pixel-level control at a higher build and compliance cost.
How does a headless checkout work?
A headless checkout works as a sequence of API calls between your frontend and a commerce backend. The frontend owns presentation; the backend owns state and money.
A typical flow has five stages:
The shopper builds a cart on your custom storefront, and the frontend stores it through a cart API.
At checkout, the frontend asks the backend to create a checkout object from that cart.
The backend calculates totals, taxes, shipping options and discounts and returns them.
Payment is collected, either in fields embedded in your UI or on a hosted payment page.
The backend creates the order and the shopper lands on a confirmation page you control.
If you want a concrete example of that endpoint surface, Wix Headless exposes cart, checkout and redirect APIs under one authentication model. The same pattern shows up in every serious headless commerce stack, and it sits inside the broader headless commerce architecture that separates storefront, services and data.
The nuance: "Headless" describes where the UI lives, not who handles the card. A checkout can be fully headless on the storefront side and still hand the actual card entry to a hosted page. Treating those as one decision is the most common reason checkout projects balloon in scope.
Hosted checkout vs. custom checkout UI
Hosted and custom are the two real options for a headless checkout, and the choice drives cost, compliance and timeline more than any framework decision.
A hosted checkout redirects the shopper from your frontend to a checkout page the commerce platform runs, then returns them to a URL you specify. You keep your custom storefront, product pages and cart. The platform keeps the payment form, fraud checks and order creation.
A custom checkout UI keeps the shopper on your domain for every step. You build the address forms, shipping selector, order summary and confirmation screens yourself, and you embed payment fields from a payment provider so raw card data still avoids your servers.
Itay Shmool, who runs payments at Wix, describes why the hosted path holds up in production:
"I am the chairman of payments at Wix. If a checkout goes down on a Saturday night, my team gets the alert, not the agency. People ask me whether the headless setup is the same infrastructure or some lighter version, and the answer is yes, it's the same thing. Same rails, same monitoring. We didn't build a separate system for headless, there was no reason to. Honestly, agencies shouldn't need to think about any of this. That's kind of the point."
On Wix, the hosted path is a redirect session. Your frontend calls the Redirects API with the checkout ID and a post-flow URL, gets back a single-use URL, and sends the shopper there. When payment finishes, Wix returns them to your site. If you'd rather start from a working backend than wire this up from scratch, a managed backend like Wix Headless already has the cart, checkout and payment layers in place.
Headless checkout options compared
The table below compares the two approaches on the factors that usually decide the project.
Factor | Hosted checkout (redirect) | Custom checkout UI |
Build effort | Low: one redirect call plus a return page | High: every form, state and error screen |
Design control | Storefront and cart only | Every checkout step |
Card data handling | Platform-hosted payment page | Embedded provider fields in your UI |
Compliance burden | Mostly carried by the platform | Larger share falls on your team |
Domain experience | Brief move to the checkout domain unless you map a custom domain | Shopper stays on your domain |
Best fit | Fast launches, small teams, agencies | Brands with checkout-specific UX requirements |
How to build a headless checkout step by step
Building a headless checkout follows the same order regardless of stack. Get the data flow right first and the UI decisions get easier.
Model the cart through the API. Store line items server-side from the first add-to-cart, not in local state you later have to reconcile.
Create the checkout from the cart. On Wix, createCheckoutFromCurrentCart() turns the visitor's cart into a checkout object with calculated totals.
Choose hosted or custom. Decide this before designing screens, using the table above.
Authorize your return domain. For a hosted flow, Wix only returns shoppers to URLs under an allowed redirect domain you configure in advance.
Create the redirect session. Call createRedirectSession() with the checkout ID and a postFlowUrl, then send the shopper to the returned fullUrl.
Build the confirmation step. Handle the return to your site, read the query parameters Wix passes back, and show an order confirmation that matches your storefront.
Test the failure paths. Declined cards, abandoned payments, expired sessions and out-of-stock items at the last second all need a defined screen.
Here's the subtlety: in a self-managed headless project, the Wix-hosted checkout lives on a separate Wix pages domain by default. Connecting a custom domain, such as a checkout subdomain of your store, removes the visible domain switch, but it requires a Premium plan. In Wix-managed headless projects, visitors stay on the same domain for the storefront and the hosted pages.
When a custom headless checkout is worth the cost
A custom headless checkout is worth building when the checkout itself is part of the product experience. Subscription configurators, multi-step B2B quotes and checkouts that embed loyalty or gifting logic are common examples.
Most stores don't meet that bar. A well-designed storefront and cart do most of the conversion work, and a hosted checkout handles payment edge cases that took platforms years to get right. If you're still choosing the frontend layer, our guide to picking a headless ecommerce framework covers how that decision interacts with checkout.
Teams that start hosted and later need more control can move incrementally. Keep the hosted payment step and customize the screens around it, such as cart review and shipping selection, before taking on payment fields.
Frequently asked questions about headless checkout
What is a headless checkout in ecommerce?
A headless checkout is an ecommerce checkout where the frontend screens are built separately from the backend that handles pricing, payment and orders. The two connect through APIs, so you can redesign checkout without touching payment logic.
What is PCI DSS and how does it affect a headless checkout?
PCI DSS is the Payment Card Industry Data Security Standard, the security baseline card brands require from any business that stores, processes or transmits cardholder data. A hosted headless checkout keeps card entry on the platform's page, which keeps most of that scope off your frontend. A custom checkout UI should still use embedded payment-provider fields so card numbers never touch your servers.
Can I use a hosted checkout with a custom frontend?
Yes. A hosted checkout with a custom frontend is the most common headless commerce setup. You build the storefront and cart, redirect the shopper to the hosted checkout for payment, and receive them back on a confirmation page you control.
What is a redirect session in a headless checkout?
A redirect session is a single-use URL that sends a shopper from your frontend to a platform-hosted page, such as checkout, and returns them to a URL you specify when the flow ends. On Wix, you create one with createRedirectSession() by passing the checkout ID and a post-flow URL.
How much does a headless checkout cost to run?
Headless checkout cost depends on the platform's pricing model rather than the checkout pattern. Some platforms charge developer or API fees on top of commerce plans. Wix Headless is free to connect and uses standard Wix plans, with a Premium plan required to accept payments.
A hosted headless checkout is the right default for most stores
A hosted headless checkout gives you a fully custom storefront while leaving payment, fraud and order logic to infrastructure that's already proven in production. Build a custom checkout UI only when checkout itself is a product differentiator, and even then, keep card entry in embedded provider fields.
For a commerce backend with cart, checkout and hosted payment already in place, try Wix Headless and connect your frontend to it.
Comments