Skip to main content

Connect your Shopify store to Clione

Plans: Starter ✓ · Growth ✓ · Pro ✓ · Agency ✓

Time required: ~5–10 minutes (including the theme-app-extension step).

You need: access to your Shopify admin as store owner OR as a staff member with permission to develop apps. The "Develop apps" capability is off by default for staff accounts — if you don't see the menu in Step 1.4 below, ask the owner to enable it under Settings → Users → permissions before continuing.

This is the end-to-end guide to giving Clione the access it needs to read your Shopify catalog, enrich it, propagate the results, and render Clione JSON-LD on the storefront. It is intentionally written for non-technical merchants — every UI path is spelled out exactly as it appears in Shopify admin, every field name is the one you'll actually see, and every scope is explained.

Clione never sees customer data, orders, payment information, fulfillment data, inventory, locations, draft orders, gift cards, or any PII. The scopes below grant access only to your product catalog, content pages, metafields, and theme files.

If you're connecting BigCommerce instead, see Connect BigCommerce.

Why a Custom App and not the public app?​

Clione does not currently submit a public Shopify App to the Shopify App Store, so the connection happens via a Custom App that you create inside your own store. This has three concrete advantages over a public-app OAuth flow:

  • Instant. No app-review backlog, no approval queue. The connection is live the second you click "Install app".
  • Scoped narrowly. A public app would request the union of every scope any merchant might need. The Custom App you create here requests only the scopes Clione actually uses — see Step 3.
  • Revocable from your admin in one click. Uninstalling the Custom App immediately invalidates the access token. You don't need to wait for Clione to remove anything.

The trade-off is one extra setup step (creating the app). The rest of this guide is that step, spelled out.

Step 1 — Open the Custom Apps page​

  1. Log in to your Shopify admin: https://<your-store>.myshopify.com/admin.
  2. From the bottom-left of the sidebar, click Settings.
  3. In the Settings sidebar, click Apps and sales channels.
  4. In the top right, click Develop apps.
    • If you've never used this before, Shopify shows an interstitial: "Allow custom app development". Click it and confirm with Allow custom app development in the modal. This unlocks the page; you'll only see this once per store.
    • (screenshot: Shopify admin → Settings → Apps and sales channels → Develop apps → Allow custom app development banner)
  5. Click Create an app at the top right.

If Develop apps is missing from the page, your user does not have the Custom App Development capability. The store owner can enable it under Settings → Users → [your name] → Permissions → Develop apps.

Step 2 — Name the app​

In the Create app dialog:

FieldValue
App nameClione AI (any name works; this label is shown in your admin and in your API request logs, so make it recognizable).
App developerLeave at the default (your user).

Click Create app. You land on the app's detail screen, which has tabs Overview, Configuration, and API credentials.

Step 3 — Configure Admin API scopes​

In the app's screen, you'll see a card titled Admin API integration. Click Configure Admin API scopes inside it.

A long list of scopes appears, grouped by resource. Tick the ones below — leave everything else unchecked. The scope checker is search-friendly: type a scope name into the Filter box to jump to it.

Required scopes​

ScopeWhy Clione needs it
read_productsRead your products, variants, options, vendors, product types, and tags. Required for sync and enrichment.
write_productsWrite the enriched metafields.global.title_tag, metafields.global.description_tag, and the Clione metafield namespace (clione.jsonld, clione.faq). Required for propagation.
read_contentRead your content pages (About, Contact, Shipping, etc. — not blog posts).
write_contentUpdate the metafields on those pages so the enriched meta_title and meta_description propagate.
read_themesDetect which themes are installed and whether the Clione JSON-LD theme app embed is enabled. The dashboard uses this for the Schema Injector status card.
write_themesRequired only if Clione should be able to install / uninstall the theme app embed for you in the future. Without it the embed has to be enabled manually in the theme editor (Step 6). Safe to grant — Clione will not modify your theme files.
read_online_store_pagesRead storefront URLs and handles so Clione targets the correct URL when verifying.
read_localesRead the store's primary language and any additional languages so enriched content is generated in the right locale.

