# Shopify

> Push Mentionwell articles into Shopify's built-in blog so they appear at /blogs/{handle}/{article-handle}.

Shopify has a real, supported Article API under `/admin/api/{version}/blogs/{blog_id}/articles.json`. Articles created this way appear at `/blogs/{blog-handle}/{article-handle}`, exactly like ones authored in the Shopify admin.

## What you need

- A Shopify store (any plan).
- Admin access to create a custom app.

## Setup

1. Shopify admin → **Settings → Apps and sales channels → Develop apps**.
2. Click **Create an app**, name it "Mentionwell".
3. **Configure Admin API scopes**:
   - `read_content`
   - `write_content`
4. **Install app** → reveal the **Admin API access token**. Copy it (Shopify shows it once).
5. Decide which Blog the articles should land in. Most stores have a default "News" blog. To list your blogs, you can hit:
   ```
   GET https://{shop}.myshopify.com/admin/api/2024-10/blogs.json
   ```
   Or just create a new one in Shopify admin → **Online Store → Blog posts → Manage blogs**.
6. Paste the shop URL, the admin token, and the target blog ID into Mentionwell.

## What gets pushed

| Mentionwell field | Shopify Article |
|---|---|
| Title | `title` |
| Slug | `handle` (lowercase, hyphenated) |
| Excerpt | `summary_html` (shown on blog index) |
| HTML body | `body_html` |
| Featured image | `image.src` (Shopify mirrors it to its CDN) |
| Tags | comma-separated string in `tags` |
| Author | `author` (free-text) |
| Published date | `published_at` + `published: true` |
| SEO title/description | metafields `global.title_tag` / `global.description_tag` |
| JSON-LD | inline `<script type="application/ld+json">` inside `body_html` |

## Caveats

- **No real categories.** Shopify's only category-like concept is "which Blog the article lives in." If you want top-level taxonomy, create multiple Blogs (e.g. `news`, `guides`, `how-to`) and let Mentionwell choose per article.
- **Tags are flat strings.** Mentionwell joins your tags with commas before pushing.
- **Rate limits.** Shopify's leaky bucket allows ~2 requests/sec sustained on most plans (4/sec on Plus). Mentionwell's worker honours `Retry-After` and slows down automatically.
- **HTML allowed tags.** Shopify strips inline event handlers and most non-LD `<script>` tags. JSON-LD specifically is allowed; Mentionwell includes it in body_html.

## Common failures

- **401** — wrong access token, or pasted into the wrong field.
- **403** — missing `write_content` scope. Open the custom app in Shopify, add the scope, and **reinstall** (scopes don't update on existing installs).
- **422** — invalid handle (must match `[a-z0-9-]+`) or a duplicate handle in the same blog. Mentionwell auto-suffixes on retry.
- **429** — rate-limited. Mentionwell retries with the `Retry-After` value automatically.


---

Canonical URL: https://mentionwell.com/docs/publish/shopify
Live HTML version: https://mentionwell.com/docs/publish/shopify
Section: Publish to your CMS
Site index for AI ingestion: https://mentionwell.com/llms.txt
Full reference: https://mentionwell.com/llms-full.txt