Skip to main content
Shopify integration issues mostly fall into two buckets: connection problems (OAuth, domain validation, scopes) and sync problems (stuck entities, missing data, failed retries). This page works through both.

​
Connection issues

​
OAuth fails during install

Symptoms. Connection fails after redirecting to Shopify, or you land back in Spotzee without a success message.

​
Domain validation errors

These show up in the Connect Shopify store drawer before you reach Shopify.

​
”Already connected to another project”

A single Shopify store can only connect to one Spotzee project at a time. If you see this:
  1. Find which project currently has the store connected.
  2. Disconnect the store from that project first.
  3. Then connect it to the new project.

​
Reconnect required (amber badge)

The integration’s status is Reconnect required. Common causes:
  • The Spotzee app was uninstalled and reinstalled in Shopify.
  • Shopify revoked the app’s access tokens.
  • Required scopes changed (you turned on a sync-back toggle that needs a scope you didn’t grant initially) and need re-approval.
Fix. Open the store card menu and choose Reconnect. Re-approve permissions on Shopify. Sync settings, customer list, and history are preserved.

​
Sync issues

​
Sync stuck or taking too long

Symptoms. An entity shows Syncing for longer than expected. Possible causes.
  • Large dataset (thousands of products, tens of thousands of orders).
  • Shopify API responding slowly or hitting rate limits.
  • Network issues between Spotzee and Shopify.
What to do.
  1. Close and re-open the sync settings drawer to refresh the displayed status.
  2. Wait 15 minutes. Large initial imports take time.
  3. If still stuck, run a Re-sync from the same drawer. It restarts the bulk import.

​
Individual entity shows Failed

Symptoms. One entity (say, Orders) shows Failed while the others are Synced.
1

Run Retry

Pick Retry next to the failed entity in sync settings.
2

If it fails again, run a health check

Use Check health from the store card menu. A health-check failure points at the underlying cause (OAuth, scopes, API).
3

If health checks pass, run a full Re-sync

A persistent per-entity failure with passing health checks usually clears with a full re-sync.

​
Missing data after sync

Symptoms. Sync completed successfully but expected data isn’t in Spotzee. Check these.
  1. Sync toggles: open sync settings and confirm the right category is enabled. Orders missing? Verify Orders, checkouts, and carts is on.
  2. Customer list: a customer list must be assigned for customer profiles to land somewhere.
  3. Data exists in Shopify: confirm the records are actually in your Shopify admin. Spotzee can only sync what’s there.
  4. Recent changes: data added after the initial sync should arrive via webhooks within seconds. If something specific isn’t there, run a Re-sync to catch up.

​
Customers not appearing in the list

Symptoms. Sync status is Synced for Customers but the assigned list is empty or missing people. Check.
  1. Is Customer profiles toggle on in sync settings?
  2. Is a customer list assigned in the dropdown?
  3. Did the initial Customer sync actually complete? Check the per-entity status.
  4. Are customers actually in your Shopify admin? Confirm in Shopify.

​
Health check failed

The store card shows Error status and the readiness checklist has one or more failed items. After fixing, run Check health again to confirm.

​
Webhooks aren’t firing

Symptoms. Initial sync was fine, but new orders or customers aren’t appearing in Spotzee. Check.
  • The integration’s status badge. Disconnected or Reconnect required stops webhook delivery. Reconnect.
  • The OAuth scopes still grant the webhook subscriptions Spotzee installed. Reconnect if scopes changed.
  • The webhook delivery logs in Shopify (Settings → Notifications → Webhooks). Failed deliveries show retry status there.
If Shopify shows successful webhook delivery but Spotzee doesn’t reflect the data, run a manual re-sync to reconcile.

​
Still stuck

If you’ve worked through the patterns above and the integration still won’t behave:
  • Read the most recent failure detail in the Store details drawer.
  • Try Reconnect to refresh OAuth credentials.
  • Pause the integration via Disconnect to stop retry storms while you investigate, then reconnect once the underlying cause is fixed.
  • For data-corruption-style issues, Delete and start fresh. Note that delete is irreversible; see Disconnect, delete, reconnect.

​
Next steps

Sync operations

Statuses, retries, and the re-sync flow.

Store details

The five-item readiness checklist.

Disconnect, delete, reconnect

The three actions and what each does to your data.

Connect a store

The OAuth flow used by reconnect.