Building a Custom Checkout with Headless Setup

• Time — 45 minutes

• Difficulty — Advanced

What You'll Build: A fully custom checkout experience where your team owns the entire UI and user flow, powered by Upmind's headless composables, XState orchestration, and API layer, giving you complete control over layout, interaction, and sequencing without reimplementing pricing, billing, or payment logic.

Prerequisites:

• An active Upmind account with API access.

• An existing frontend application or a defined plan for your UI shell.

• Solid working knowledge of Vue 3 and the Composition API.

• Familiarity with state management concepts (XState knowledge is helpful but not required).

• A read-through of Understanding the Cart Architecture to understand how the headless layer fits into the broader stack.

• A read-through of Using the Decision Guide to confirm that headless is the right approach for your team.

• Access to Upmind API Documentation for reference during integration.

• Sandbox credentials for testing payments and order flows.

A headless checkout is the most flexible way to integrate Upmind’s commerce capabilities into your product. In this model, your team owns the entire user experience while Upmind handles the underlying commerce logic for pricing, subscriptions, promotions, taxes, and payment orchestration.

This approach is powerful by design. It is best suited to teams that need control beyond visual styling or page layout, and who want to embed checkout as a first-class part of their product rather than a separate storefront.

When to choose this approach

You should consider a headless checkout when:

• You already operate an established frontend or application UI that you want to extend, not replace.

• Checkout needs to be deeply embedded into an existing product or onboarding flow.

• Maintaining UX consistency across your app, marketing surfaces, and billing experience is critical.

• Your purchase flow requires custom steps, branching logic, or non-standard sequencing.

• You want to reuse the same commerce logic across web, mobile apps, or internal tools.

Common use cases include SaaS onboarding flows, embedded checkout inside dashboards, enterprise customer portals, and mobile applications.

If speed to launch with minimal engineering is the priority, the ready-made Cart is usually a better fit. Headless is for teams optimizing long-term control, ownership, and extensibility.

Architecture overview

A headless checkout combines Upmind’s logic layer with your own UI, optionally supported by Client Vue as an application shell. This separation allows teams to iterate on experience without touching core commerce behavior.

At a high level:

• Your frontend defines layout, styling, and user interaction.

• Headless Upmind composables manage commerce state and business logic.

• XState orchestrates complex flows in a deterministic way.

• Upmind APIs persist products, pricing, baskets, payments, and orders.

Simplified architecture diagram

The key idea is simple but powerful:

The UI is replaceable, logic is shared, and orchestration is centralized.

This means teams can redesign, refactor, or even rebuild their frontend without re-implementing pricing rules, subscription logic, or payment sequencing. Commerce behavior stays consistent across surfaces, while presentation remains fully flexible.

How Headless, UI, and Client Vue relate

These three layers are often confused, so it’s important to separate their roles clearly.

These layers are often confused, but they serve very different purposes. Headless defines what happens, your UI defines how it feels, and Client Vue optionally provides structure to accelerate development.

Separating these concerns keeps systems maintainable as complexity grows, especially when multiple teams or platforms are involved.

Headless Upmind (Logic layer)

Headless Upmind is a collection of Vue 3 composables that encapsulate commerce behavior and state management. These composables act as the primary interface between your UI and the Upmind platform.

It handles:

• Basket lifecycle management.

• Pricing and discount application.

• Subscription rules and renewals.

• Tax calculation.

• Payment sequencing.

• Error handling and retries.

Your developers do not manually call raw APIs in sequence. Instead, they interact with composables that already understand the correct order of operations.

JavaScript Example: A single user action may trigger multiple coordinated API calls behind the scenes, all executed safely and consistently.

Example
JavaScript
Copy
const { basket, addItem, applyPromo, checkout } = useBasket()

Catalogue → Configure → Basket → Billing → Payment → Confirmation 

XState (Orchestration engine)

XState operates beneath the composables and enforces deterministic flow control. It ensures that checkout behavior progresses through valid, predictable states.

It manages transitions such as:

• Empty > Configuring

• Configuring > Validating

• Validating > Processing Payment

• Processing > Converting

• Converting > Success or Error

This guarantees that invalid actions cannot occur. For example, a payment submission cannot be triggered while configuration or validation is incomplete.

By formalizing flow rules, XState eliminates entire classes of edge cases that typically appear in custom checkout implementations.

Developers benefit from:

• Fewer edge-case bugs caused by race conditions or invalid state.

• Predictable flow behavior across environments.

• Clear extension points for analytics, logging, or custom side effects.

Client Vue (Application shell)