Storefront API scopes​

You can leave the entire Storefront API integration card untouched. Clione does not use the Storefront API today.

Webhooks (optional)​

In Configuration → Webhooks, you can optionally subscribe to products/update, products/delete, collections/update, collections/delete, and pages/update so that Clione's catalog mirror stays in sync without a manual re-sync. This is not required to connect — you can always trigger a sync manually from the dashboard. If you want to wire it up later, see Webhooks for developers.

Scopes you must NOT enable​

Granting these would expose data Clione never reads. Leave them at None:

  • read_customers, write_customers, read_customer_addresses
  • read_orders, write_orders, read_draft_orders, read_order_edits
  • read_fulfillments, write_fulfillments
  • read_inventory, write_inventory, read_locations
  • read_discounts, write_discounts, read_price_rules, read_gift_cards
  • read_shipping, read_checkouts, read_payment_methods
  • read_reports, read_analytics, read_marketing_events

Click Save at the top right. You'll see a brief banner confirming the scopes are updated.

Step 4 — Install the app and capture the credentials​

Switch to the API credentials tab at the top of the app screen.

  1. Click Install app in the top right.
  2. Shopify shows a confirmation listing the scopes you just configured. Click Install to grant them.
  3. The page reloads showing Access tokens. Under Admin API access token, click Reveal token once.
  4. A shpat_... token appears. Copy it now — Shopify will never show it again. If you close the modal without copying, you have to Uninstall app and Install app again to mint a new one.

You'll also see (further down the page):

  • API key — public identifier for the app.
  • API secret key — used only if you switch to OAuth flow later. Not needed for the Custom App connection.

Optional: paste the token into a password manager (1Password, Bitwarden) for safekeeping. Treat it as you would your Shopify admin password — anyone with the token can call the Admin API against your store with the scopes you granted.

Step 5 — Add the store in the Clione dashboard​

  1. Log in to your Clione dashboard at app.clione.ai.
  2. From the left sidebar, click + Add Store (or open /stores/new directly). The 3-step wizard opens.
  3. Step 1 — Pick the platform: click the Shopify card.
  4. Step 2 — Store details:
    • Store name — anything that helps you tell stores apart in the sidebar (e.g. EgoShoes EU, EgoShoes US). This is internal only.
    • Shopify store URL — your myshopify.com domain. You can paste either the short name (egoshoes-eu) or the full domain (egoshoes-eu.myshopify.com); Clione normalises both. Do not include https:// or any path.
    • Currency — the same currency your Shopify store uses. This populates priceCurrency in JSON-LD until Clione reads multi-currency from Shopify Markets (planned).
  5. Click Next.
  6. Step 3 — Credentials: paste the Admin API access token (shpat_...) from Step 4 into the Shopify Admin API access token field.
  7. Click Create and Connect.

Within seconds the store appears in your dashboard sidebar. Open it to see the store overview. The Schema Injector card will show Theme App Extension status (rather than the BigCommerce Scripts API status — these differ; see Schema Injector).

If you skip Step 6 the catalog will sync fine and the enriched values land in metafields, but no JSON-LD will ever appear on your storefront, because the metafield is not rendered until the theme embed is on.

Step 6 — Enable the Clione theme app embed (required for JSON-LD)​

Shopify metafields are API-only by default — the storefront does not auto-render them. Clione writes JSON-LD into the clione.jsonld metafield, but the storefront only renders it if the Clione JSON-LD theme app embed is enabled in your live theme.

Without this step, your enriched JSON-LD is invisible to Google, Bing, ChatGPT, Perplexity, and every other crawler. The metafield exists. The crawlers don't see it.

The block lives at apps/shopify-theme-extension/blocks/clione-jsonld.liquid in the Clione source and is shipped together with the Custom App you installed in Step 4. Enabling it is a one-click operation in the theme editor:

  1. Shopify admin → Online Store (in the left sidebar) → Themes.
  2. Find your live theme (the one labelled Current theme) → click Customize.
  3. In the theme editor, click the puzzle icon (App embeds) in the left rail. (screenshot: Shopify theme editor left rail, App embeds tab open)
  4. Find Clione JSON-LD in the list. Toggle it on.
  5. Click Save in the top right.

