WooCommerce Setup

PhantomStudio 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 Astro 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:

• WooCommerce active
• PhantomWP Connect installed and paired (Step 2 below)

Step 1: Create the Store

On the dashboard, click New Project and pick the WooCommerce Store template. This generates the full storefront: shop pages, cart, checkout, customer accounts, and the API routes behind them. See The Dashboard.

When the store first opens in the editor, a welcome dialog offers Open Site Settings.

Step 2: 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

Download the plugin from your project and upload it to WordPress:

1. In the editor, open Site ▾ › WordPress
2. On the Connection tab, enter your site URL, click Fetch, then Download PhantomWP Connect (.zip)
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 WordPress

The store uses the same connection as any WordPress project. Open Site ▾ › WordPress:

1. On the Connection tab, enter your site's address in WordPress Site URL and click Fetch.
2. Check that the plugin badge reads full access. If it doesn't, finish Step 2.
3. Click Save Settings. This writes .env, restarts the dev server, and copies the variables to your deployment if the site is deployed.

The access secret is created for you. You can copy or rotate it on the Security tab.

Step 4: Configure Payments (Optional)

Store projects get a WooCommerce tab in Site ▾ › WordPress. Orders, totals, currency, tax, shipping, coupons and paid-status updates go through PhantomWP Connect; this tab only holds what the payment providers need.

• Storefront URL: the public address of your store, used for payment redirects (PUBLIC_SITE_URL).
• Enable bank transfer / manual payment (BACS): on by default.

Stripe

1. Tick Enable Stripe Checkout
2. Enter your Secret key (sk_test_... or sk_live_...)
3. Enter your Publishable key (pk_test_... or pk_live_...)
4. Enter your Webhook signing secret (whsec_...), needed to mark orders as paid

PayPal

1. Tick Enable PayPal Checkout
2. Choose Sandbox for testing or Live for production
3. Enter your Client ID and Client secret from the PayPal Developer Dashboard

Click Save Settings after changing payments.

Testing Checkout Without Stripe/PayPal

To test the full checkout flow without setting up Stripe or PayPal, use Direct bank transfer (BACS):

1. In WordPress, go to WooCommerce › Settings › Payments
2. Enable Direct bank transfer
3. Save changes, and keep Enable bank transfer / manual payment (BACS) ticked in PhantomStudio

Bank transfer orders are created with a "Pending payment" status and don't need an external payment provider. This lets you test the entire checkout flow (cart, form submission, order creation and the order confirmation page) without API keys.

Rendering

Most store pages (home, shop, category, product, cart, checkout and the account pages) are Static: built when you publish, so they load fast. Search, order confirmation and order detail pages are Dynamic (called Live before PhantomStudio): built on every visit. Cart totals, checkout, orders and logins go through the store's API routes, which run on the server. So a store needs server output in astro.config.mjs (saving the WordPress settings in a store project adds it) and server-capable hosting: Vercel or Cloudflare Workers.

Because product pages are static, new products and price changes show after the next deploy. Set up a deploy hook to deploy when the store changes. See Rendering.

Environment Variables Reference

You don't need to edit .env by hand. Save Settings in Site ▾ › WordPress merges the required variables into it:

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

# Access secret (sent as X-PhantomWP-Secret)
WP_ACCESS_SECRET=...
# Older Woo templates may still read WC_ACCESS_SECRET as a fallback; it gets
# the same value.
WC_ACCESS_SECRET=...

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

# Site URL (for payment redirects)
PUBLIC_SITE_URL=https://your-shop.com

# Which payment methods are on
PUBLIC_PAYMENT_BACS_ENABLED=true
PUBLIC_PAYMENT_STRIPE_ENABLED=false
PUBLIC_PAYMENT_PAYPAL_ENABLED=false
PAYPAL_MODE=sandbox

# Stripe and PayPal keys are also written here
# when you fill them in on the WooCommerce tab

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"

Open Site ▾ › WordPress and click Save Settings again. It rewrites .env and restarts the 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. The WordPress connection is saved, and Site ▾ › WordPress shows the plugin as paired
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 the WooCommerce tab of Site ▾ › WordPress
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