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.
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 SEO Writer plugin |
| Canonical and noindex | Depends on your SEO plugin | Paste |
| Structured data (schema) | Yes, with an Administrator connection or the SEO Writer 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 Redirects 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 SEO Writer plugin (today) | With the SEO Writer 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 SEO Writer and Redirects plugins
Two free SEOmatic plugins let your agents do more. SEOmatic: SEO Writer carries SEO titles, descriptions, canonical, noindex, social tags and structured data into any SEO plugin, and applies robots.txt changes. SEOmatic Redirects lets you apply redirects in one click. Neither is needed to connect.
Not in the WordPress plugin directory yet
Both plugins are waiting to be listed in the WordPress plugin directory, so you cannot install them from Plugins, Add New today. Until then, the fixes they carry come as text to paste. To ask about them, email contact@seomatic.ai.
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 not enabled... | A security plugin or your host turned off WordPress Application Passwords. Turn them back on (they also need HTTPS), then click Connect again. |
| 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 switched off for your user by a security plugin or your host. Turn them back on. They also need HTTPS. |
| 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 plugins only add extra abilities.
- 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.