Troubleshooting Integrations — MerchantFlow

Troubleshooting MerchantFlow Integrations

This guide covers common integration issues and how to fix them when a connection will not start, fails during OAuth, or begins showing stale data. Use these platform-specific checks to diagnose and resolve problems quickly. For sync-specific issues after a successful connection, see Sync Troubleshooting.

Google Services Issues

Search Console or Merchant Center Is Missing Entirely

If the Search Console or Merchant Center row does not appear on the Google card at all -- not greyed out, just absent -- the service is turned off for your workspace. Both sit behind per-workspace feature flags while their data pipelines are stabilized, and both ship off by default. Reconnecting Google will not bring them back; contact MerchantFlow support to have the flag enabled. See Search Console and Merchant Center.

No Properties or Sites Appear in Configure Google Services

• Reconnect with the correct Google account -- the connected Google user must have access to the properties you expect to see
• Confirm the account can access the GA4 property, Search Console site, or Merchant Center account
• If you recently changed Google account permissions, reconnect Google from Settings > Integrations

Google Ads Shows "Coming Soon"

This means your MerchantFlow environment does not hold a Google Ads developer token, so the Google Ads API cannot be reached. GA4 can still be connected and used normally, as can Search Console and Merchant Center where those are enabled for your workspace.

Shopify Issues

OAuth Will Not Start

• Confirm the store domain is a valid .myshopify.com address
• Make sure you are an admin on the Shopify store
• Confirm your MerchantFlow account has a verified email, and 2FA enabled if you sign in with an email and password (Security Settings). Social-only sign-ins are not asked for 2FA

Reinstalling Asks You to Upgrade to Plus

If you reinstall MerchantFlow on a store you already had connected and are told to upgrade to Plus to add this store, do not upgrade. Reconnecting your own store is not adding a second one, and a one-store plan covers it.

This means the link between your store and your workspace needs repairing. Contact [email protected] with your store domain and we will relink it, with your history intact and no change to your plan.

Shopify and WooCommerce Conflict

MerchantFlow allows one primary commerce platform per merchant tenant. Connecting WooCommerce to a workspace that already has Shopify is rejected with Disconnect Shopify before connecting WooCommerce. Disconnect the existing platform from Settings > Integrations before connecting the new one. See Shopify or WooCommerce for platform-specific instructions.

WooCommerce Issues

API Credentials Fail

• Confirm the store URL is correct, reachable, and uses HTTPS
• Confirm the consumer key and consumer secret are valid
• Confirm the API key has read access permissions
• Regenerate credentials in WooCommerce > Settings > Advanced > REST API if needed

See WooCommerce Integration for full setup instructions.

Meta, Snapchat, TikTok, or Pinterest Issues

OAuth Was Cancelled or Interrupted

Restart the connection from Settings > Integrations. MerchantFlow does not save a partial connection if the provider flow is cancelled. You must complete the full OAuth flow for the connection to activate.

No Ad Accounts Appear After OAuth

• Confirm your advertising platform login has ad account access (check Meta Business Manager, Snapchat Ads Manager, TikTok Ads Manager, or Pinterest Business)
• Confirm the MerchantFlow environment has the platform enabled (some platforms are environment-gated)
• Reconnect the platform after fixing provider-side account access

One Ad Account Is Broken but the Others Look Fine

Meta, Snapchat, TikTok, and Pinterest each hold several ad accounts per workspace, and the card rolls up with error precedence -- one broken account marks the whole platform as unhealthy, because total spend is no longer complete. Expand the card, find the account showing the error, and reconnect or pause just that one. Pausing keeps its history and stops it syncing.

Pinterest Ads Shows "Coming Soon"

Pinterest Ads is behind the pinterest_ads_enabled flag while the Pinterest app awaits Standard API access, and it is off by default. An admin enables it per workspace. Until then the card is not connectable and MerchantFlow reports Pinterest as absent everywhere downstream.

Speedfulfill Reconnection Prompts

