What connecting Shopify does#

PilotDeck researches, drafts and queues content for review. A CMS connection is the last hop: once you approve a draft, PilotDeck sends it to your store for you. The example below uses a PilotDeck site named pilotdeck-testwebsite.

Nothing to paste

You enter your store domain and approve the PilotDeck app on Shopify's own install screen. PilotDeck receives its access from Shopify, so you never copy a token.

Articles in your blog

Each approved draft becomes a blog article in the blog you pick, with its SEO title, description, tags and featured image.

Drafts first

The default publish mode is Draft only. Articles arrive hidden, so nothing goes live until you publish it in Shopify.

Before you start#

You need	Details
A Shopify store	Any store works, including a free development store from a Shopify Partners account. You need your store's permanent address, which is your store name followed by `.myshopify.com`.
Permission to install apps	A Shopify login that is allowed to install apps on the store.
At least one blog	Articles are created inside an existing blog. A new store usually ships with a default blog called "News". If you deleted it, create a blog under Online Store > Blog posts first.
A PilotDeck login	Permission to change integrations for the site. Without it the connect controls are unavailable.

No custom app token. Shopify no longer lets merchants create the older custom app tokens, so the install approval is the only way to connect. PilotDeck asks for two permissions: write_content and read_content.

Overview#

1Open Settings > Integrations in PilotDeck and pick ShopifyYou
2Enter your store domain and click Authenticate with ShopifyYou
3Review the permissions and install the app on Shopify's screenYou
4Return to PilotDeck. It saves the connection and lists your blogsPilotDeck
5Choose a blog, optionally add a category, and confirmYou
6Send a test draft and check it in ShopifyVerify

Open Integrations in PilotDeck#

You

In PilotDeck, make sure the correct site is selected in the top-left site switcher (here, pilotdeck-testwebsite). Go to Settings > Integrations and find the CMS Connection card, then choose Shopify.

A site can have one CMS connection at a time. If another CMS is already connected, disconnect it first, then pick Shopify.

Shopify connect panel in PilotDeck with a Store domain field and Authenticate with Shopify button — The Connect Shopify panel: a Store domain field and the Authenticate with Shopify button.

Enter your store domain#

You

The panel reads Connect Shopify. Type your store address into Store domain, for example your-store.myshopify.com. The field is required.

Connect Shopify panel with a placeholder store domain entered — Store domain filled in. The address is a placeholder in this screenshot.

Click Authenticate with Shopify. Your browser leaves PilotDeck and opens Shopify.

Use the permanent myshopify.com address, not a custom domain. If you type only the store name, PilotDeck adds .myshopify.com for you, and it ignores a leading https:// or any trailing path.

Approve the app on Shopify#

You

If you are not signed in, Shopify first shows its own login page. Sign in with the account that can install apps on the store.

Shopify login with a placeholder email and a masked password — Shopify's login. The email is a placeholder and the password shows dots.

Shopify shows its install screen for the PilotDeck app, listing what it needs access to: store owner and blog contributor data (read) and Online Store content (read and write). Review it and click Install.

Shopify Install app screen listing the permissions the PilotDeck app needs — Shopify's install screen. The store and organisation names are masked in this screenshot.

Shopify then sends you back to PilotDeck. PilotDeck checks the signature on that return, saves the connection for pilotdeck-testwebsite and starts it in Draft only mode.

Access does not expire. Shopify gives PilotDeck a long-lived access token. If you uninstall the app from the store later, the connection flips to a needs reauth state with the message "App was uninstalled from the Shopify store".

Choose a blog and confirm#

You

Back in PilotDeck, a Finish setup card appears. PilotDeck lists up to 50 blogs from your store.

PilotDeck Finish setup card with a Choose a blog list, an optional category and a Confirm button — The Finish setup card. Open **Choose a blog** to see your blogs. A new store has one, called News.

Open the Choose a blog list and select the blog that should receive articles.
Optionally fill in Category. Shopify articles have tags rather than categories, so PilotDeck adds this value to each article's tags.
Click Confirm.

If you skip this step, PilotDeck publishes into the first blog it finds in the store. Choosing a blog makes the destination explicit.

The CMS Connection card now shows your store domain with an active badge, the publish mode selector, Send test draft, Send test live and Disconnect.

Shopify connected and ACTIVE in PilotDeck — Connected. The card shows the store address, ACTIVE, the publish mode, an optional category, the test buttons and Disconnect.

Verify with a test article#

Verify

Click Send test draft. PilotDeck creates a sample article in your chosen blog and reports "Test draft created." In Shopify, open Content > Blog posts and find it. Its visibility is Hidden.

Shopify card after Send test draft showing Test draft created — The card after Send test draft.

Shopify Blog posts list showing the PilotDeck sample article as Hidden in the News blog — The sample article under Content > Blog posts: hidden, in the News blog, with the author PilotDeck sent. The banner about restricted store access is normal on a development store.