The block targets <head>, so the JSON-LD is rendered server-side by Liquid on every page request. There is no JavaScript involved and crawlers see it on the very first request, including curl-style crawlers that do not run JS.

What the block renders​

The block is plain Liquid (no scripts) and renders:

  • Per-page entity JSON-LD — read from product.metafields.clione.jsonld, collection.metafields.clione.jsonld, or page.metafields.clione.jsonld depending on the page type.
  • Global Organization JSON-LD — read from shop.metafields.clione.organization. Rendered on every page.
  • Global WebSite JSON-LD — read from shop.metafields.clione.website. Rendered on every page, includes a SearchAction pointing at Shopify's /search?q= URL template.

If the entity metafield is empty (because the entity hasn't been enriched yet) the block emits nothing for that entity — no empty script tag, no broken markup. Once you enrich the entity in Clione the metafield is populated and the block starts rendering on the next page request.

Re-enabling after a theme swap​

App embeds are stored per theme, not per store. If you swap to a new theme, duplicate your current theme, or work in a development theme, you must enable Clione JSON-LD on each one separately. The same applies after a third-party theme update that resets app embeds — re-open the theme editor and toggle it on again.

What does NOT require the theme embed​

SignalNeeds theme embed?
<title> (meta_title)No — Shopify natively renders global.title_tag via theme.liquid's {{ page_title }}.
<meta name="description">No — same; uses global.description_tag.
<link rel="canonical">No — Shopify generates this from the product's canonical URL.
Product / Collection / Page JSON-LDYes.
FAQPage JSON-LDOptional — the FAQ widget injects FAQPage JSON-LD client-side; if you want server-rendered FAQ schema instead, use the theme embed flow plus the FAQ Liquid snippet documented in FAQ widget install — Shopify.
OG tagsPartial — Shopify renders default OG title/description from global.title_tag / global.description_tag. Clione-specific OG fields ride alongside JSON-LD in the same metafield namespace and require the embed.

Sanity check (optional)​

If you want to verify the token works before clicking Create and Connect, run this in any terminal (replace the two placeholders with your real values):

curl -s \
  -H "X-Shopify-Access-Token: shpat_..." \
  "https://<your-store>.myshopify.com/admin/api/2024-10/products.json?limit=1"

Expected: a JSON response with one of your products. If you see {"errors":"[API] Invalid API key or access token (unrecognized login or wrong password)"}, the token was copied wrong — re-reveal and copy again, no leading or trailing whitespace.

Troubleshooting (Shopify-specific)​

401 Unauthorized from Clione — The access token was revoked (someone uninstalled the Custom App), or copied with whitespace, or it's the wrong app's token. Re-open the Clione AI Custom App → API credentials tab → click Install app to mint a fresh token, then paste it under Store → Settings → Credentials in the Clione dashboard.

403 Forbidden only when Clione writes metafields — A write_* scope is missing. Open the app → Configuration → Admin API scopes → tick the missing write_* scope (most often write_products) → Save → return to API credentials → Install app again to grant the additional scope. Existing tokens do not automatically pick up newly added scopes — you must re-install.

Theme app embed not visible in App embeds — The most common cause is that the theme was installed (or last edited) before the Custom App was installed. Re-install the Custom App: Settings → Apps and sales channels → Develop apps → Clione AI → API credentials → Uninstall app, then Install app again. Reload the theme editor — Clione JSON-LD should now appear under App embeds.

JSON-LD doesn't appear in the page source after enabling the embed — Three possible causes:

  1. The product has not been enriched yet. Open it in Clione → check the Enrichment tab → enrich. Only enriched entities have non-empty clione.jsonld metafields, and the Liquid block emits nothing for empty metafields (intentional — better to be silent than to render <script type="application/ld+json"></script>).
  2. You're looking at a different theme. Shopify renders the live theme by default but a ?preview_theme_id=... URL renders a different one. Make sure the embed is enabled on the Current theme, not just on a duplicate.
  3. The metafield was written but the storefront is serving from a CDN cache. Hard refresh (Ctrl/Cmd + Shift + R). Cache TTL for myshopify.com is ~60 seconds; custom domains depend on your DNS/CDN.

Meta description shows truncated to 255 characters on the storefront — Known platform limit. Shopify's single_line_text_field metafield type caps at 255 chars; Clione may generate up to 320. The dashboard shows a warning when this happens and truncates at a sentence boundary. To get the full 320-char description, use the headless API mode with @clione/seo and skip the metafield mirror — see Headless on Hydrogen.

429 Too Many Requests during sync — Shopify's GraphQL Admin API rate-limits via "cost", not requests-per-second. Clione automatically retries with cost-aware backoff, so a 5,000-product catalog can take 5–10 minutes to sync. The progress chip in the top bar updates live; you can leave the page and come back.

Sync says "shop not found" — The store URL in Store → Settings → General doesn't match the myshopify.com domain that the token was issued for. Re-check the Shopify store URL field — it should be your-store.myshopify.com, not your custom domain.

Revoking access​

If you need to revoke Clione's access:

  1. Shopify admin → Settings → Apps and sales channels → Develop apps.
  2. Open the Clione AI app.
  3. Click Uninstall app in the API credentials tab.
  4. Confirm.

Within seconds, every Clione request to your store returns 401 and your store stops appearing as healthy in the Clione dashboard. No data is deleted on either side — you can re-install the app any time to mint a fresh token and resume.

If you also want to delete the store from Clione (and remove the enriched data we have), use the Danger zone → Schedule deletion in Store → Settings in the Clione dashboard. See Store settings for the 7-day grace window.

What's different on Shopify vs BigCommerce​

Common questions from merchants connecting their second platform:

AspectShopifyBigCommerce
Token typeOne single shpat_ Admin API access token.Access Token + Store Hash from a V2/V3 API Account.
Where the token is createdCustom App inside the store's admin (Settings → Apps and sales channels → Develop apps).API Accounts page (Settings → API Accounts → Create API Account).
JSON-LD on the storefrontTheme App Embed (server-side Liquid).Schema Injector (BC Scripts API → <script src=...> in <head>).
Variant modelFirst-class: each variant is a separate SKU with its own price/option values.Product Options + generated SKU; variants are derived from options.
Category equivalentCollections — both manual (you pick products) and smart (rule-based).Categories — tree-structured with parent IDs.
Multi-currencyShopify Markets (one product, prices per market). Clione reads default currency today; Markets-aware enrichment is planned.BC Channels (one product, prices per channel). Same status.
Native reviewsRemoved in 2023 — you need Judge.me / Yotpo / Loox / Stamped to populate reviews.* metafields.Native Customer Reviews under Settings → Channels.
Meta description max length255 chars (metafield type limit).65535 chars (no practical limit).
Sync speed (per 1k entities)60–120s (GraphQL cost-based rate limit).30–60s (REST v3).

See Platform capabilities for the full per-signal matrix.

What happens after Clione has the token​

  1. First sync (1–10 minutes depending on catalog size). Clione pulls your products, collections, and pages. Watch progress in the top-bar chip or under Sync in the store sidebar.
  2. First enrichment (depends on your plan quota). From any listing page (Products, Collections, Pages), select up to 5 entities and click Bulk enrich. Clione always asks for confirmation before spending enrichment credits — there is no auto-enrich on sync. See Enrich your catalog.
  3. Auto-propagation. As soon as the enrichment completes, signals are pushed to the storefront in the background. You don't click anything for this.
  4. Verification. Open Verification in the store sidebar to confirm that what's in Clione matches what's on the live storefront. See Verify signals.

If a write fails (e.g. the metafield type is wrong, a description exceeds 255 chars, the theme embed is off and JSON-LD is invisible), the Verification page will surface a yellow Warn or red Fail with the exact diff. Every write is logged with before/after values under each entity's Propagation tab.