Connect the storefront

WordPress and the storefront are two separate websites. This page connects them from the WordPress side: WordPress learns the storefront’s address, both sides share the secrets that keep sign-in and checkout safe, and you check that the storefront can read your settings.

Before you start

• The Companion plugin is installed and active (Install the Companion plugin).
• You know the storefront’s public address, for example https://shop.example.com. Ask whoever deploys the storefront if you don’t.
• Someone can edit the site’s wp-config.php file (your developer or your host).

Step 1: Set the Storefront URL

StoreFront›Settings›General

1. Go to StoreFront › Settings. The General tab opens first.

2. In the Headless storefront card (“Where customers actually browse the store.”), type the storefront’s address into Storefront URL, for example https://shop.example.com.

3. Click Save Changes. The card now shows a Connected badge.

Setting	What it does	Default
Storefront URL	The storefront’s public address. Everything in WordPress that links to the storefront uses it (see the list below).	Empty

The field is forgiving, but it has rules:

• Only a full http:// or https:// address is accepted. If you leave out the scheme, https:// is assumed.
• A trailing slash is removed and anything after a ? is dropped. A path is kept.
• If the value can’t be used (for example, a relative path), the field quietly keeps the previously saved address. Check the field after saving.
• If the field is greyed out with a Defined in wp-config.php chip, the address is pinned with the RSC_FRONTEND_URL constant. Change it in wp-config.php instead.

What the Storefront URL drives. More depends on this one field than its help text suggests:

• Links in verification and password-reset emails.
• Links in back-in-stock emails and their sign-up confirmations.
• Where the Brevo double opt-in confirmation sends shoppers (/?newsletter=confirmed).
• The Header builder’s live preview, which shows the storefront’s real header.
• The view links on the Static Pages tab, and Preview and View links on products.
• The redirect that sends visitors from a product’s WordPress page to the storefront.
• Stripe Express Checkout: the storefront’s domain is registered with Stripe automatically.
• The addresses shown in the Google and Facebook sign-in setup guides.

Don't leave it empty

Without a Storefront URL, verification and password-reset emails fall back to a WordPress API address that answers in raw JSON instead of a page. New shoppers can’t finish signing up.

Step 2: Add the secrets to wp-config.php

Two secrets can only live in wp-config.php, never in the settings screen. Ask your developer or host to add these lines above the line that reads /* That's all, stop editing! */.

// Required. Signs the storefront's sign-in tokens. 64 or more random characters.
// The Social Login tab shows a ready-to-paste line with a freshly generated secret.
define( 'RSC_JWT_SECRET', 'paste-a-long-random-secret-here' );

// Strongly recommended when you take payments. Must be exactly the same value
// as the storefront's STOREFRONT_SHARED_SECRET. Generate one with: openssl rand -hex 32
define( 'RSC_STOREFRONT_SHARED_SECRET', 'paste-the-shared-secret-here' );

// Optional. Pin values instead of typing them into the settings screen.
// Each pinned field becomes read-only in wp-admin.
// define( 'RSC_FRONTEND_URL', 'https://shop.example.com' );
// define( 'RSC_GOOGLE_CLIENT_ID', 'your-id.apps.googleusercontent.com' );
// define( 'RSC_FACEBOOK_APP_ID', 'your-app-id' );
// define( 'RSC_FACEBOOK_APP_SECRET', 'your-app-secret' );
// define( 'RSC_TURNSTILE_ENABLED', true );
// define( 'RSC_TURNSTILE_SITE_KEY', 'your-site-key' );
// define( 'RSC_TURNSTILE_SECRET_KEY', 'your-secret-key' );

Constant	Required	What it does
RSC_JWT_SECRET	Yes	Signs the tokens that keep shoppers signed in. Without it, sign-in, registration and every account feature are switched off. It is never stored in the database or shown in wp-admin.
RSC_STOREFRONT_SHARED_SECRET	Strongly recommended for any store taking payments	Lets WordPress trust which shopper a checkout request comes from, so checkout attempts can be limited per shopper. This protects you against “card testing” (fraudsters trying stolen cards in bulk). It must match the storefront’s STOREFRONT_SHARED_SECRET exactly.
RSC_FRONTEND_URL and the others	No	Pin a value so it can’t be changed from the screen. Useful when the same database serves several environments.

The easy way to get a JWT secret. Open StoreFront›Settings›Authentication›Social Login. While no secret is set, an amber banner shows a ready-to-paste define( 'RSC_JWT_SECRET', '…' ); line with a freshly generated 64-character secret and a Copy button. A new secret is generated each time the page loads; use any one of them, once.

