WooCommerce Setup

PhantomWP can turn your WooCommerce store into a headless Astro storefront. You keep WooCommerce for orders, inventory, and customer management while serving a fast static frontend. Products are pre-rendered at build time. Cart, checkout, authentication, and payments are handled via server-side API routes that talk to WooCommerce's REST API.

Prerequisites

Before you start, your WordPress site needs:

• WooCommerce REST API enabled (with API keys generated)
• JWT Authentication for WP REST API plugin installed and configured

Step 1: Enable the WooCommerce REST API

The REST API is how PhantomWP reads products, categories, customer data, and creates orders.

Generate API Keys

1. In WordPress admin, go to WooCommerce > Settings > Advanced > REST API
2. Click Add key
3. Set the description to something like PhantomWP
4. Set the user to an Administrator account
5. Set permissions to Read/Write
6. Click Generate API key

You will see a Consumer Key (ck_...) and Consumer Secret (cs_...). Copy both - the secret is only shown once.

Step 2: Install the JWT Authentication Plugin

Customer login, registration, and account features require the JWT Authentication for WP REST API plugin. Without it, customers cannot sign in or manage their accounts on the headless storefront.

Install and Activate

1. In WordPress admin, go to Plugins > Add New
2. Search for JWT Authentication for WP REST API (by Starter Dev)
3. Click Install Now, then Activate

Alternatively, install from the WordPress plugin directory.

Configure wp-config.php

The plugin requires two additions to your wp-config.php file. Connect to your server via FTP/SSH and open the file (it is in the WordPress root directory).

Add these lines before the line that says /* That's all, stop editing! */:

/** JWT Authentication Secret Key */
define('JWT_AUTH_SECRET_KEY', 'your-secret-key-here');

/** Enable CORS for the REST API */
define('JWT_AUTH_CORS_ENABLE', true);

For the secret key, generate a strong random string. You can use this WordPress salt generator and copy any one of the values, or use a password generator.

Configure .htaccess (Apache only)

If your site runs on Apache, the JWT plugin needs the Authorization header to be passed through. Add this to the top of your .htaccess file (in the WordPress root):

RewriteEngine on
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule ^(.*) - [E=HTTP_AUTHORIZATION:%1]

If you are using Nginx, add this to your server block:

location / {
    # Pass Authorization header to PHP
    fastcgi_param HTTP_AUTHORIZATION $http_authorization;
}

Verify JWT Works

Test that the plugin is active by calling the token endpoint:

curl -X POST https://yoursite.com/wp-json/jwt-auth/v1/token \
  -H "Content-Type: application/json" \
  -d '{"username": "your-wp-username", "password": "your-wp-password"}'

A successful response looks like:

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user_email": "user@example.com",
  "user_nicename": "username",
  "user_display_name": "Display Name"
}

If you get "No route was found matching the URL and request method", the plugin is not active or not installed correctly.

Step 3: Connect in PhantomWP

Now that the REST API and JWT are ready, connect everything in the PhantomWP IDE.

Create a WooCommerce Site

When creating a new site in PhantomWP, select WooCommerce Store as the template type. This generates the full storefront including shop pages, cart, checkout, customer accounts, and all necessary API routes.

Open WooCommerce Settings

In the IDE, click the shopping cart icon in the header bar to open the WooCommerce Settings modal.

Configure Credentials

Fill in the following fields:

Click Test Connection to verify everything works. You should see a success message with your store name and product count.

Click Save Configuration to write the .env file and restart the dev server.

Sync Products and Images

After saving credentials, click Sync Products & Images to:

1. Download all product data (names, prices, descriptions, variations, stock)
2. Download product images to your project for Astro image optimization
3. Generate the product media map for local image resolution

Products are stored in src/data/products.json and images in src/media/products/. This data is used at build time to pre-render all product pages.

Step 4: Configure Payments (Optional)

PhantomWP supports Stripe and PayPal for checkout. Configure them in the Payments section of the WooCommerce Settings modal.

Stripe

1. Enable Stripe in the modal
2. Enter your Secret Key (sk_test_... or sk_live_...)
3. Enter your Publishable Key (pk_test_... or pk_live_...)
4. Enter your Webhook Secret (whsec_...) - needed to mark orders as paid

PayPal

1. Enable PayPal in the modal
2. Enter your Client ID and Client Secret from the PayPal Developer Dashboard
3. Select Sandbox for testing or Live for production

Testing Checkout Without Stripe/PayPal

If you want to test the full checkout flow without setting up Stripe or PayPal, enable Direct bank transfer (BACS) in WooCommerce:

1. Go to WooCommerce > Settings > Payments
2. Enable Direct bank transfer
3. Save changes

Bank transfer orders are created with a "Pending payment" status and do not require any external payment provider. This lets you test the entire checkout flow - cart, form submission, order creation, and the order confirmation page - without needing API keys.

Environment Variables Reference

You do not need to edit .env manually. The WooCommerce Settings modal writes all environment variables automatically when you click Save Configuration - including store credentials, payment gateway keys, and the site URL.

The generated .env file contains:

# WooCommerce Store URL
WC_API_URL=https://yoursite.com/wp-json

# WooCommerce REST API Credentials
WC_CONSUMER_KEY=ck_...
WC_CONSUMER_SECRET=cs_...

# Access Secret (for securing API routes)
WC_ACCESS_SECRET=...

# JWT Secret (for customer auth tokens)
JWT_SECRET=...

# Site URL (for payment redirects)
PUBLIC_SITE_URL=http://localhost:4321

# Stripe and PayPal keys are also written here
# if configured in the Payments section of the modal

Troubleshooting

"No route was found matching the URL and request method"

The JWT Authentication plugin is not installed or not activated. Go to Plugins in WordPress admin and verify it is active.

"Consumer key is missing"

The REST API keys are incorrect or not entered. Double-check the Consumer Key and Consumer Secret in WooCommerce Settings.

Products Not Showing

Make sure:

1. You have published products (not drafts) in WooCommerce
2. You have clicked Sync Products & Images after saving credentials
3. Products have a status of "Published" and are not set to "Private"

Login Not Working

1. Verify the JWT plugin is installed and active
2. Check that JWT_AUTH_SECRET_KEY is defined in wp-config.php
3. If using Apache, verify the .htaccess rewrite rules are in place
4. Test the token endpoint directly with curl (see Step 2)

Checkout Errors

1. Make sure payment gateways are enabled in both WooCommerce and PhantomWP
2. Check that shipping zones and methods are configured in WooCommerce > Settings > Shipping
3. Verify the PUBLIC_SITE_URL environment variable is set correctly for payment redirects

Next Steps

• Store Features - Overview of all storefront features
• Deploying to Vercel - Deploy your headless store