Connecting Shopify

Reading time: 8 minutes. Hands-on time: 10 minutes. What you'll have at the end: Your live product catalog flowing into Scarif One, with images, prices, descriptions, and inventory. Every ad and email generation is now product-aware.

This tutorial assumes you've finished 01 — Getting started and you're logged in.

Why connect Shopify

Without it, Scarif One has no idea what you sell. Every "generate an ad" prompt has to ask you for product details every time, and the AI can't pull customer data, can't check inventory before suggesting a push, and can't write product-aware emails.

With it, the AI:

• Knows every product you sell — name, description, price, photos, tags, inventory
• Can pick a product to feature in any ad/email automatically
• Auto-pauses ads for products that just went out of stock
• Writes lifecycle emails ("Welcome", "Win-back", "Subscription renewal") with the customer's actual purchase history
• Can upload generated ad images to your Shopify CDN so they're hosted on your domain, not ours

The integration takes ~5 minutes, costs nothing extra, and uses Shopify's built-in custom-app system — no third-party connectors, no scopes you don't need.

Step 1 — Open your Shopify admin

Sign in to Shopify the way you normally do:

• admin.shopify.com (the unified admin), or
• yourstore.myshopify.com/admin (per-store admin)

You should land on the dashboard with Home highlighted in the left sidebar.

Step 2 — Navigate to the custom apps area

1. Click Settings at the very bottom-left of the Shopify admin.
2. The Settings page opens. Click Apps and sales channels in the left column.
3. Click Develop apps in the top-right.

First time clicking Develop apps? Shopify will show a warning: "Apps that you build with custom app development have access to your store data. Make sure you trust the developers."

Click Allow custom app development. This unlocks the Develop apps area for all custom integrations going forward — you only do it once per store.

Step 3 — Create the custom app

1. Click Create an app (top-right).
2. App name: type Scarif One. (Customers don't see this name — it's only for you.)
3. App developer: auto-fills with your email. Leave it.
4. Click Create app.

You're now on the new app's page. It looks empty because you haven't configured any API access yet.

Step 4 — Configure the Admin API scopes

1. Click Configuration in the top tabs.
2. Find Admin API integration and click Configure.
3. Tick all six of these scopes — and only these six. Extra scopes get rejected at install time; missing scopes break the sync silently.

Don't grant write_products or write_orders. Scarif One never modifies your catalog or orders. If we ask for those scopes in a future version, ask why before approving.

1. Click Save at the bottom.

Storefront API — there's a separate section. Leave it alone. Scarif One doesn't use it.

Step 5 — Install the app to generate the token

1. Click Install app at the top of the page.
2. Shopify shows a confirmation: "Are you sure you want to install Scarif One on your store?"
3. Click Install.

Now the critical bit:

1. The next page shows the Admin API access token. It's blurred out by default with a button: Reveal token once.
2. Click Reveal token once.
3. COPY THE TOKEN IMMEDIATELY. It starts with shpat_ and is about 38 characters long. Paste it into a notes app or password manager.

You only see this token ONCE. If you close the page or lose the token, you can't reveal it again. You'd have to uninstall the app, recreate it from scratch, and re-grant the scopes. Take 5 seconds and copy it now.

Step 6 — Connect inside Scarif One

1. Open Scarif One in another tab.
2. Click 🔌 Integrations in the dashboard nav.
3. Find the Shopify card (top-left, green border).
4. Click 🔌 Connect Shopify.
5. Inline tutorial modal opens. Scroll to the bottom — you'll see two fields:

1. Click 🔍 Test connection.

Within ~5 seconds you should see a green box:

✅ Connection works Connected to Acme Coffee (GBP) First sync: Acme Coffee · 47 products · 2,341 customers

1. Click ✓ Save + connect.

The modal closes. The Shopify card now has a green ✓ Connected badge.

Step 7 — Wait 60 seconds for first sync

In the background, Scarif One is now:

