Shopify — Ranket Docs

Ranket connects to your Shopify store and publishes generated articles directly into a blog of your choice. Each article ships with title, handle (slug), HTML body, summary, target-keyword tags, and SEO title/description metafields. Updates and deletes propagate the same way once an article has been delivered once.

Setup with one click (recommended)

In your brand settings → Webhooks, click Add destination → Shopify.
Type your store domain (e.g. acme.myshopify.com) and click Connect with Shopify.
Shopify opens a permission screen showing the scopes Ranket needs (write_content to publish articles, read_content to list blogs). Click Install app.
After install, pick which blog Ranket should publish into.
Done — articles auto-publish to that blog.

Note: We’re approved on the Shopify App Store, so the install flow shows the Ranket logo and a public-app trust badge. If you see a “this app is not approved” warning, your Ranket instance is running on a partner-mode dev key — contact support.

Setup with a Custom App token (alternative)

What you need before you start

A Shopify store on any plan that exposes the Admin API (Basic and above). The myshopify domain (my-shop.myshopify.com) is required even if you have a custom domain — the API only accepts the permanent shop domain.
Permission to install a custom app on the store. This typically means the store owner or a staff account with the Develop apps permission enabled (Settings → Users and permissions → Permissions → Apps and channels → “Develop apps”).
At least one existing Blog in the store (Online Store → Blog posts → Manage blogs). A default News blog ships with every store; you’ll need its numeric ID.

Step-by-step setup

In Shopify admin, go to Settings → Apps and sales channels → Develop apps. If this is your first custom app, click Allow custom app development and confirm.
Click Create an app, name it Ranket, and click Create app.
On the app’s page, click Configuration → Admin API integration → Configure.
Under Admin API access scopes, enable write_content and read_content. Save.
Go to the API credentials tab and click Install app at the top, then Install to confirm.
Copy the Admin API access token (starts with shpat_). Shopify shows it once — store it safely.
Find your target blog’s ID. The fastest way: visit https://<your-shop>.myshopify.com/admin/api/2024-10/blogs.json while logged into the admin, or use the Admin API Explorer. Copy the numeric id (e.g. 123456789).
In Ranket, open your brand → Webhooks tab → Add endpoint and pick Shopify.
Fill in your Shop Domain (the *.myshopify.com form), the Access Token (shpat_…), the Blog ID, and optionally adjust API Version and Publish Immediately.
Click Test connection before saving — Ranket hits /admin/api/<version>/blogs/<blogId>.json to confirm the token works and the blog exists.

Configuration options

Field	Required	Default	What it does
`shopDomain`	yes	—	Permanent shop domain in the form `<store>.myshopify.com`. Must match the regex; custom domains are not accepted here.
`accessToken`	yes	—	Admin API access token from your Custom App. Must start with `shpat_`.
`blogId`	yes	—	Numeric ID of the blog the article will be posted to.
`apiVersion`	no	`2024-10`	Shopify Admin API version. Bump when newer stable versions ship.
`publishImmediately`	no	`true`	When `true`, articles are created with `published: true` and go live immediately. Set `false` to land them as drafts.

What gets sent

Each article.published event creates an article via POST /admin/api/<version>/blogs/<blogId>/articles.json with:

title, handle (from the slug), body_html, summary_html (wrapped excerpt), tags (target keyword), author (your brand name).
published flag from publishImmediately.
SEO metafields under the global namespace: title_tag (meta title) and description_tag (meta description) — these are the keys Shopify themes read for <title> and <meta name="description">.

Image URLs and JSON-LD schema are present in the original webhook payload; Shopify themes typically render the hero image inline from body_html and don’t need separate upload.

Updates and deletes

When Ranket optimizes an article, the same endpoint receives an article.updated event and the post is updated in place via PUT /admin/api/<version>/blogs/<blogId>/articles/<id>.json. Deletions fire article.deleted and remove the article via DELETE.

Troubleshooting

401 Unauthorized — the access token is wrong, was rotated, or the Custom App was uninstalled. Reinstall and copy the new token.
403 Forbidden / “scope not granted” — the app is missing write_content. Re-open the app’s configuration, enable the scope, and reinstall (Shopify requires a reinstall after scope changes).
404 on the blog ID — the blog was deleted or the ID is wrong. List blogs again at /admin/api/<version>/blogs.json and update the config.
422 Unprocessable Entity — usually a duplicate handle. Shopify enforces unique handles per blog; let Ranket regenerate the slug or delete the older article first.
429 Too Many Requests — you hit Shopify’s leaky-bucket rate limit. Ranket retries automatically with backoff; no action needed.