Building a Headless WooCommerce Store Using the REST API and Hippoo Auth

Modern eCommerce development increasingly favors headless architecture: separating the frontend presentation layer from the backend CMS. For WooCommerce users, this means leveraging WordPress and WooCommerce as powerful data providers, while delivering a high-performance frontend with frameworks like React, Vue, or Next.js.

This guide walks you through creating a headless WooCommerce shop, including:

Understanding headless WooCommerce architecture
Using core WooCommerce REST API endpoints
Authenticating users securely with the Hippoo Auth plugin
Fetching authenticated user orders using Hippoo’s extended API
Structuring your frontend for performance and reliability

What Is a Headless WooCommerce Store?

A headless WooCommerce store decouples the frontend UI from the WordPress backend. Instead of rendering pages with PHP themes, the frontend queries data from WooCommerce’s REST API and dynamically renders the experience using a JavaScript framework.

Why go headless?

Better frontend performance with server-side rendering or static generation
Full control over user experience
Easier integration with mobile apps and external systems
Developer freedom with modern tools and workflows

Tools Required

To build a headless WooCommerce setup, you need:

WordPress with WooCommerce installed
Hippoo Auth plugin for user authentication via API
A modern JavaScript framework (React, Next.js, Nuxt, Vue, Svelte)
(Optional) Custom REST API routes or GraphQL for advanced use cases

Core WooCommerce API Endpoints

The WooCommerce REST API is available at:

/wp-json/wc/v3/

Use basic authentication (API key and secret) for server-side operations, or use OAuth/jwt (via plugins like Hippoo Auth) for user-level access.

Fetching Products

GET /wp-json/wc/v3/products

Optional query parameters:

search: filter by name
category: filter by category ID
per_page, page: pagination

Example:

fetch('https://example.com/wp-json/wc/v3/products?per_page=20')

Creating an Order (Guest or Authenticated)

POST /wp-json/wc/v3/orders

Payload:

{
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "12345678"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "123 Street",
    "city": "New York"
  },
  "line_items": [
    { "product_id": 95, "quantity": 1 }
  ],
  "payment_method": "cod",
  "set_paid": false
}

For guest checkouts, you can use this endpoint directly. For logged-in users, authenticated requests will associate the order with their account.

Authenticating Users with Hippoo Auth

WordPress does not provide a secure, frontend-ready login system via the REST API by default. The Hippoo Auth plugin enables token-based authentication with secure login and session handling.

Login Endpoint

POST /wp-json/hippoo-auth/v1/login

Request payload:

{
  "username": "[email protected]",
  "password": "your_password"
}

Successful response:

{
  "success": true,
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user_id": 23,
  "user_email": "[email protected]",
  "user_display_name": "John Doe"
}

Store this token on the frontend (e.g., in memory, localStorage, or a secure cookie) and use it to authenticate further requests.

Fetching Customer Orders with Hippoo Auth

The WooCommerce REST API requires elevated privileges to access order data, even for logged-in users. Hippoo Auth solves this by providing a secure endpoint for users to view their orders.

Endpoint to Get Orders for the Authenticated User

GET /wp-json/hippoo-auth/v1/my-orders
Authorization: Bearer YOUR_TOKEN_HERE

This returns only the orders related to the authenticated customer account.

Example using fetch:

const res = await fetch('https://example.com/wp-json/hippoo-auth/v1/my-orders', {
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  }
});

const orders = await res.json();

Note: Do not use the default WooCommerce /orders?customer=ID for public clients. Hippoo Auth wraps access control to ensure the user only sees their data securely.

Handling the Cart in a Headless Setup

WooCommerce does not expose a cart API by default. Options:

1. Frontend-managed cart (recommended)

Store cart in local state or localStorage
On checkout, convert cart to order using /wc/v3/orders

2. Use a Cart API Plugin

WooCommerce Cart REST API
WooCommerce Store API (for Blocks): /wp-json/wc/store/cart/

Note: The Store API is still evolving and not suitable for all headless use cases.

Full Frontend Flow

Here’s a typical flow for a headless WooCommerce shop:

Product Listing
- Fetch public data from /wc/v3/products
User Authentication
- Call POST /hippoo-auth/v1/login
- Store JWT token
Cart Management
- Build cart in frontend state
- Allow users to add/remove/update products
Checkout
- Collect customer data
- POST to /wc/v3/orders using the stored token
Order History
- Fetch user orders from /hippoo-auth/v1/my-orders
Logout
- Clear token from local storage or memory

Security Considerations

Always use HTTPS in production to secure token-based requests
Protect tokens on the client
Store them in HttpOnly cookies if using SSR frameworks like Next.js
Limit API keys and capabilities for server-side calls
Use Hippoo Auth’s logout endpoint to invalidate sessions if needed

Optional: Custom API Endpoints

You can extend WordPress to expose your own REST API endpoints using:

add_action('rest_api_init', function () {
  register_rest_route('myapp/v1', '/customer-meta', [
    'methods' => 'GET',
    'callback' => function() {
      $user = wp_get_current_user();
      return get_user_meta($user->ID);
    },
    'permission_callback' => function() {
      return is_user_logged_in();
    }
  ]);
});

Conclusion

Going headless with WooCommerce allows you to build faster, more flexible, and modern eCommerce experiences. By combining WooCommerce’s REST API with Hippoo Auth, you can safely handle user login, display personalized data, and manage checkout without relying on traditional WordPress themes.

Whether you’re building a custom storefront, a mobile app, or a progressive web app, this architecture gives you full control while leveraging WooCommerce’s robust backend.

For more tools and extensions to power your headless WooCommerce project, visit Hippoo.app.