Fix Sync Failures in MerchantFlow

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 the Audit Logs panel on the same page for specific error messages

Common Causes and Fixes

Token Expired

Symptoms: Integration shows an "Error" status with the message "Authentication expired. Please reconnect your account to continue syncing."

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 queued sync jobs, up to 5 attempts by default
• Retry delays are exponential, starting at 5 seconds and doubling per attempt
• The recurring scheduled sync uses a single bounded retry instead, because the next cycle is only 30 minutes away
• Ad platform rate limits trip a circuit breaker: the failed dates are recorded and skipped for the rest of the batch so the remaining quota is not burned, then retried on a later sync

When a rate limit is hit, the integration health message reads "API rate limit reached. Sync will automatically retry in a few minutes."

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. The health message reads "Unable to connect to the service. This may be temporary - we will retry automatically."

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.

The health message reads "Network connectivity issue. Sync will automatically retry."

Fix: This typically resolves within minutes. If it persists, contact [email protected].

Timeout

Symptoms: Sync initiated but never completed.

Large data sets may cause timeouts:

• Very large product catalogs
• Extensive order history on first sync

A run still in progress after 30 minutes is marked failed with "Sync timed out after 30 minutes" when the next sync is triggered. The health message for this failure type reads "Sync took too long and was cancelled. This may indicate a large dataset or connectivity issue."

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 single delta sync cycle every 30 minutes per workspace that covers all connected integrations in one pass. Each cycle syncs products, orders, analytics, ad spend, Search Console, and Merchant Center data together. There are no separate per-provider timers.

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 on a five-minute interval. It looks for sync leases that have expired -- the signature of a worker that crashed without releasing its lock -- and resets them so the workspace is not left permanently stuck in progress.

Sync Logs

View detailed sync history in the Audit Logs panel on Settings > Integrations:

• Start and end times for each sync
• Number of records processed and failed
• 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 -- only one sync runs per workspace at a time, so a second request while one is running is rejected with "Sync already in progress"

Frequently Asked Questions

Does MerchantFlow automatically retry failed syncs?

Yes. Queued sync jobs are retried up to 5 times with exponential backoff starting at 5 seconds. The recurring scheduled sync uses one bounded retry instead, since the next cycle runs 30 minutes later. If all retries fail, the sync is marked as failed and picked up again on 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?

No. The automatic sync cycle runs every 30 minutes and is not configurable per workspace. You can trigger additional syncs using the Manual Sync Runner.

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: August 29, 2026