Store Features

This page covers everything the headless storefront includes out of the box.

Architecture

The storefront follows a hybrid approach:

• Product pages load WooCommerce Store API data at dev/build time, with optional synced JSON snapshots for tooling
• Cart is client-side using nanostores and localStorage (no server needed)
• Checkout, orders, coupons, and auth use server-side API routes that call PhantomWP Connect in real-time

This means product browsing is instant (served from CDN) while transactional features stay connected to your live WooCommerce backend.

Pages

The template generates these pages:

Product Data

Products are fetched from WooCommerce Store API. The WooCommerce settings panel can also sync local snapshots and images:

• src/data/products.json - All product data (name, price, images, categories, variations, stock, etc.)
• src/data/categories.json - Product categories
• src/media/products/ - Downloaded product images (optimized by Astro at build time)
• src/lib/product-media-map.json - Maps WooCommerce image URLs to local paths

Data Access

All product data functions are async:

import {
    getLocalProducts,
    getLocalProduct,
    getLocalCategories,
    getLocalVisibleCategories,
    getLocalProductsByCategory,
    getLocalFeaturedProducts,
    getLocalRelatedProducts,
} from '../lib/local-product-data';

Helpers

import { formatPrice, isInStock, getDiscountPercentage, stripHtml } from '../lib/woocommerce';

Cart

The cart is entirely client-side using nanostores for reactive state. No server round-trips for adding/removing items.

import {
    $cart, $cartCount, $cartTotal,
    addToCart, removeFromCart, updateQuantity, clearCart,
    openCartDrawer, closeCartDrawer,
} from '../lib/cart';

Cart data persists in localStorage across page navigations and browser sessions.

Authentication

Customer authentication uses PhantomWP Connect Visitor Authentication. The WordPress admin panel (wp-login.php) can remain locked down - all auth flows go through the Astro API routes.

Login and Registration

import {
    $isLoggedIn, $user, $token,
    login, register, logout,
    getToken, initAuth,
    requestPasswordReset,
} from '../lib/auth';

• login(email, password) calls /api/auth/login which authenticates via PhantomWP Connect visitor authentication
• register({ email, password, firstName?, lastName? }) creates a WooCommerce customer
• Auth state (token + user info) is stored in localStorage

Password Reset

The forgot password flow is self-contained and does not depend on WordPress's wp-login.php:

1. User submits email on /forgot-password
2. API route asks PhantomWP Connect to start the reset flow
3. WooCommerce/WordPress sends the reset email
4. The reset page posts the reset key back through PhantomWP Connect

API Routes

Checkout

The checkout page dynamically loads configuration from your WooCommerce store:

• Payment gateways - Reads enabled supported gateways from WooCommerce
• Shipping methods - Calculates valid rates for the customer's address
• Customer addresses - Pre-fills billing/shipping if logged in
• Stock validation - WooCommerce validates stock during order creation; optional REST precheck runs only when REST keys are configured

Order Flow

1. Customer fills in the checkout form
2. Totals, tax, coupons, and shipping are calculated by WooCommerce
3. Order is created via /api/orders/create through PhantomWP Connect
4. For BACS/manual payment, the customer lands on /order-complete
5. Optional Stripe/PayPal flows require their own provider configuration

Payment Gateways

BACS/manual payment is the default basic-store path.

Stripe - Uses Stripe Checkout (redirect flow). Requires Stripe keys in .env and a webhook endpoint for payment confirmation.

PayPal - Uses the PayPal Orders API. Supports both sandbox and live modes.

Stripe and PayPal are advanced optional flows. To test the checkout flow without setting up a payment provider, enable Direct bank transfer (BACS) in WooCommerce.

Customer Account

Logged-in customers can:

• View order history (/account/orders)
• Manage billing and shipping addresses (/account/addresses)
• Update their name and password (/account/settings)

All account operations use the WooCommerce REST API with JWT token authentication.

API Routes

Components

Astro Components (src/components/shop/)

React Components (src/components/react/)

These need client:load for hydration:

Limitations

Since this feature is in alpha, there are some current limitations:

• Product stock display can lag - Product pages use build/dev-time Store API data. WooCommerce validates stock again during order creation.
• No product variations UI - Variable products are supported in data, but the product page does not yet show a variation picker (e.g. size/color dropdowns).
• Coupons depend on WooCommerce validation - Coupon preview and final order totals are calculated by WooCommerce through PhantomWP Connect.
• No order tracking - Customers can see order status but there is no shipment tracking integration.
• Image sync is manual - Product images in development need to be re-synced manually after adding new images in WooCommerce.
• Email delivery - The forgot password flow relies on being able to send email from the server. This works well on hosted platforms but may need configuration in development.

Next Steps

• WooCommerce Setup - How to connect your store
• Deploying to Vercel - Deploy your headless store to production