Send test live publishes the sample article for real. Use it only on a store where that is fine, and delete the test article in Shopify afterwards.

Development stores. A development store is password protected, so the public article address is not openly reachable. That is expected and not a failed publish. Check the article inside the Shopify admin instead.

Done. Approved content for this site now goes to your Shopify blog in the mode you chose.

Publish modes and what gets created#

Mode	What happens	When to use it
Draft only (default)	Articles are created in the blog as hidden. You make them visible in Shopify when ready.	While you learn the flow, or when someone reviews on the Shopify side.
Publish live	Articles are created visible and appear on your store blog.	Once you trust the output and your review step happens in PilotDeck.

Change the mode from the selector on the connected card. PilotDeck asks you to confirm every switch, because the two modes behave differently once content has been sent.

Each article carries these fields:

Title, body, handle (the URL slug) and summary from the draft's meta description.
Tags, including your optional category.
Featured image, when the draft has one. If Shopify rejects the image, the article is still created without it.
SEO title and description, stored in Shopify's standard page title and description fields.
FAQ and article structured data (JSON-LD) written into the article body, plus an author name and an author box when the draft has an author. The author name defaults to "PilotDeck" when none is set.

If the handle is already taken in that blog, PilotDeck retries with a numeric suffix, up to a few times, instead of failing.

This is separate from PilotDeck's site publish mode (clone, CMS or copy) and from draft handling (review or auto). A site set to the CMS publish mode with no connected CMS is not ready to publish. Check that the Shopify card shows active.

For administrators: register the Shopify app#

Only the person who runs the PilotDeck server does this, once. Everyone else uses the steps above. PilotDeck connects through a Shopify app that you register in the Shopify Dev Dashboard, and the server needs that app's client ID and secret.

Keep the client secret private. Put it in the server environment only. Never paste it into chat, tickets, screenshots or a repository.

Create a Shopify Partners account and an organisation, or use one you already have. Shopify may ask you to verify your email address first.
In the Dev Dashboard open Stores > Create store, choose Dev, name it, pick a plan and tick Generate test data. A development store is free and is the safest place to try the connection.
Open Apps > Create app. Set the name, add your PilotDeck API's callback address under Allowed redirection URL(s), and set Scopes to write_content,read_content. Click Create app, then Release.
Open the app's Settings page. Under Credentials, copy the Client ID and the Client secret.
Set SHOPIFY_OAUTH_CLIENT_ID, SHOPIFY_OAUTH_CLIENT_SECRET and SHOPIFY_SCOPES (the two scopes above) in the PilotDeck server environment, together with the redirect base the callback uses, then restart the server.

Shopify Create store dialog with Dev selected — Create store with the Dev type: a free store for testing.

Shopify Dev Dashboard Create an app form with a redirect URL and scopes filled in — Create an app. The redirect address is a placeholder here. Use your own PilotDeck API address followed by `/api/connectors/oauth/shopify/callback`.

Shopify app Settings page with the Client ID and Client secret masked — The app's Credentials. Both values are masked in this screenshot.

If the server is missing these values, PilotDeck shows a store domain and access token form instead of the Authenticate with Shopify button. See Troubleshooting.

Disconnecting#

On the connected card click Disconnect and confirm. Approved content stops publishing to your store right away. This cannot be undone, but you can reconnect by repeating steps 1 to 4. To fully remove access, also uninstall the PilotDeck app in your Shopify admin under Settings > Apps and sales channels.

Troubleshooting#

I see "OAuth isn't configured on this server"

The Shopify install is not enabled on the PilotDeck server you are using, so PilotDeck falls back to showing store domain and access token fields instead. Contact your PilotDeck administrator rather than creating a token yourself.

"Connection was cancelled. Please try again."

You clicked Cancel on Shopify's install screen, so nothing was saved. Click Authenticate with Shopify again and approve the install.

I am sent back with a failure message

PilotDeck rejects a return whose signature does not check out ("Shopify HMAC verification failed"), or one where Shopify gave no access token. Start again from step 2 and complete the install in one go without refreshing the return page.

"No blog found in this store"

The store has no blog. Create one under Online Store > Blog posts, then send the test draft again. If you want a specific blog, reconnect and choose it in Choose a blog.

The blog list is empty during Finish setup

Your store returned no blogs. Create a blog in Shopify and reconnect.

Test draft fails with an authorization error

Shopify rejected the saved access, often because the app was uninstalled or its permissions changed. Disconnect, then connect again and approve the install.

The card shows needs reauth

The PilotDeck app was removed from the store. Install it again with Authenticate with Shopify. The connection keeps your earlier blog choice.

The article address shows a password page

That is a development store. Its public pages are password protected, so the link is not openly reachable. The article still exists in your Shopify admin.

The article has no featured image

Shopify can refuse an image it cannot fetch. PilotDeck then creates the article without the image rather than blocking the publish. Add the image in Shopify.