How to Connect WordPress (and WooCommerce)
Updated
Before You Start#
- Self-hosted WordPress (the WordPress.org software), version 5.6 or later, served over HTTPS.
- Your site must be at the root of its domain, like example.com. A WordPress install in a subfolder, like example.com/blog, cannot be connected.
- Log in as an Administrator. SEOmatic acts as the WordPress user who approves it. An Editor works for most fixes, but cannot add structured data or apply robots.txt changes.
- Permalinks are not set to Plain. In WordPress, go to Settings, then Permalinks, and pick any other option.
- Security tools let SEOmatic through. If you use Cloudflare, Wordfence or a host firewall, read Fix connection errors below first.
Connect Your WordPress Site#
- In the sidebar, under Setup, click Connections.
- On the WordPress row, click Add Connection.
- In Domain name, type your domain only, like
example.com. Leave out https:// and any slash at the end. - Click Connect. SEOmatic checks your site, then sends you to your WordPress admin.
- Log in to WordPress if asked. Use an Administrator account.
- WordPress asks you to approve an application named seomatic. Click Yes, I approve of this connection.
- You land back in SEOmatic on a page called Setting Up Connection. Wait a few seconds.
- When the page title changes to Current Connection and the card shows a green Active status, you are done.
Finish within 30 minutes, in the same browser
The approval link works for 30 minutes and only in the browser where you clicked Connect. If you see This WordPress approval link expired or was not started here, click Add Connection again.
Connecting creates an Application Password called seomatic on your WordPress user. You can see it, or revoke it, in WordPress under Users, then Profile, then Application Passwords. Revoking it stops SEOmatic from making changes.
Or Connect From the SEOmatic AI Plugin#
If you installed the free SEOmatic AI plugin first, you can connect from WordPress. Its key arrives by itself, so there is nothing to copy.
- In WordPress, open SEOmatic, then Home, and click Connect.
- Sign in to SEOmatic, or create a free account.
- Click Allow publishing. WordPress asks you to approve SEOmatic, the same Application Password screen as above. This is what lets the fixes you approve be published. The plugin's own key can only read.
- Choose your Search Console site.
Back on SEOmatic, Home, a checklist shows Search Console linked, Publishing allowed and Agents on. Anything not done yet has one button that finishes it: Choose site, Allow publishing or Start trial.
Someone else holds the WordPress login? Send them a one-time link from the card that shows what SEOmatic can do on your site. See connect your website.
What Your Agents Can Change on WordPress#
| Change | Posts, pages and products | Categories and tags |
|---|---|---|
| Title and URL | Yes | Yes |
| Page text (rewrites, FAQ blocks, internal links, headings) | Yes, except pages built with Elementor, Beaver Builder, Oxygen or Bricks | Yes (the category description) |
| SEO title and meta description | Yes, through your SEO plugin (see below) | Yoast, Rank Math or AIOSEO Pro with the SEOmatic AI plugin |
| Canonical and noindex | Depends on your SEO plugin | Paste |
| Structured data (schema) | Yes, with an Administrator connection or the SEOmatic AI plugin | No |
| Image alt text | Yes, featured and gallery images | No |
| New blog posts | Yes, published live after you approve a content campaign | |
| New location or service pages | Created as drafts copied from a page you choose | |
| Redirects | One click with the SEOmatic AI plugin, once you can install it (see below). Until then, you add each redirect yourself |
Large sites are read in batches: SEOmatic lists up to 10,000 items, and a big site can take a few daily syncs to be fully listed. Until a page is listed, its fixes come as text to paste.
Your SEO Plugin Decides Where Titles and Descriptions Land
| SEO plugin | Without the SEOmatic AI plugin (today) | With the SEOmatic AI plugin (once you can install it) |
|---|---|---|
| Yoast SEO | Works on Yoast 28.1 or later, when you connected as an Administrator. Older Yoast: paste | Works, including canonical and noindex |
| Rank Math | Works on WordPress 6.9 or later. Older WordPress: paste | Works |
| All in One SEO (AIOSEO) | Works | Works |
| SEOPress | Works on posts and pages. Categories: paste | Works on posts and pages. Categories: paste |
| No SEO plugin | Paste. WordPress has nowhere to keep an SEO title | Works: the plugin prints the tags itself |
When your SEO plugin does not accept a change, the task tells you so and shows the exact box to paste into, for example the Yoast SEO box under the editor. The change is not counted as live until it shows on your page.
The SEOmatic AI Plugin
One free plugin, SEOmatic AI, lets your agents do more. It carries SEO titles, descriptions, canonical, noindex, social tags and structured data into any SEO plugin, and applies robots.txt changes. Its Redirects module, under SEOmatic > Redirects and 404s, lets you apply redirects in one click. It also has free modules that need no account, such as the 404 log, AI crawler tracking and instant indexing. You do not need it to connect. See SEOmatic AI for every module.
Settings, then Connections, shows under your WordPress connection whether SEOmatic found the plugin, whether it is out of date, and how many fixes wait on it. See the SEOmatic AI WordPress plugin for install, modules and privacy.
Not in the WordPress plugin directory yet
SEOmatic AI is submitted to the WordPress plugin directory and in review, so you cannot install it from Plugins, Add New today. Until then, fixes that need it wait. Your Agents board shows how many, for example 3 fixes are waiting on SEOmatic AI, with a Get plugin button, and they ship by themselves once it is on your site.
Page Builders
| Builder | Text on existing pages | Title, SEO title, meta description |
|---|---|---|
| Block editor or Classic editor | Yes | Yes |
| Divi, WPBakery | Yes | Yes |
| Elementor, Beaver Builder, Oxygen, Bricks | No: the builder keeps its text outside WordPress, so it comes as text to paste | Yes |
On a builder page, a text-only task stops with a message that the page is built with that builder, and Nothing was charged. A task that also changes the title or meta description applies those and gives you the text part to paste. See a change landed on the wrong page, or a page builder page was skipped.
WooCommerce#
A WooCommerce shop is a WordPress site, so connect it with the steps above. There is no separate WooCommerce row in Connections. Your agents can change product titles, descriptions, URLs, SEO titles and descriptions, product structured data and image alt text, plus product categories and tags. They never change prices, stock, SKUs, variations or orders.
Optional: give SEOmatic read-only access to exact prices and stock, so product structured data matches your shop. Only the workspace Owner sees this setting.
- In WordPress, go to WooCommerce, Settings, Advanced, REST API, then click Add key.
- Give it a description like SEOmatic, set Permissions to Read, and click Generate API key.
- Copy the Consumer key (starts with ck_) and Consumer secret (starts with cs_). WooCommerce shows the secret only once.
- In SEOmatic, open Settings, then Integrations, and click WooCommerce.
- Paste both values. Leave Store URL (optional) empty if the shop is the site this workspace works on. Click Connect.
Fix Connection Errors#
| You see | What to do |
|---|---|
| Please enter a valid domain name (e.g., example.com) | Type only the domain. Remove any path or slash at the end. |
| WordPress REST API is not accessible. Please check your permalink settings... | In WordPress, go to Settings, Permalinks, pick any option except Plain and click Save Changes. Check no plugin turns off the REST API. |
| This doesn't appear to be a WordPress site... | Check you typed the domain that runs WordPress, not a separate marketing site. |
| Connection blocked by security settings... or ...blocked by a security plugin... | Allow SEOmatic in your firewall or security plugin (Wordfence, iThemes Security, WP Cerber, your host's firewall) for /wp-json/*. See the allowlist below. |
| Site is protected by Cloudflare... | In Cloudflare, add a WAF custom rule that skips security for SEOmatic's addresses on /wp-json/*. If Bot Fight Mode is on, add an IP Access rule set to Allow. |
| This site is protected by HTTP Basic Authentication... | Despite what the message says, you do not need to turn it off. Open If your WordPress is protected with Basic Authentication, please enter your credentials here and fill it in as described below. |
| Application passwords are turned off on your site... | A security plugin or a setting usually does this. Turn them back on for your user (they also need HTTPS), then click Connect again. |
| Your web host is blocking SEOmatic's login... | WordPress created the connection, but your host removes the login before it reaches WordPress, so connecting again won't help. Send your host the note shown under the message (click Copy), then connect again. The note reads: Hi, my WordPress site example.com drops the Authorization header on REST API requests, so application passwords can't log in. Could you pass the Authorization header through to PHP for this site? Thanks. If you run your own server, add this to your .htaccess file: RewriteEngine On RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}] |
| Invalid WordPress credentials | You typed your normal login password. That box needs an Application Password, see below. |
| Unable to reach this domain... or Connection timed out... | Check the site is up and loads over HTTPS, then try again. |
| WordPress returned an unexpected response... | Turn off maintenance mode, or check a caching or security plugin is not answering instead of WordPress. |
| An error on the WordPress approval page itself | Application passwords are turned off for your user. A security plugin or a setting usually does this. Turn them back on (they also need HTTPS), then connect again. |
| This WordPress approval link expired or was not started here... | Click Add Connection again and finish within 30 minutes in the same browser. |
| You came back from WordPress and nothing happened | You probably clicked No, I do not approve of this connection. Start again and approve. |
Allowlist for firewalls: SEOmatic connects from 178.156.158.190 and 2a01:4ff:f0:ecdb::1, with the user agent SEOmatic/1.0 (+https://seomatic.app). Allow both addresses, because some hosts block only one.
The Basic Authentication Box
Use this only if your site blocks the WordPress REST API for visitors who are not logged in. It needs your WordPress username and an Application Password, not your normal password. To create one, in WordPress go to Users, Profile, scroll to Application Passwords, type a name like SEOmatic and click Add New Application Password. A site behind a server password (a host's "password protect" setting) cannot be connected this way.
- Do I need to install a plugin to connect?
- No. Connecting uses WordPress's own Application Passwords. The SEOmatic AI plugin only adds extra abilities. If you have it, you can also start from its Connect button, see starting from the plugin.
- Will my agents publish blog posts live or as drafts?
- Live. After you approve a content campaign, articles that pass the quality review are published, with categories and a featured image. New location or service pages are created as drafts.
- How do I switch to a different WordPress user?
- Log in to WordPress as that user, then click Edit on the connection card and Update. You approve again and the new user replaces the old one. Only workspace Admins and Owners see Edit.
- Test connection works, but changes fail. Why?
- A firewall may block SEOmatic's changes but not the test, or the Application Password was revoked. Read the note next to the status on the card and see fix a broken connection.
Was This Article Helpful?
Still need help?Email contact@seomatic.ai with your site address and a screenshot. A person replies, usually within one business day.