Keep these secrets secret

Never paste either secret into an email, a ticket or a chat. Pick each value once and keep it.

The shared secret must be identical on both sides. If the two values differ, WordPress can’t tell shoppers apart and treats every guest as coming from the storefront’s server, so the checkout limit (five attempts a minute) is shared by all guests at once. On a busy store that blocks real checkouts. If you change the secret, change it on both sides together.

You may also see RSC_DISABLE_EMAIL_VERIFICATION in developer notes. It lets accounts sign in without confirming their email and is meant for local testing only. Never set it on a live store.

Step 3: Check API Access

StoreFront›Settings›Authentication›API Access

This tab decides which WooCommerce APIs need a signed-in shopper. The defaults are right for the standard storefront, so you normally just check them:

• Protected namespaces contains wc/v3 (accounts and orders need sign-in).
• Public routes is empty.
• The WooCommerce Store API (wc/store/v1), which serves the catalogue, cart and checkout, stays open.

If someone has changed these, see Sign-in and security before editing them. Clearing the protected list by mistake leaves account data unprotected.

Step 4: Share the details with the storefront team

The storefront has its own configuration, set by whoever deploys it. Send them:

They need	Value
Your WordPress address	For example https://wp.example.com (no trailing slash)
The Companion API address	Your WordPress address followed by /wp-json/retail-store-companion/v1
The shared secret	The same value you put in RSC_STOREFRONT_SHARED_SECRET, sent through a password manager or another secure channel

Payment keys, Google and Facebook credentials and Turnstile keys are not on that list. They stay in WordPress, and the storefront reads what it needs from here. The storefront side is described in Connect to WooCommerce.

How the storefront reads your settings

The Companion plugin publishes your settings at read-only addresses under /wp-json/retail-store-companion/v1/. The storefront reads them when it builds each page:

• Public settings (colours, header, footer, home page sections, pages, SEO) are readable by anyone, as on any public website. Secrets are never included: for social sign-in, for example, the storefront receives only whether each provider is on and its public ID.
• No webhooks. WordPress doesn’t notify the storefront when you save. Each answer may be cached for up to 5 minutes, so changes reach shoppers within about 5 minutes.
• Payment settings are read fresh on every checkout, so switching Stripe or PayPal between test and live mode applies to the next checkout.

Verify the connection

Run through this checklist once both sides are configured.

1. General tab: the Headless storefront card shows Connected.

2. Social Login tab: the banner at the top is green and reads “JWT signing secret is configured”.

3. Settings feed: open https://your-wordpress-site/wp-json/retail-store-companion/v1/storefront/settings in a browser (use your own WordPress address). You should see a page of data, not an error.

4. Header tab: open any header with Edit. The preview should be labelled “Desktop layout — real storefront”, not “This is a simplified mock”.

5. Dashboard: if you take card or PayPal payments, there is no notice saying RSC_STOREFRONT_SHARED_SECRET is not defined.

6. A live change: change something visible, such as the Testimonials heading, save, wait 5 minutes and reload the storefront. Change it back afterwards.

7. Sign-up: on a test or staging store, register a test account on the storefront. The verification email’s link should open a page on the storefront’s address.

Caution

Don’t create test accounts or orders on a live store your customers are using. Use a staging copy for the last step.

Troubleshooting

Symptom	Likely cause	What to do
Shoppers can’t sign in or register; the storefront reports a server error	RSC_JWT_SECRET is missing	Add it to wp-config.php (Step 2).
Verification emails open a page of raw data	No Storefront URL	Set it on the General tab (Step 1).
The saved Storefront URL changed back	The value wasn’t a full web address	Type the whole address, starting with https://.
The header preview says “simplified mock”	No Storefront URL, or the storefront isn’t reachable	Set the URL and check the storefront is online.
The settings feed in check 3 shows an error	Permalinks set to Plain, or a security plugin blocks the WordPress API	Change permalinks (see WooCommerce settings) or allow /wp-json/ in the security plugin.
A notice says the shared secret is missing	RSC_STOREFRONT_SHARED_SECRET isn’t defined	Add it to wp-config.php and give the same value to the storefront team.

Next steps

WooCommerce settingsPermalinks, time zone, locations and the rest the storefront relies on.

PaymentsStripe, PayPal, Express Checkout and offline methods.

Sign-in and securityGoogle, Facebook, Turnstile, sessions and API access.

wp-config constantsEvery constant the Companion plugin reads.