Images and Files
When Wash syncs a post, it uploads the post's images to Shopify Files and points the article at the Shopify CDN copies. Other file types, such as PDFs, can come along too.
How image sync works
flowchart TD
A[WordPress Media Library] --> B[Find images in the post]
B --> C[Convert to WebP, if enabled]
C --> D[Upload to Shopify Files]
D --> E[Rewrite URLs in the content]
| Image | Synced | Notes |
|---|---|---|
| Featured image | Yes | Becomes the Shopify article image |
| Images in the content | Yes | URLs are rewritten to the Shopify CDN |
| Galleries | Yes | Each image is uploaded |
| Background images in CSS | No | Upload them to Shopify by hand |
| Images hosted elsewhere | No | They keep their external URL |
Each image is uploaded once. Later syncs reuse the Shopify copy, unless you replace the image in WordPress: then the new file is uploaded and the article updated.
Settings
Go to Settings > Wash Connector and open the Files & Media tab.
| Setting | Default | What it does |
|---|---|---|
| Upload Images | On | Uploads images to Shopify Files. Turn it off to leave images on WordPress |
| Convert to WebP | Off | Converts images to WebP before uploading. If a conversion fails, the original format is kept |
| Allowed File Types | Images | Which kinds of file are uploaded |
The file types you can allow:
| Type | Formats | Size limit |
|---|---|---|
| Images | JPEG, PNG, GIF, WebP, SVG | 20 MB each |
| PDF Documents | ||
| Videos | MP4, MOV, WebM | 1 GB each |
| Audio | MP3, WAV, OGG | |
| Documents | DOC, XLS, PPT, TXT |
Shopify sets the storage and size limits, and they depend on your Shopify plan. Files over the limit are skipped.
WebP conversion
WebP files are typically 25 to 35% smaller than JPEGs at the same quality, and every current browser shows them. Wash converts JPEG, PNG, GIF and TIFF images at quality 85. It doesn't resize images, so upload them at the size you need.
URLs in the content
Image URLs in the post are rewritten to the Shopify CDN:
<!-- WordPress -->
<img src="https://yourblog.com/wp-content/uploads/2026/01/hero-image.jpg" alt="Hero" />
<!-- Shopify -->
<img src="https://cdn.shopify.com/s/files/1/0123/4567/8901/files/hero-image.jpg" alt="Hero" />
Alt text, loading="lazy" and <figure> captions are kept as they are. WordPress's srcset and sizes attributes are removed, because those point at WordPress image sizes. If your theme needs responsive images, build them from the article image with Shopify's image_url filter:
<img
src="{{ article.image | image_url: width: 800 }}"
srcset="
{{ article.image | image_url: width: 400 }} 400w,
{{ article.image | image_url: width: 800 }} 800w,
{{ article.image | image_url: width: 1200 }} 1200w
"
alt="{{ article.image.alt | escape }}"
/>
Featured image
The featured image becomes the Shopify article image:
{{ article.image | image_url: width: 800 }}
If it shows in the Shopify admin but not on the blog, your theme's article template doesn't output it. The Files & Media tab has a FAQ entry with the code to add.
Syncing media by hand
Images sync on their own when you publish a post. You can also sync them from the Media Library (in list view):
- The Shopify Sync column shows whether each image is on the Shopify CDN. Click the icon of a synced image to open the CDN copy
- Hover over an image and click Sync to Shopify, or Re-sync to Shopify if it's there already
- Select several images and choose Sync to Shopify from Bulk actions
- On an image's edit screen, use the Sync to Shopify button
If you sync images by hand, sync the post again afterwards so its content points at the new URLs.
Troubleshooting
Image not uploading
- Check Upload Images is on and the file type is allowed
- Check the file is under the size limit
- Look for errors under Apps > Wash > Logs in Shopify
Images in the content still point at WordPress
- Check the image is in the Media Library and shows as synced
- Sync it with Sync to Shopify, then sync the post again
- In WordPress's
debug.log, lines starting with[wash]show what happened
Image quality looks worse
Turn off Convert to WebP and sync the post again.
Best practices
- Optimize images before you upload them to WordPress.
- Use descriptive filenames and alt text, for SEO and accessibility.
- Size images for how they're shown. A 6000px upload for an 800px slot wastes bandwidth.
- Delete images you no longer use to keep Shopify Files tidy.