Client Vue is a collection of complex, pre-built UI organisms and layout templates commonly required by cart and checkout experiences. It provides reusable structure and interaction patterns without enforcing pages, routing, or flows. Client Vue is optional, but especially valuable for teams building larger SPAs.

It provides:

• A clear separation where authentication, guards, and flow control are defined by headless flows and implemented in your app.

• Shared layout structure, such as headers, footers, and persistent UI regions.

• Dependency wiring that connects UI components cleanly to headless logic.

Client Vue acts as a starter framework for UI scaffolding, allowing teams to focus on UX and feature development while retaining full ownership of pages, routes, and user flows.

You can choose to:

• Use Client Vue end-to-end as your application shell.

• Adopt only selected organisms or layouts.

• Ignore it entirely and bring your own custom shell.

Upmind UI (Design system)

Upmind UI is a lightweight design system composed of atomic and molecular components that form the foundation for more complex UI organisms. It is designed to balance consistency with flexibility.

Upmind UI is the internal component library used by the Cart and Portal, and reflects established interaction patterns across the Upmind ecosystem. While not required for headless implementations, it can accelerate development and alignment.

It provides:

• Accessible, production-ready components.

• Token-based theming for colors, spacing, and typography.

• Consistent interaction patterns across commerce surfaces.

Advanced teams may choose to adopt it for visual consistency with Upmind. Others may bring a proprietary design system. Both approaches are fully supported, as the headless layer does not depend on Upmind UI.

High-level setup steps

A typical headless implementation follows a clear, phased path that separates application structure, commerce logic, and user experience. This allows teams to move methodically from foundation to launch while keeping responsibilities cleanly divided:

1. Decide your shell: Start by choosing where and how the checkout UI will live. This decision defines how headless commerce integrates into your product.

• If you already have an existing frontend, headless checkout is added directly into your current application, preserving established navigation, branding, and UX patterns.

• If you use the Client Vue starter, you gain a pre-wired application shell with reusable layouts and organisms, accelerating development while still allowing full customization.

• For mobile or embedded apps, the headless layer integrates into native or hybrid environments, enabling shared commerce logic across platforms.

This choice determines your UI ownership but does not affect commerce capabilities.

2. Install Headless Upmind: Once the shell is defined, install the headless logic layer that powers commerce behavior.

• Add the Headless Upmind composables package to your project.

• This Vue.js composables package encapsulates shared logic, state access, and API interactions, making it usable across Client Vue and fully custom components.

• Configure API credentials, select the appropriate environment (sandbox or live), and verify connectivity to Upmind services.

At this stage, no UI is required as the focus is on enabling commerce logic.

3. Define your flow: Next, model the buyer journey your checkout will follow.

• Define how users discover and select products.

• Specify any configuration steps required before purchase.

• Design the basket review and validation experience.

• Determine when and how payment is triggered.

• Define confirmation, success, and error handling behavior.

These steps are mapped to deterministic state transitions rather than ad hoc UI logic.

4. Bind UI to state: With flows defined, connect your UI to headless state and actions.

• Use composables to read data and trigger actions from the UI.

• State transitions are handled internally through composables, abstracting XState machines so applications never interact with them directly.

• Loading, error, and success states are handled in a standardized way, including surfacing API messages and informational notes consistently across the UI.

This ensures predictable behavior across all screens and interactions.

5. Integrate payments: Payments are integrated once the checkout flow is complete.

• Rely on Upmind-managed payment gateways for orchestration, security, and compliance.

• Implement redirects or embedded payment flows as required by your UX and provider configuration.

Payment logic remains consistent regardless of UI implementation.

6. Test edge cases: Before launch, validate behavior beyond the happy path.

• Test failed and interrupted payment scenarios.

• Validate promotional rules and discount edge cases.

• Confirm tax recalculations when regions or inputs change.

• Ensure session recovery works correctly after refreshes or interruptions.

This step is critical for production stability.

7. Go live: When ready, transition to production confidently.

• Monitor state transitions and system events during live usage.

• Track conversion events and key checkout metrics.

• Iterate on UI, messaging, or layout without rewriting underlying logic.

Because commerce logic is centralized and shared, teams can evolve UI and UX independently without reworking pricing, billing, subscriptions, or payment behavior. This separation dramatically reduces regression risk and long-term maintenance cost.

Links to deeper documentation

For teams building headless experiences, the following resources provide essential depth and reference material:

• Upmind API Documentation

  Detailed API documentation covering products, pricing, subscriptions, billing, and order management for advanced or custom integrations.