Installation Guide

Setup takes a few minutes: install the Shopify app, install the WordPress plugin, then connect the two with a one-time connect code.

Prerequisites

Before you begin, ensure you have:

• Shopify store on any Shopify plan
• WordPress site (version 6.3 or higher)
• PHP 8.0 or higher on your WordPress server
• Admin access to both platforms

Step 1: Install the Shopify app

1.1 Access the Shopify App Store

1. Log in to your Shopify admin panel
2. Navigate to Apps in the sidebar
3. Click Shopify App Store
4. Search for "Wash: Blog Manager"

1.2 Install the app

1. Click on Wash: Blog Manager in the search results
2. Click the Add app button
3. Review the permissions and click Install app
4. You'll be redirected to the Wash: Blog Manager dashboard

1.3 Complete initial setup

1. Choose your subscription plan (you can start with Free)
2. The app will create necessary metafield definitions automatically
3. On the dashboard, the Set up Wash checklist walks you through the rest. Under Add your WordPress site address, enter your site's address and click Check site. Wash tells you whether it found WordPress and the Wash Connector there

You don't need to copy any key. WordPress gets one from the connect code in step 3.

Step 2: Install the Wash Connector in WordPress

The Wash Connector is a WordPress plugin. It runs on your WordPress web server. Nothing is installed on your computer. Get the latest version here: wash-blog-manager.zip (no account needed). Version, release date and changes: latest release on GitHub.

Option A: Upload via WordPress admin

1. Download wash-blog-manager.zip
2. Log in to your WordPress admin panel
3. Go to Plugins → Add New
4. Click Upload Plugin
5. Select the ZIP file and click Install Now
6. Click Activate Plugin

Option B: Manual installation (FTP)

1. Download wash-blog-manager.zip and extract it
2. Upload the wash-blog-manager folder to /wp-content/plugins/
3. Log in to WordPress admin
4. Go to Plugins → Installed Plugins
5. Find Wash Connector and click Activate

Option C: WP-CLI

WP-CLI installs and activates it straight from the release:

wp plugin install https://github.com/tradik/wp-wash/releases/latest/download/wash-blog-manager.zip --activate

Step 3: Connect WordPress to Shopify

3.1 Access plugin settings

1. In WordPress admin, go to Settings → Wash Connector
2. You'll see the connection setup page

3.2 Get a connect code in Shopify

1. In your Shopify admin, open Apps > Wash. Once the checklist has found the Wash Connector, click Generate connect code under Connect WordPress to this store. You can also go to Connections, click Add Connection, then Generate connect code
2. Copy the code (for example ABCD-EFGH-JKMN). It works once and expires after 15 minutes.

3.3 Paste the code in WordPress

1. Back in Settings → Wash Connector, tick the data processing consent box
2. Paste the code into Connect code
3. Click Connect to Shopify

You don't type your store's address anywhere: the code tells the plugin which store to connect.

3.4 Verify connection

After connecting, you should see:

• Connected toyour-store.myshopify.com
• A Disconnect button

In Shopify, the connection card under Apps > Wash > Connections now shows the WordPress URL. Click Test next to it to check Wash can reach your site.

Step 4: Configure blog mappings

4.1 Understand blog mappings

Blog mappings decide which Shopify blog each WordPress post goes to, by category, language or both. On the Free plan there are no mappings: posts go to the first blog in your Shopify store, so you can skip this step. Mappings come with the Pro plan and above.

4.2 Create your first mapping

1. Go to Settings → Wash Connector and open the Blogs tab
2. Click Add Mapping Rule
3. Under WordPress Source, pick a Category (e.g., "News")
4. Under Shopify Destination, pick the Target Blog (e.g., "News")
5. Click Save Mapping

4.3 Multiple mappings

You can create multiple rules:

WordPress Category	Shopify Blog
News	News
Tutorials	Guides
All categories (catch-all)	Journal

Once you have any rules, posts that match none of them don't sync. Keep a catch-all rule at the bottom if every post should go somewhere. Blog Mappings explains the order rules are matched in.

Step 5: Test your first sync

5.1 Create a test post

1. In WordPress, go to Posts → Add New
2. Write a simple test post
3. Assign it to a mapped category
4. Click Publish

5.2 Verify sync

1. Check the Shopify column in Posts → All Posts. It shows the sync status and links to the article
2. Visit your Shopify blog to see the published post
3. Verify images and formatting transferred correctly

Step 6: Configure additional settings

6.1 Sync options

Open the Sync Settings tab under Settings → Wash Connector to configure:

• Auto-sync on Publish: sync posts when they are published or updated
• Sync Metafields: send core and plugin meta fields to Shopify metafields
• Rewrite Internal URLs: turn internal WordPress links into Shopify URLs
• Post Types: which post types sync to Shopify

6.2 Other tabs

• Authors: map WordPress authors to Shopify (Pro and above)
• Meta Fields: sync custom fields (Pro and above)
• Redirections: smart redirections from old WordPress URLs (Business and above)
• Files & Media: image and file handling

Troubleshooting

Connection failed

• Generate a new connect code if yours was used or is more than 15 minutes old
• Check that your Shopify app is installed and active
• Ensure your WordPress site can make outbound HTTPS requests

Sync not working

• Confirm the post is assigned to a mapped category
• If the post shows No mapping, add a blog-mapping rule that matches it
• Check the sync logs in Shopify under Apps > Wash > Logs (see screenshot below)
• Verify your subscription plan allows more syncs

Sync icon keeps spinning

If the sync icon keeps spinning indefinitely after publishing a post, it usually means the callback from Shopify is being blocked. Common causes:

Cloudflare protection

If your WordPress site uses Cloudflare with Bot Fight Mode or Under Attack Mode enabled, server-to-server callbacks may be blocked.

Fix: add a WAF exception rule

1. Log in to your Cloudflare dashboard
2. Go to Security → WAF → Custom Rules
3. Create a new rule with these settings:
   • Rule name: Allow Wash Callbacks
   • Expression: (http.request.uri.path contains "/wp-json/wash/v1/callback")
   • Action: Skip (select "All remaining custom rules")
4. Deploy the rule

Security plugins

WordPress security plugins like Wordfence, Sucuri, or iThemes Security may block API requests.

Solution:

1. Go to your security plugin settings
2. Add /wp-json/wash/v1/callback to the whitelist/allowlist
3. For Wordfence: Firewall → Blocking → Whitelisted URLs
4. For Sucuri: Settings → Hardening → Whitelist

Testing callback endpoint

To verify your callback endpoint is accessible, run this test:

curl -X POST "https://your-wordpress-site.com/wp-json/wash/v1/callback" \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

If you see a Cloudflare challenge page or 403 error, the endpoint is being blocked.

Images not appearing

• Check that images are properly attached to the post
• Verify your Shopify plan supports file uploads
• Review image size limits in settings

Next steps

• Connection Settings
• Set up author mapping
• Enable smart redirections
• Choose the right plan for your needs

Need help?

If you encounter any issues during installation:

1. Check our FAQ section
2. Review the Shopify limitations
3. Contact support through the Shopify app dashboard