Connect WooCommerce

A connection has two halves. WordPress needs the Companion plugin (Retail Store Companion), two secrets in wp-config.php and the storefront’s address. The storefront needs to know where WordPress lives, plus a shared secret and optional WooCommerce REST keys. This page walks through both, then shows how to check the result.

Before you start

• The storefront runs locally in Demo Mode. If not, start with Install.
• WordPress with WooCommerce active, served over HTTPS, with permalinks set to anything but Plain.
• Administrator access to wp-admin and the ability to edit wp-config.php.

Danger

Connect your local storefront to your own development or staging store. The weLabs QA store at westore.welabs.dev is read-only for everyone: browse it, but never place orders or create accounts there.

The WordPress side

The full click-by-click guides are Install the Companion plugin and Connect the storefront. In short:

1. Install and activate the Companion plugin. It appears under Plugins as “Retail Store Compaion” (that spelling is the plugin’s own).

2. Add two secrets to wp-config.php. RSC_JWT_SECRET signs shopper sign-in tokens; without it, sign-in and registration fail. RSC_STOREFRONT_SHARED_SECRET must match the storefront’s STOREFRONT_SHARED_SECRET (see the shared secret below).

   // Required: signs storefront access tokens. 64 or more random characters.
   define( 'RSC_JWT_SECRET', 'paste-a-long-random-value-here' );
   
   // Recommended in production: the same value as STOREFRONT_SHARED_SECRET.
   define( 'RSC_STOREFRONT_SHARED_SECRET', 'paste-the-shared-secret-here' );

   The Social Login tab shows a ready-to-paste RSC_JWT_SECRET line with a freshly generated value while the constant is missing.

3. Tell WordPress where the storefront lives. Go to StoreFront›Settings›General and enter the storefront’s public address in Storefront URL, for example https://shop.example.com. Verification and password-reset emails, back-in-stock emails, product preview links, the header builder’s live preview, product redirects and Stripe’s wallet domain registration all use it. You can pin it in wp-config.php with RSC_FRONTEND_URL instead.

4. Leave API Access at its defaults. StoreFront›Settings›Authentication›API Access protects wc/v3 and leaves the Store API open, which is what the storefront expects.

The other wp-config.php constants are listed in wp-config constants.

Create WooCommerce REST API keys

Browsing, search, cart, checkout and sign-in work without keys: they use WooCommerce’s public Store API and the Companion plugin’s sign-in tokens. Keys add the features that read WooCommerce’s REST API as the store.

1. In wp-admin, go to WooCommerce›Settings›Advanced›REST API and click Add key.
2. Give it a description you will recognise later, such as Storefront production.
3. Choose an administrator or shop manager account as the User.
4. Set Permissions to Read.
5. Click Generate API key and copy the Consumer key (ck_…) and Consumer secret (cs_…). WooCommerce shows the secret only once.

Use one key pair per storefront deployment (production, staging) so you can revoke one without touching the other.

What keys add

Feature	With keys	Without keys
Country pickers at checkout, in the cart’s shipping estimator and in the Address Book	Only the countries you sell to and ship to	Every country
Express checkout buttons on product pages	Offered where you switched them on	Not offered on product pages; cart and checkout still offer them

A signed-in shopper’s own orders, profile and addresses are read with that shopper’s sign-in token, not with the store’s keys.

The storefront side

Edit apps/storefront/.env on your machine. On a deployed storefront, set the same variables in your host’s settings (see Deployment).

# Which backend: woocommerce. Unset, mock or fake = Demo Mode.
COMMERCE_SOURCE=woocommerce

# Your WordPress site, no trailing slash.
WOO_STORE_URL=https://cms.example.com

# The Companion plugin's REST base on that site.
RSC_API_URL=https://cms.example.com/wp-json/retail-store-companion/v1

# Signs the session cookie (openssl rand -base64 32).
AUTH_SECRET=your-generated-secret

# The storefront's own public address, no trailing slash.
SITE_URL=https://shop.example.com

# WooCommerce REST keys, Read permission.
WOO_CONSUMER_KEY=ck_your_key
WOO_CONSUMER_SECRET=cs_your_secret

# The same value as RSC_STOREFRONT_SHARED_SECRET in wp-config.php.
STOREFRONT_SHARED_SECRET=your-shared-secret

Restart pnpm dev after editing the file.

Caution

Always set RSC_API_URL in WooCommerce mode. Sign-in finds the Companion plugin from WOO_STORE_URL on its own, but the newsletter, contact form, profile photo and compare sync use RSC_API_URL directly and otherwise fall back to a local development address.

Nothing for payments, Google or Facebook sign-in, or Turnstile goes here. The storefront reads which providers are configured, and their public keys, from WordPress.

The shared secret

STOREFRONT_SHARED_SECRET and RSC_STOREFRONT_SHARED_SECRET hold the same random value. With it, the storefront signs each shopper’s IP address on cart and checkout requests, so WordPress’s payment rate limits count individual shoppers instead of treating the storefront server as one very busy client. Without it, WordPress shows an admin notice while a gateway takes storefront payments, and the per-shopper checkout limit is off.

Generate one value and put it in both places:

openssl rand -hex 32

The shopper’s address comes from the X-Forwarded-For header, so the storefront must run behind a proxy that sets it. Cloudflare and most hosting platforms do this for you.

Check the connection

Run through this list once the storefront restarts.

• The Home page and /shop show your own products, not the demo catalogue.
• The header, footer and colours match what is set under StoreFront → Settings.
• You can register a test account, receive the verification email and sign in.
• Account → Orders lists that account’s orders.
• The checkout’s country list shows only the countries you sell to (needs REST keys).
• Checkout lists the payment methods you enabled in WooCommerce, still in test mode.
• The admin notice about a missing shared secret is gone.
• Opening a published product’s WordPress page redirects to the same product on the storefront (only once the Storefront URL is set and the storefront is on a different host from WordPress).
• The header builder’s live preview in wp-admin shows the storefront’s header.

If something fails, see Troubleshooting and Store admin troubleshooting.

Fill in brand categories

The brand directory at /brands shows each brand’s main category and filters by it. A daily WordPress job works these out. On a store that already has brands, run the job once instead of waiting a day:

wp cron event run rsc_backfill_brand_primary_category

If WP-CLI reports that the event does not exist, deactivate and reactivate the Companion plugin once to schedule it, then run the command again.

Tip

A headless WordPress gets few page views, so WP-Cron runs late. Set up a real system cron for wp-cron.php before launch, or back-in-stock emails and daily jobs will lag. See Emails and background jobs.

Next steps

ConfigurationLanguages, Home sections and checkout behaviour.

PaymentsSet up Stripe and PayPal in WordPress.

DeploymentPut the connected storefront online.