If Speedfulfill shows Reconnection required. SpeedFulfill upgraded its API - please reconnect with your new credentials. -- the integration card words the same condition as Reconnect required - SpeedFulfill upgraded its API. Please reconnect with your new API key and secret. -- or SpeedFulfill credentials expired. Please reconnect with your current API key and secret., your stored credentials predate SpeedFulfill's API change or have expired. Open the Speedfulfill modal in Settings > Integrations and save your current API key and API secret from the SpeedFulfill merchant backend (Settings > App API). See Speedfulfill.

Stale-Data Warnings

MerchantFlow watches every connected integration for stale data: a connection that authenticates successfully but has stopped producing new syncs. Each integration carries a health status of healthy, warning, error, or unknown, and staleness is measured from its last successful sync:

The notification fires only when the integration first crosses into the error state, so a long-running problem does not generate a fresh alert on every health poll.

Common triggers:

• The integration token was silently revoked on the provider side (Meta and Snapchat both expire tokens periodically without warning the connected app)
• The ad account was moved to a different parent account
• The Shopify or WooCommerce store entered maintenance mode
• A configured property or account was deleted in the provider

What Does Not Count as Stale

MerchantFlow deliberately skips these rather than raising a false alert:

• Paused ad accounts. Pausing an account is a choice you made, so it stops receiving sync watermarks without being flagged
• Flag-gated services. Search Console and Merchant Center are not synced while their workspace flags are off, so their frozen timestamps are ignored
• Connected but unconfigured Google services. If you authorized Google but never picked a GA4 property, Search Console site, Merchant Center account, or Google Ads customer, that service has nothing to sync

Health Messages You May See

When a sync fails outright, the card shows a specific message rather than a staleness warning:

• Authentication expired. Please reconnect your account to continue syncing. -- reconnect from Settings > Integrations
• API rate limit reached. Sync will automatically retry in a few minutes. -- no action needed
• No data was returned from the API. Check if your account has active data. -- check the provider for paused campaigns or empty date ranges
• Integration setup incomplete. Please complete the connection in Settings. -- finish the configuration step
• Unable to connect to the service. / Network connectivity issue. -- both retry automatically

How to Resolve a Stale Warning

1. Open the affected integration from Settings > Integrations
2. If the message points at expired authentication, click Reconnect and walk through OAuth again
3. Otherwise check the provider for paused accounts or empty date ranges, then trigger a manual sync

The warning clears automatically on the next successful sync.

General Troubleshooting Steps

If none of the above fixes apply:

1. Check that your MerchantFlow account meets the OAuth prerequisites -- verified email, and 2FA if you sign in with an email and password
2. Try disconnecting and reconnecting the integration from Settings > Integrations
3. Run a targeted manual sync from Settings > Integrations > Manual Sync Runner
4. Review Sync Troubleshooting if the connection is live but data looks wrong
5. Check Sync Status for error messages or failed sync indicators

Frequently Asked Questions

What is a "stale data" notification and what should I do?

MerchantFlow tags an integration as stale when it has not synced successfully for over 24 hours -- a warning at that point, and an error past 72 hours. Reconnect the integration from Settings > Integrations to refresh credentials. If reconnecting does not resolve it, the data gap is usually on the provider side (deleted property, store maintenance, an ad account with no activity in the window).

Why does my integration keep disconnecting?

Integration disconnections usually happen when provider-side credentials expire or are revoked. For OAuth connections (Google, Shopify, Meta, TikTok, Snapchat, Pinterest, Klaviyo), re-authorize from Settings > Integrations. For WooCommerce and the fulfillment providers, regenerate and re-enter your API credentials.

How do I know if my integration is connected and working?

Check Settings > Integrations for connection status indicators. A successfully connected integration shows an active status. You can also verify by checking Sync Status for recent successful syncs.

Can I reconnect an integration without losing historical data?

Yes. MerchantFlow retains your historical data when an integration is disconnected. Reconnecting resumes syncing from where it left off.

Related Guides

• Integrations Overview -- all supported integrations
• Shopify -- Shopify connection guide
• WooCommerce -- WooCommerce connection guide
• Sync Status -- monitor sync health
• Sync Troubleshooting -- fix sync-specific issues
• Manual Sync -- trigger syncs on demand

---

Last updated: August 29, 2026