WooCommerce Setup

PhantomWP can turn your WooCommerce store into a headless Astro storefront. You keep WooCommerce for orders, inventory, taxes, shipping, and customer management while serving a fast static frontend. Products can be fetched from WooCommerce's Store API, while checkout, orders, customer accounts, VAT, and shipping calculations go through PhantomWP Connect.

Prerequisites

Before you start, your WordPress site needs:

• PhantomWP Connect plugin installed and paired
• WooCommerce active on the same WordPress site

Step 1: Install the PhantomWP Connect Plugin

WooCommerce checkout, customer login, registration, account features, order creation, VAT, and shipping calculations are handled by the PhantomWP Connect WordPress plugin. No WordPress application password or separate WooCommerce REST API key is required for the normal connection flow.

For a full reference on the plugin (endpoints, security model, troubleshooting), see the dedicated PhantomWP Connect Plugin documentation.

Install and Activate

PhantomWP Connect installs automatically when you connect a WordPress site from the PhantomWP IDE. If you need to install it manually:

1. In the PhantomWP IDE, open the WordPress connect panel
2. Download the plugin zip from the Install plugin link
3. In WordPress admin, go to Plugins > Add New > Upload Plugin
4. Upload the zip, then click Install Now and Activate

Pairing runs automatically on the first admin page load after activation. When the WordPress plugin shows Paired on the PhantomWP menu in wp-admin, authentication is ready.

Verify Customer Auth Works

Test that auth is wired up by calling the token endpoint:

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

A successful response looks like:

{
  "success": true,
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user_email": "user@example.com",
  "user_nicename": "username",
  "user_display_name": "Display Name",
  "roles": ["customer"]
}

If you get "No route was found matching the URL and request method", the plugin is not active or the pairing did not complete. Check the PhantomWP menu in wp-admin for status.

Step 3: Connect in PhantomWP

Now that PhantomWP Connect is ready, finish wiring everything up 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 Connection

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 the connection, 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 merges the required environment variables when you click Save Configuration.

The generated .env file contains:

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

# Access Secret (for protecting origin requests)
WP_ACCESS_SECRET=...
# Legacy Woo templates may still read WC_ACCESS_SECRET as a fallback, but new
# generated PhantomWP/Woo requests send WP_ACCESS_SECRET as X-PhantomWP-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 PhantomWP Connect plugin is not installed or not activated. In WordPress admin, go to Plugins and verify PhantomWP Connect is active, then open the PhantomWP menu and confirm the status shows Paired.

"WordPress connection is not configured"

Save the WordPress/WooCommerce connection again and restart the local dev server. The generated storefront expects WP_API_URL and WP_ACCESS_SECRET for the PhantomWP Connect bridge.

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 PhantomWP Connect is installed and active in WordPress
2. Open the PhantomWP menu in wp-admin and confirm the status shows Paired
3. Test the token endpoint directly with curl (see Step 2)
4. If you recently upgraded from the old JWT Authentication for WP REST API plugin, existing sessions are invalidated - ask customers to log in again

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