Fix Sync Failures

Sync failures in MerchantFlow occur when background jobs cannot successfully pull data from your connected platforms. MerchantFlow includes automatic retry logic and health monitoring, but some issues -- such as expired OAuth tokens or revoked permissions -- require manual intervention to resolve.

How to Diagnose a Sync Failure

1. Go to Settings > Integrations to check integration status
2. Look for red "Error" or yellow "Warning" indicators
3. Check Sync Status for the last successful sync time
4. Review integration logs for specific error messages

Common Causes and Fixes

Token Expired

Symptoms: Integration shows "Disconnected" or "Error" status.

OAuth tokens can expire if:

• The third-party platform revoked access
• You changed your password on the connected platform
• The Shopify app was uninstalled
• Token refresh failed due to a temporary API issue

Fix:

1. Go to Settings > Integrations
2. Click "Reconnect" next to the affected integration
3. Re-authorize through the OAuth flow
4. Historical data is preserved; syncing resumes automatically

Rate Limiting

Symptoms: Partial data or "rate limit" errors in logs.

Third-party APIs limit how many requests MerchantFlow can make. This is handled automatically:

• MerchantFlow automatically retries (up to 3 times)
• Retry delays start at 1 second and increase per attempt
• GA4 has specific rate limit tracking to prevent quota exhaustion

Fix: Usually resolves automatically. Avoid triggering multiple manual syncs in rapid succession.

API Errors

Symptoms: Sync starts but fails partway through.

The third-party platform returned an unexpected error.

Fix:

1. Check if the platform (Google, Shopify, Meta) has any ongoing outages
2. Wait 30 minutes and try a manual sync
3. If persistent, disconnect and reconnect the integration

Network Errors

Symptoms: All integrations failing simultaneously.

Fix: This typically resolves within minutes. If it persists, check for any service notices at merchantflow.ai.

Timeout

Symptoms: Sync initiated but never completed.

Large data sets may cause timeouts:

• Very large product catalogs (10,000+ products)
• Extensive order history on first sync

Fix: The sync will resume where it left off on the next cycle. Allow multiple cycles for large initial syncs.

Sync Schedule Reference

MerchantFlow runs a delta sync cycle approximately every 30 minutes that covers all connected integrations in a single pass. Each cycle syncs products, orders, analytics, ad spend, and Merchant Center data together.

While the sync job runs every 30 minutes, the actual data freshness depends on each provider's processing delays:

Sync Monitoring Tools

Sync Watchdog

MerchantFlow runs a background watchdog that monitors sync health. It detects:

• Syncs that have not completed within expected timeframes
• Consecutive failures that indicate a persistent problem
• Stale data that has not been refreshed

Sync Logs

View detailed sync history at Settings > Integrations > Logs:

• Start and end times for each sync
• Number of records processed
• Error messages and failure types
• Health status transitions

How to Prevent Sync Failures

1. Keep integrations connected -- do not revoke OAuth tokens on connected platforms
2. Maintain access -- ensure you retain admin access on all connected platforms
3. Monitor status -- check integration health regularly in Settings
4. Avoid manual overuse -- rate limit for manual syncs is once per hour per integration

Frequently Asked Questions

Does MerchantFlow automatically retry failed syncs?

Yes. MerchantFlow retries failed syncs up to 3 times with increasing delays. If all retries fail, the sync is marked as failed and retried during the next scheduled cycle.

Will I lose data if a sync fails?

No. Failed syncs do not delete existing data. Your previously synced data remains intact, and the next successful sync picks up where the last one left off.

How do I know which integration is causing the failure?

Check Settings > Integrations for per-integration health status. Each integration shows its current state (Connected, Error, Warning) and the last successful sync time.

Can I change the sync frequency?

The automatic sync cycle runs approximately every 30 minutes by default. You can trigger additional syncs using the Manual Sync Runner, but the automatic schedule cannot be changed.

Related Pages

• Sync Status -- Monitor sync health
• Sync Troubleshooting -- General sync issues
• Troubleshooting Integrations -- Platform-specific issues
• No Data Showing -- Empty dashboard troubleshooting
• Integration Errors -- OAuth and token fixes

---

Last updated: March 14, 2026