Shopify Onboarding — Merchant Guide

Spagify supports two ways to connect your Shopify store. Pick the one that matches how you signed up:

You signed up via…	Use this flow
Shopify App Store (found Spagify on Shopify)	Flow A — App Store install
Spagify pricing page (paid with a credit card via Stripe)	Flow B — Customer-managed custom app
Have a legacy custom app from before Jan 1, 2026	Flow C — Legacy custom app (pre-2026)

Both current flows give you the same product — identical sync, identical webhooks, identical automation. The differences are how you install and how you're billed:

• App Store install — Shopify handles both install (OAuth) and billing (charges on your Shopify invoice).
• Customer-managed custom app — you create the app in your own Shopify Dev Dashboard, install it on your store, and hand Spagify your app's Client ID and Client secret. Billed via Stripe (your credit card). Spagify uses the credentials to request short-lived Shopify access tokens on demand.

Before you start

You will need:

• Admin access to your Shopify store (Owner, or a Staff account with the Manage settings permission).
• Your .myshopify.com domain — e.g. acme-store.myshopify.com. This is the internal domain, not your customer-facing .com domain. If you're not sure what yours is: go to your Shopify admin, look at the URL bar — it's the string before /admin.
• About 5 minutes.

Flow A — App Store install

The fastest path. One-click install and Shopify handles billing.

Step 1 — Open the Spagify listing

1. Go to https://apps.shopify.com.
2. Search for Spagify.
3. Click the Spagify listing to open it.

Alternatively, if you already have a Spagify onboarding link from us, just click it — it takes you straight to step 2.

Step 2 — Click "Add app"

1. On the Spagify listing page, click the green Add app button in the top-right.
2. Shopify will ask you to log in to your store if you aren't already. Enter your .myshopify.com domain and sign in.

Step 3 — Approve the permissions

Shopify shows a permissions screen listing what Spagify needs access to:

• Read products — so we can sync your catalog.
• Read inventory — so we can flag out-of-stock items in automation.
• Read orders — so we can attribute Google Ads clicks to conversions.

Click Install app.

Step 4 — Approve billing

Shopify will show the Spagify pricing plan and ask you to approve the charge.

1. Review the plan and price.
2. Click Approve.

Charges appear on your regular Shopify invoice — no separate credit card needed.

Step 5 — Complete Spagify setup

Shopify redirects you to Spagify's onboarding wizard.

1. Confirm your name and workspace name (pre-filled from your Shopify account email).
2. Click Continue.
3. On the Connect Shopify step, you'll see a green badge that says Connected — [your-store].myshopify.com. Nothing else to do here.
4. Click Sync products and continue — your initial catalog backfill will start.
5. Continue to the Google Ads connection step.

Step 6 — Verify the sync

1. Once onboarding is complete, go to Products in the Spagify sidebar.
2. Your Shopify catalog should appear within 1–2 minutes for stores under 10,000 SKUs. Larger catalogs can take up to 10 minutes for the initial backfill.
3. Ongoing updates (new product, price change, stock change) appear in real-time via webhooks — usually within seconds.

You're done. Skip to What's next.

Flow B — Customer-managed custom app

Use this flow if you paid via Stripe. You'll create a Shopify custom app in your own Dev Dashboard, install it on your store, then hand Spagify two credentials from that app: your Client ID and Client secret. Spagify never sees a permanent Admin API token — it exchanges your credentials with Shopify for a short-lived (~24h) access token whenever it needs one, and refreshes automatically.

This takes ~10 minutes of Dev Dashboard clicks. Only the store Owner (or a staff member with app-development permissions) can complete it — Shopify collaborators cannot access the Dev Dashboard.

Step 1 — Sign in to Spagify

1. If you haven't already, go to https://www.spagify.com and sign in with the email you used to purchase.
2. You'll land on the onboarding wizard. Complete Step 0 — Your details (name + workspace name), then click Continue.
3. The Connect Shopify step lays out a summarised version of these instructions, with a copy button on every value you have to enter in Shopify (app name, scopes, App URL, webhooks API version) and quick links to your Shopify admin and the Dev Dashboard. Enter your store domain at the top first: the Shopify admin link then opens your own store rather than the account picker.
4. Leave Spagify open in one tab. Open a new tab for your Shopify admin. The step keeps whatever you have typed while you work in the other tab.

If you'd rather do this from Settings later, that's fine — go to Settings → Integrations → Shopify → Connect with Custom App. The same walkthrough opens there in a panel on the right. Clicking outside the panel will not close it, so coming back from Shopify cannot lose what you have already pasted; Cancel and the X ask before discarding it.

Step 2 — Open your Shopify admin

1. In the new tab, go to your Shopify admin — e.g. https://admin.shopify.com/store/your-store.
2. Sign in with an account that has Owner or Store settings access. Staff accounts without settings access will not see the Develop apps option.

