Connection Status & Troubleshooting

The Connection Status card on the WooCommerce settings tab confirms that the Real ID API can reach your WordPress site. This bidirectional reachability is required for post-checkout verification status to sync back to your orders. If a customer completes their ID check but their WooCommerce order's metadata never updates, the connection is the first thing to check.

Where to find it

In your WordPress admin: Real ID → Settings → Status tab. The first card on the tab is API Connection Status.

It runs automatically when you open the tab. Use the Retry / Re-check connection button to run it again on demand. The Status tab also has a shortcut to view your Real ID logs in WooCommerce and a button to refresh the plugin's cache.

What the check does

When you (or the auto-check) trigger it, the Real ID plugin asks our API to call back to your site at:

GET /wp-json/real-id/v1/version

…using your shop's license key as the Authorization: Bearer <licenseKey> header. The same code path our backend uses when it syncs verification status onto your orders. So if this check passes, every other webhook callback we make will also reach your site.

Status meanings

Status	What it means	What to do
✅ Connected	Our API reached your site, your license key was accepted, and the plugin responded with version info.	Nothing — sync should be working.
⚠️ License not activated	No license key is set on the plugin yet.	Activate the license under Real ID → Billing.
⚠️ Authentication failed	Your site responded but rejected our license key.	Re-activate the license. If it persists, your stored license key may be out of sync with our records — contact support.
❌ Plugin route not found	Our request reached WordPress, but /wp-json/real-id/v1/version returned 404.	Make sure the Real ID plugin is active and updated to the latest version.
❌ Blocked by firewall or WAF	Our request returned 403 with a non-JSON body — typical of a Cloudflare, Sucuri, or hosting-level firewall blocking /wp-json/* before it reaches WordPress.	See the WAF / Cloudflare section below. This is the most common cause when sync silently stops working on a previously-healthy site.
❌ Request timed out	Our request didn't get a response within 8 seconds. Often caused by a JS-challenge bot protection (Cloudflare Bot Fight Mode, Super Bot Fight Mode) — our backend cannot solve a browser challenge and the request just hangs.	Disable the JS challenge for /wp-json/real-id/v1/*, or allowlist requests carrying a Bearer Authorization header.
❌ Site unreachable	DNS failed or the site refused the connection.	Confirm the site is online and resolves publicly (curl -I https://yourdomain.com).
❌ Real ID API unreachable	Your WordPress site couldn't reach the Real ID API itself — the failing leg is on our side, not yours.	Usually transient. Wait a few minutes and retry. If it persists, contact Real ID support.
❌ Unexpected response	The site responded with something we didn't recognize.	Contact support and share the response body shown on the card.

Blocked by firewall or WAF

If the indicator is red with Blocked by firewall or WAF, a layer in front of WordPress is rejecting our requests. Common culprits:

Cloudflare (most common)

1. Open your Cloudflare dashboard → select the zone for your site.
2. Go to Security → Bots → Configure Super Bot Fight Mode.
   • If "Definitely automated" is set to Block, our backend (which runs from cloud serverless platforms) is being flagged.
   • Either set this to Allow for /wp-json/real-id/v1/*, or add a WAF skip rule:
3. Go to Security → WAF → Custom rules and add a rule:
   • Field: URI Path, Operator: starts with, Value: /wp-json/real-id/v1/
   • And: HTTP Request Header — Authorization, Operator: starts with, Value: Bearer
   • Action: Skip → check All remaining custom rules, Bots, Managed rules.

Kinsta hosting firewall

Kinsta hosts many WP sites and proxies through Cloudflare. In MyKinsta dashboard → your site → Tools → IP Deny, confirm there are no rules blocking external IPs broadly. If you have Kinsta APM or custom rules, review those for /wp-json/* patterns.

WordPress security plugins

Plugins like Wordfence, iThemes Security, or All In One WP Security can block REST API access. Check for:

• "Block REST API for non-logged-in users" toggles — disable for /real-id/v1/* paths
• IP-based rate limiting that may be flagging our serverless egress

Why we can't just give you an IP allowlist

Our backend runs on AWS Lambda and Vercel, so the source IP rotates across a large pool. There's no fixed IP set we can hand you to allowlist. Instead, allowlist by path + Authorization header, as shown in the Cloudflare example above.

What to do after fixing the block

1. Go back to Real ID → Settings → Status in WordPress admin
2. Click Re-check connection
3. The status should turn green within a few seconds

Your in-flight verification syncs will resume on their next QStash retry — there's nothing additional to manually replay on your end. If you have specific orders you suspect missed their sync, contact support with the order IDs.