• Pulling all your products via Shopify's GraphQL API
• Caching product images (URLs only — no copies leave Shopify's CDN unless you generate ad creatives later)
• Running the AI product context curator — for each product, Gemini distills the description into a structured creative brief (essence, key selling points, ideal customer, visual identity)
• Writing the result to /data/tenants/{your-slug}/product-contexts.json

This takes 30 seconds for ~10 products, up to 5 minutes for 100+ products. You don't need to wait — close the tab and come back later. The next time you open /products or /create/ad-creatives, your catalog is there.

Want to watch progress? Open /admin/scheduler (or docker compose logs -f scarif-one if self-hosted). Look for log lines like [shopify] curated 12/47.

Step 8 — Verify it worked

1. Click Products in the dashboard nav (or open /products directly).
2. You should see your full product list with thumbnails.
3. Click any product — you'll see:
   • Live data from Shopify (price, inventory, description)
   • The AI-generated creative brief below it
   • A "Generate ad with this product" button

If products are missing or the page is empty, see Troubleshooting below.

Troubleshooting

"401 Unauthorized" when testing

Token is wrong, expired, or you're using a public app token instead of an Admin API token.

Fix: Go back to Shopify → Settings → Apps and sales channels → Develop apps → your app → API credentials → click Rotate to generate a new token. Reveal it, copy it, paste it back into Scarif One. Don't forget to click Test connection again.

"403 Forbidden on /products.json"

Token works for general API but you forgot a scope (almost always read_products).

Fix: Shopify admin → your app → Configuration → Admin API integration → Configure → tick the missing scope → Save → uninstall the app → reinstall it. New token. Re-paste in Scarif One.

Yes, you have to uninstall + reinstall. Shopify doesn't let you add scopes to an installed app — security feature.

"Use the .myshopify.com domain"

You pasted your custom domain (e.g. acmecoffee.com). The Admin API only answers on the technical .myshopify.com domain.

Fix: Find your .myshopify.com domain. In Shopify admin: Settings → Domains. The technical one is usually first. Use that one.

"Invalid domain" error

Two common causes:

• Trailing slash in the domain field — strip it. (acme.myshopify.com/ → acme.myshopify.com)
• HTTPS prefix in the domain field — strip it. (https://acme.myshopify.com → acme.myshopify.com)

Test passed but my products aren't showing in Scarif One

The first-sync runs in the background and can take a few minutes. If /products is still empty after 5 minutes:

1. Click 🐛 in the bottom-right and file a bug. Include the message "Products empty after Shopify connect." We'll see your bug within seconds.
2. Or: from /integrations, find your Shopify card and click ↻ Re-test. This re-runs the test and triggers a manual re-sync.

"Cannot upload images (write_files)"

You forgot the write_files scope. This isn't a connection failure — testing passes — but ad image uploads to your store CDN will fail later.

Fix: Same as the 403 fix above — add write_files in Shopify, uninstall + reinstall, paste the new token.

What changes in Scarif One after Shopify connects

The dashboard adapts automatically:

• /create/ad-creatives — product picker now lists your real products
• /create/email — campaign drafter has a "use this product" button
• /products — the full catalog with AI-generated creative briefs per product
• /inventory — stock-aware push priorities (items low on stock get marketing priority)
• /lifecycle — customer segments now have real customers in them
• /cart-recovery — abandoned-cart detection starts running
• /analytics — once you publish ads, revenue attribution works

You don't need to "turn on" any of this — it activates the moment Shopify connects.

Disconnecting

If you ever need to disconnect (rotating tokens, switching stores, paranoid):

1. /integrations → Shopify card → Disconnect.
2. Confirm.
3. The token is removed from your tenant profile.

Your synced data is preserved — products, customer briefs, etc. stay on disk. You can reconnect later (same token or new) and pick up where you left off.

To wipe the synced data too: /security → "Delete tenant data" → tick "Shopify-derived data only". Or for self-hosted users: rm -rf data/tenants/{your-slug}/product-contexts.json.

Where to next

• Tutorial 03 — Connect Meta (Facebook + Instagram) so you can publish ads
• Tutorial 04 — Generate your first ad with full creative direction
• Tutorial 06 — Draft email campaigns with your real customer segments
• Tutorial 07 — Reviews → UGC pipeline (needs Judge.me too)