How to Fix WooCommerce Cart Not Persisting When Using JWT‑Based Headless Frontends

by

Modern eCommerce platforms are increasingly moving towards headless architectures to gain better performance and flexibility. One of the most popular combinations includes using WooCommerce as the backend and a JWT-based API authentication system with a headless frontend built in frameworks like React, Vue, or Next.js. However, developers commonly encounter issues where the WooCommerce cart does not persist across sessions or page reloads. This issue can lead to cart abandonment and poor user experience.

Contents

TL;DR

If you’re facing issues with your WooCommerce cart not persisting in a headless frontend using JWT authentication, it’s likely due to session handling limitations. WooCommerce stores cart data in PHP sessions tied to cookies. Without proper handling of cookies or authentication via JWT, the cart resets after each request. Solutions involve syncing sessions across frontend requests, passing WooCommerce session cookies explicitly, or using custom endpoints to fetch and persist cart data manually.

Understanding the Problem

The WooCommerce cart relies heavily on PHP sessions for temporary data storage. These sessions are typically stored server-side and managed via client-side cookies. When moving to a headless setup using JWT authentication, traditional cookie-based mechanisms often break because:

  • The frontend is decoupled and may run on a different domain.
  • Cookies, particularly HTTP-only ones, might not be passed with API requests.
  • JWT is stateless and does not natively maintain session IDs.

This causes a disconnect — WooCommerce tries to create new sessions with every request, leading to cart data loss.

Common Symptoms

  • Adding items to the cart appears to work, but refreshing the page shows an empty cart.
  • Cart data is lost when navigating between pages.
  • Cart behaves correctly in the WordPress-powered admin or default frontend but not in the headless frontend.

Diagnosing the Session Issue

To verify if it’s a session issue, first inspect the network activity in your browser dev tools:

  1. Add an item to the cart through your frontend app
  2. Observe the Set-Cookie response headers from WooCommerce (usually woocommerce_cart_hash, woocommerce_items_in_cart, and wp_woocommerce_session_)
  3. Check if your frontend includes these cookies in subsequent requests.

If the cookies aren’t maintained, your JWT-based frontend requires intervention to preserve session continuity.

Solutions to the Cart Persistence Problem

1. Pass WooCommerce Cookies Explicitly

Set up your frontend to manually handle cookies received from WooCommerce. Since JWT handles authentication, cookies are often stripped out. Use JavaScript libraries like js-cookie to:

  • Capture WooCommerce session cookies
  • Persist them in frontend storage
  • Attach them to every API request as Cookie headers

This allows WooCommerce to associate incoming requests with the correct session ID.

import Cookies from 'js-cookie';

const sessionId = Cookies.get('wp_woocommerce_session_yourhash');

// Attach on every request to WooCommerce via fetch or axios
fetch('/wp-json/wc/store/cart', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${jwtToken}`,
    'Cookie': `wp_woocommerce_session_yourhash=${sessionId}`
  }
});

2. Enable Cross-Origin Cookies

If your frontend and backend operate on different domains (or subdomains), browsers prevent third-party cookies unless explicitly enabled. Update your Set-Cookie headers with SameSite=None; Secure attributes. Also:

  • Make WooCommerce serve cookies with SameSite=None
  • Ensure HTTPS is used for all requests when using Secure flag
  • Use CORS headers correctly to allow credentials
Access-Control-Allow-Origin: https://yourfrontend.com
Access-Control-Allow-Credentials: true

On the frontend, make sure credentials are included in fetch or axios:

fetch('/api/endpoint', {
  credentials: 'include',
  ...
});

3. Create and Handle WooCommerce Sessions Manually

If cookie management becomes too complex, you can use the WooCommerce API to create a session manually. This involves:

  • Creating a backend endpoint that initializes a cart session and exposes the session ID
  • Persisting this ID in local storage on the frontend
  • Reattaching it to requests through a custom proxy or API

4. Offload Cart Storage to Client

To get around PHP-based sessions entirely, save cart data in the client’s local storage or Redux state and synchronize with WooCommerce only when needed. This approach works best with light carts or those that do not need tight server integration.

However, there are limitations with tax calculations, shipping estimates, stock validation, and coupon logic in purely local carts. So users should eventually sync their cart with WooCommerce via authenticated POST requests to the Store API.

5. Use WooCommerce Store API (v2+)

The newer WooCommerce Store API includes more robust endpoints for headless implementations:

  • POST /wc/store/cart/items — add items
  • GET /wc/store/cart — retrieve cart
  • POST /wc/store/cart/coupons — apply discount codes

Using this API allows you to serialize and persist the cart data via JWT-authenticated calls directly without depending fully on PHP sessions.

Best Practices

  • Use HTTPS for all API requests to support cookie sharing.
  • Keep session logic in sync between client and server.
  • Avoid hardcoding session IDs — treat them securely as tokens.
  • Regularly test on multiple browsers, especially Safari (strict cookie policies).

Conclusion

Fixing WooCommerce cart persistence in JWT-based headless frontends involves understanding session mechanisms, cookie behaviors, and using modern APIs. While JWT offers a seamless user authentication model, it requires complementary solutions for maintaining user session continuity, particularly with legacy systems like WooCommerce that rely on traditional PHP sessions.

By carefully managing cookies or leveraging the official Store API for cart handling, developers can ensure a smooth and reliable shopping experience across headless implementations.

FAQ

  • Q: Why does my cart reset every time I refresh the page?
    A: This is likely due to missing or unmanaged WooCommerce session cookies in a headless setup. The session isn’t being persisted across requests.
  • Q: Can I use only JWT without cookies?
    A: JWT can handle authentication, but WooCommerce still relies on cookies for session data unless restructured using the Store API.
  • Q: Is it safe to store WooCommerce session IDs in local storage or cookies?
    A: Treat session IDs as tokens. If you choose to store them client-side, secure them using HTTPS and avoid exposing them unnecessarily.
  • Q: Which WooCommerce API version supports headless carts best?
    A: Store API (v2+) introduced a more RESTful and stateless cart structure ideal for headless commerce.
  • Q: How do I test whether cookies are the issue?
    A: Use browser dev tools to inspect the presence and transmission of woocommerce_cart_hash, woocommerce_items_in_cart, and wp_woocommerce_session_ cookies.