Step 3 — Open the Dev Dashboard

1. In your Shopify admin's left sidebar, click Settings (the gear icon at the bottom).
2. In the settings menu, scroll to and click Apps. Most stores will see an "Add apps to your store" placeholder on this page.
3. In the top-right of the Apps page, click Develop apps.
4. On the App development page, in the Build and manage apps in your Dev Dashboard panel, click Build apps in Dev Dashboard. This opens the Dev Dashboard in a new page.

Step 4 — Create the app

You'll land on the Dev Dashboard's Apps page. If this is your first app, the list will be empty.

1. In the top-right of the Apps page, click Create app.
2. On the Create an app screen, use the Start from Dev Dashboard panel on the right (NOT "Start with Shopify CLI" — Spagify doesn't require the CLI toolchain).
3. Enter an App name — Spagify (or any label you'll recognize later; this is just for your reference).
4. Click Create.

You'll land directly in the Dev Dashboard for the new app, with the Versions tab auto-selected and a blank first-version config form open on the right. This is the form Step 5 configures.

The left sidebar shows Monitoring, Logs, Versions, and Settings — there is no "Overview" or "Configuration" tab in the modern Dev Dashboard.

Step 5 — Configure Admin API scopes

You'll be in the Create version form — the modern Dev Dashboard single-page layout (not the legacy Custom App admin form with separate tabs and per-scope checkboxes).

1. Find the API access panel.

2. In the Scopes field, enter this comma-separated list:

   read_products, read_inventory, read_orders, write_content

   Copy it from the Spagify panel rather than retyping it — a mistyped scope is only reported much later, by Shopify, when the credential exchange comes back missing it. Or click Select scopes to pick them from a searchable picker; the result is identical.

   • read_products — Spagify reads your product catalog to build the product list you'll automate against.
   • read_inventory — Spagify reads stock levels to skip out-of-stock products in automation rules.
   • read_orders — Spagify reads orders to attribute Google Ads clicks (via GCLID) to conversions.
   • write_content — the one write. When a product handle changes, Spagify creates a URL redirect from the old product page to the new one, so the link Merchant Center holds keeps landing on the product instead of a 404 (a 404 disapproves the offer within a day). Nothing else under this scope — pages, blogs, themes — is read or written. Without it, renamed products raise a "reconnect needed" alert.

3. Leave Optional scopes empty.

4. Leave Use legacy install flow unchecked. Spagify expects the modern install flow.

5. Do not add any other write scope. write_content in step 2 is the only write Spagify makes, and it only creates URL redirects for renamed products.

6. Do not enter read_customers or read_all_orders. These trigger Shopify's Protected Customer Data review, which delays access by weeks. Spagify does not need PII to work.

7. While you're on this form, quickly confirm the other panels are set correctly:

   • App URL — https://www.spagify.com. This is just the landing page Shopify shows if someone opens your app from the admin sidebar; Spagify never redirects through it.
   • Embed app in Shopify admin — leave unchecked. Spagify is a standalone web app, not an embedded admin app.
   • Webhooks API version — pick the latest stable version (e.g. 2026-07). This is the API version Shopify uses when it POSTs webhook payloads to Spagify.
   • Redirect URLs — leave empty (Spagify never redirects through this app).

Continue to Step 6 to release the version — do not click Release yet if any of the panels above still need adjustments.

Step 6 — Release the version

Once Step 5's form is filled in:

1. Click Release in the bottom-right of the Create version form.
2. A Release this new version? dialog opens. Both fields are optional:

   • Version name — leave blank and Shopify will auto-generate a name like spag-demo-app-1, spag-demo-app-2, etc. Only visible in the Dev Dashboard.
   • Version message — free-form changelog note for your own records.
3. Click Release in the dialog to confirm.

You'll land on the app's Overview page. The right rail now shows three panels:

• Installs — count of stores this app is installed on (currently 0) and an Install app button.
• Distribution — "Select distribution method" (used for App Store or custom-distribution links; not needed for a self-install).
• Versions — the version you just released, marked Active, with a New version button for future edits.

Step 7 — Install the app on your store

From the Overview page:

1. In the Installs card in the top-right rail, click Install app.
2. You'll be sent to a Welcome back, [your name] page listing all the Shopify accounts you own. Click the store you want to install on (e.g. spag-demo-store.myshopify.com).
3. Shopify shows an Install app screen listing the permissions the app needs. The four scopes you configured in Step 5 are grouped into permission blocks — expand each to confirm they line up with read_products, read_inventory, read_orders, and write_content.
4. Click Install in the bottom-right.

The app is now installed on your store. Shopify redirects you into your store admin, and the app appears in Settings → Apps on that store.

Step 8 — Copy your Client ID and Client secret

The Dev Dashboard shows your custom app's credentials on the Settings tab, not on the Versions or Overview tabs.

1. In the Dev Dashboard's left sidebar (under your app name), click Settings.
2. Find the Credentials panel at the top of the page.
3. Client ID — a hex string (e.g. b86780e8bfa97d4041ae304f4c80627a1). Click the copy icon next to it.
4. Client secret — starts with shpss_. Shopify displays it in full on this page; click the copy icon next to it.

Step 9 — Paste the credentials into Spagify

Switch back to the Spagify tab — the Connect Shopify step of the wizard, or the Connect with Custom App panel if you started from Settings — and fill in the fields under Paste them here, below the steps:

• Permanent Shopify domain — the field at the top of the walkthrough, above the steps, if you have not filled it in already: your .myshopify.com domain (e.g. acme-store.myshopify.com). Pasting the whole admin URL (https://admin.shopify.com/store/acme-store) is fine: the field rewrites it to the domain when you click away, as it does for a bare store handle or a domain with a protocol or path on it. A custom storefront domain (like acme.com) is not what goes here and is left alone rather than guessed at — Spagify needs the underlying myshopify.com domain, which appears in your admin URL bar.
• Client ID — paste the value from Step 8.
• Client secret — paste the value from Step 8.

Click Connect.

Spagify will:

• Exchange your Client ID + Client secret with Shopify for a short-lived Admin API access token. Tokens last ~24 hours; Spagify keeps your Client secret encrypted at rest and refreshes tokens automatically.
• Verify the store, confirm the required scopes were granted, and record the shop's permanent myshopify.com domain and GraphQL ID.
• Register webhooks so product and order changes sync in real-time.
• Start the initial product backfill in the background.

You should see a green Shopify connected notification within a few seconds. If Spagify rejects the credentials, see Troubleshooting below.

Step 10 — Verify the sync

1. Go to Products in the Spagify sidebar.
2. Your catalog appears within 1–2 minutes for stores under 10,000 SKUs.
3. In Settings → Integrations → Shopify, you should see a green Connected badge and a small blue Custom App badge.

You're done. Continue to What's next.

Flow C — Legacy custom app (pre-2026)

Only relevant if your Spagify custom app was created before January 1, 2026 in the old Shopify-admin custom-apps UI. Those apps still work with their static Admin API access token — Shopify has not disabled them, but you cannot create new ones.

Use this flow if all three are true:

• Your existing custom app in Shopify admin shows an Admin API access token starting with shpat_....
• The app has the required Spagify scopes (read_products, read_inventory, read_orders, write_content) already granted. A legacy app without write_content still connects; Spagify then cannot create URL redirects for renamed products and says so in an alert.
• You do not want to migrate to a Dev Dashboard app.

What you paste into Spagify

In the Spagify Connect with Custom App (Legacy) modal:

• Permanent Shopify domain — your .myshopify.com domain.
• Admin API access token — the shpat_... value from Settings → Apps → Develop apps → [your app] → API credentials. If it's no longer visible, Shopify will only regenerate it if you uninstall + reinstall the app, which invalidates the previous token.
• API secret key — visible on the same API credentials tab. Spagify uses it to verify incoming Shopify webhook signatures for this legacy connection (Dev Dashboard apps use their Client secret for the same purpose).

Click Connect. Everything downstream (webhook registration, product sync, verification) behaves the same as Flow B.

You're done. Continue to What's next.

What's next

• Connect Google Ads — Spagify pairs Shopify product data with Google Ads spend/conversion data. The onboarding wizard walks you through this as the next step, and the getting started guide covers it end to end, including the Merchant Center feed your Shopping campaigns serve from.
• Set up your first rule — Go to Rules → New Rule. Try starting with the "Pause zero-conversion keywords" template.
• Enable autopilot — Once you're comfortable with rules, Products → [any product] → Enable autopilot lets Spagify apply rules automatically instead of surfacing suggestions for your approval.

Troubleshooting

"Shopify credentials rejected" when clicking Connect (Flow B)

Spagify tried to exchange your Client ID + Client secret with Shopify and Shopify refused. The most common causes:

• Client ID or Client secret copied incompletely. Both are shown on the Dev Dashboard's Settings → Credentials panel. Copy each with the dedicated copy icon; do not select-and-copy manually — it's easy to miss trailing characters. The secret starts with shpss_.
• Client secret was rotated. If someone clicked Rotate in the Dev Dashboard after you copied the secret, the value you pasted is now invalid. Copy the current secret and reconnect.
• App is not installed on the store you named. Client-credentials only works when the app is actually installed on the store you passed as Permanent Shopify domain, and both belong to the same Shopify organization. Confirm the app appears in that store's admin under Settings → Apps.
• Scopes are missing. The credential exchange returns whatever scopes the current released version has. Go back to Versions in the Dev Dashboard and confirm the active version grants read_products, read_inventory, read_orders, and write_content. If you added scopes after installing, release a new version and reinstall, then click Reconnect Shopify in Spagify so it re-reads the granted scopes.
• Shop domain is wrong. Use the .myshopify.com domain (from your admin URL bar), not a custom storefront domain.

"Shopify access token validation failed" when clicking Connect (Flow C, legacy)

• Token was copied incompletely. The shpat_... token is usually 38 characters total. Copy with the copy icon, not manual selection.
• Token was revoked. If someone uninstalled the app, the token stops working. Reinstall and Shopify will show a new token once.
• Scopes are missing. Legacy tokens are scoped at install time — adding a scope requires reinstall.

"I don't see the Build apps in Dev Dashboard button"

You saw this at Step 3. Only an Owner account, or a staff member with the Manage apps and channels permission, sees this button. If you're a staff user, ask your store owner to complete Steps 3–8, or grant you the permission first. Shopify collaborators cannot open the Dev Dashboard.

The Client ID or Client secret field appears already filled

Some password managers autofill any password-style field. Delete whatever is prefilled and paste the actual value from the Dev Dashboard. Spagify does not accept credentials in the wrong format.

Products aren't appearing after 10 minutes

• Check Settings → Integrations → Shopify — is the badge still green?
• Check the Last sync timestamp on the same card. If it's stale, click Sync Products Now to trigger a manual re-sync.
• If sync repeatedly fails, your Client secret may have been rotated or the app may have been uninstalled in Shopify. Reconnect using Flow B.

I want to disconnect

App Store install (Flow A):

• To fully disconnect: uninstall Spagify from your Shopify admin (Settings → Apps and sales channels → Spagify → Uninstall). Spagify will receive the app/uninstalled webhook and clean up its side automatically.

Customer-managed custom app (Flow B):

• In Shopify: open the Dev Dashboard for your app, go to the store's Settings → Apps, click your app, and choose Uninstall. This revokes the current access token and prevents Spagify from requesting new ones — the next credential exchange will return 401 and Spagify will mark the connection disconnected.
• If you want Spagify to also delete the stored Client ID / Client secret, email support@spagify.com. There is no self-service "Remove connection" button yet — this is planned.

Legacy custom app (Flow C):

• Same idea, but the uninstall happens in Shopify admin under Settings → Apps → Develop apps → [your app] → Uninstall app. The shpat_... token is revoked immediately.

I need to change the Client secret (rotation)

If you clicked Rotate in the Dev Dashboard, the old secret is dead immediately. To reconnect Spagify:

1. Copy the new secret from Settings → Credentials in the Dev Dashboard.
2. In Spagify, go to Settings → Integrations → Shopify → Reconnect and paste the new secret (the Client ID and shop domain stay the same).

The connection is scoped by shop domain, so updating the secret in place replaces the stored value — no duplicate connection is created.

I paid via Stripe but I want to switch to App Store billing

Uninstall the Custom App in Shopify (see above). Then install Spagify from the Shopify App Store — Shopify will handle billing going forward. You'll need to cancel the Stripe subscription separately at Settings → Billing in Spagify. Email support@spagify.com and we can coordinate the switch without gaps.

Security notes

For merchants who want the details on how your Shopify credentials are handled:

• What Spagify stores.

  • Flow A (App Store): a Shopify-issued OAuth access token.
  • Flow B (Dev Dashboard): your Client ID and Client secret. Spagify never stores a permanent Admin API token — it exchanges your credentials with Shopify for a ~24h token when it needs one, and refreshes automatically.
  • Flow C (Legacy): a static shpat_... Admin API token plus the app's API secret key (used for webhook HMAC verification).
• Encryption at rest. Every secret listed above is encrypted before it hits our database using AES-256-GCM with a data key wrapped by AWS KMS. Plaintext exists only in memory during the request that stores it, and during the moment a Shopify API call is being made.
• TLS everywhere. All traffic between your browser, Spagify, and Shopify runs over TLS.
• HMAC verification uses tenant-specific secrets. Shopify signs webhook payloads with your app's Client secret (Flow B) or API secret key (Flow C), so Spagify looks up the correct per-shop secret to verify each webhook — a compromised secret from one shop cannot forge webhooks for another.
• Rate-limited connect endpoint. The connect endpoint is rate-limited to prevent brute-force testing of credentials.
• Audit logging. Every connect event is written to an audit log with actor, workspace, shop domain, and timestamp. Credentials themselves are stripped from the audit payload.
• Scope escalation. Spagify only ever calls the Shopify Admin API using scopes granted by your app's currently-released version. Adding a scope requires releasing a new version on your side — Spagify cannot silently escalate.

If you need a security review document for your compliance team, email security@spagify.com.