Shopify troubleshooting

The Shopify publish flow

Shopify blog publishing uses the Admin API, not the Storefront API. The custom app you create in Shopify Admin holds the access token, scoped to your blog and content surfaces.

"401 Invalid token"

• The custom app was uninstalled from your store. Re-install at Settings → Apps and sales channels → Develop apps.
• The token was rotated. Tokens never expire, but they CAN be rotated manually. If you rotated, re-paste in Settings → Integrations → Shopify.
• The store handle in the integration is wrong. Use the yourstore.myshopify.com URL exactly — not your custom domain.

"403 Access denied"

Your custom app is missing a required scope. We need:

• write_content — to create blog posts.
• read_content — to verify the blog and list existing posts.

Edit the custom app in Shopify, request the scope, and re-install the app on your store. The token after re-install includes the new scope.

"404 Blog not found"

The blog ID is wrong. Common mistakes:

• Using the blog handle (slug) instead of the numeric ID. The ID is the number in /admin/blogs/{ID}.
• Using a blog ID from a different store than the connected one.
• The blog was deleted on the Shopify side.

Fix: open the blog in Shopify Admin, copy the numeric ID from the URL, and update Settings → Integrations → Shopify.

Draft vs. published state

Shopify blog posts have a published boolean. We default to published: true on publish. To publish as draft (so a human reviews in Shopify before the post goes live), toggle Settings → Integrations → Shopify → Publish as draft.

When publishing as draft, the publish dialog warns you that the post won't be live on your storefront until you flip the toggle inside Shopify.

Featured image missing

Shopify blog post images go through a different upload flow than product images. We:

1. Upload the image as a temporary file.
2. Reference the temporary URL in the blog post body.
3. Shopify ingests the image during post creation and rehosts on their CDN.

If the image URL we generate is unreachable from Shopify's server during step 3, the image is dropped silently. Re-publish to retry.

Tags and categorisation

Shopify blog tags are comma-separated strings on the post body. We map:

• Markdown frontmatter tags: [a, b, c] → a, b, c in Shopify.

Shopify doesn't have categories on blog posts (the way WordPress does). If you need category-like grouping, use multiple blogs and pick the right blog at publish time.

HTML body quirks

The engine emits clean HTML. Shopify's blog editor inserts non-standard whitespace and <span> wrappers when humans edit. If you've hand-edited a published post in Shopify, our subsequent updates may produce a visual jolt because we restore clean HTML.

We don't currently overwrite existing posts (publish always creates new), so this only matters if you migrate to update-in-place when we ship it.

Author field

Shopify blog posts have an Author field. We default to the connected user's name. Override per-publish in the publish dialog.

If you want all posts to ship as a specific author regardless of who clicked publish, set the default in Settings → Integrations → Shopify → Default author.

SEO fields

Shopify exposes page_title, meta_description, and url_handle as SEO fields. We populate all three from your draft frontmatter. If your post is for a non-default locale, the SEO field language follows your Shopify store's settings.

Rate limits

Shopify Admin API rate-limits at 2 calls/second per store (or 4/sec on Shopify Plus). Our publish flow uses 2 calls per post — create + image upload — so a backlog of 10 posts publishes in roughly 10 seconds. Large bulk publishes self-throttle.