Troubleshooting Facebook Ads Integration

Having issues with your Facebook Ads integration? This comprehensive troubleshooting guide covers common problems and their solutions. All information has been verified against the actual Alpha Insights codebase.

Connection Issues

"Connection Failed" Error

Symptoms: Can't complete initial connection, error message appears

Common causes & solutions:

1. Browser Popup Blocked

Solution:

1. Look for popup blocker icon in browser address bar
2. Click it and select "Always allow popups from this site"
3. Try connecting again

2. Incorrect Facebook Login

Solution:

1. Make sure you're logging in with the Facebook account that manages your ads
2. Verify you have admin access to the ad account
3. If unsure, check Facebook Business Manager to confirm access

3. Outdated Browser

Solution:

• Update your browser to the latest version
• Try a different browser (Chrome, Firefox, Safari, Edge all supported)
• Clear browser cache and cookies

4. Third-Party Cookie Blocking

Solution:

1. Temporarily disable browser privacy extensions (uBlock, Privacy Badger, etc.)
2. Try in private/incognito mode
3. Whitelist both your WordPress site and facebook.com

"Token Expired" or "Reconnect Required"

Cause: Facebook API tokens expire after 60-90 days for security

Solution:

1. Go to Settings → Facebook Integration
2. Click Reconnect
3. Log in to Facebook again
4. Grant permissions
5. Connection restored

Prevention: This is normal and happens to everyone. Just reconnect when prompted.

"Permission Denied"

Cause: Your Facebook account doesn't have sufficient access to the ad account

Solution:

1. Go to Facebook Business Manager
2. Check your role for the ad account
3. You need "Admin" or "Advertiser" role at minimum
4. If you don't have access, ask the account owner to grant it
5. Wait 5 minutes after being granted access, then try connecting again

"No Ad Accounts Found"

Cause: The Facebook account you're logged in with has no associated ad accounts

Solution:

• Verify you logged in with correct Facebook account
• If you have multiple Facebook accounts, log out completely and try with the right one
• Check Facebook Business Manager to see which account has access
• If someone else manages your ads, have them connect the integration

Sync Issues

Data Not Syncing

Symptoms: Last sync time is hours/days ago, no new data appearing

Diagnostic steps:

1. Go to Settings → Facebook Integration
2. Check connection status - should be "Connected" (green)
3. Check last sync time
4. Click View Sync Logs to see error messages

If Status Shows "Error"

Solution:

1. Click Reconnect
2. Complete authentication again

If Status Shows "Connected" But Not Syncing

Solution:

1. Click Sync Now to force immediate sync
2. If that fails, check sync logs for specific error messages
3. Verify your WordPress site can make outbound HTTPS connections (ask your host)

If Sync Logs Show "Rate Limit Exceeded"

Cause: Hit Facebook API rate limits

Facebook's Limits: The Marketing API has rate limits to prevent abuse. If you're syncing very frequently or have many campaigns, you may hit these limits.

Solution:

• Change API Call Schedule from "Every 6 Hours" to "Every 12 Hours" or "Daily" in Settings → Facebook Integration
• Wait an hour for rate limit to reset automatically
• Reduce number of campaigns if you have 100+ active campaigns (archive old campaigns in Facebook)
• Check the "Request Timeout" and "Number Of Results To Collect Per Call" settings - lower values may help

Partial Data Syncing

Symptoms: Some campaigns sync but others don't

Causes & solutions:

1. Campaign Status Filtering

Check: Settings → Facebook Integration → Campaign Filters

By default, only active and paused campaigns sync. If you want ended campaigns too:

1. Enable "Include ended campaigns"
2. Save settings
3. Sync Now

2. Campaign Date Range

Check: Campaign start dates

If you set historical import to "Last 30 days" but campaign ran 60 days ago, it won't be imported.

Solution:

1. Increase historical import range
2. Re-sync

Slow Syncing

Symptoms: Syncs take 10+ minutes, timeout errors

Causes & solutions:

1. Too Many Campaigns

If you have 100+ campaigns:

• Sync takes longer (normal)
• Consider archiving old ended campaigns in Facebook
• Or filter to only sync active campaigns

2. Large Date Range

Importing "All time" for account with years of data:

• Can take 30-60 minutes (normal)
• Let it complete in background
• Once done, ongoing syncs will be fast

3. Slow Server

Shared hosting with limited resources:

• Contact host about enabling background processing
• Or switch to "Daily" sync frequency

Data Accuracy Issues

Ad Spend Doesn't Match Facebook

Common reasons and solutions:

1. Currency Mismatch

Check:

1. Settings → Facebook Integration → Currency
2. Verify it matches your Facebook ad account currency
3. If you changed it, re-sync to recalculate

2. Time Zone Difference

Issue: Alpha Insights uses your WordPress timezone, Facebook might use different one

Solution:

• Small discrepancies (1-5%) are normal due to timezone boundaries
• For exact matching, set WordPress timezone to match Facebook account timezone

3. Sync Delay

Issue: Facebook data not fully available yet (they process in batches)

Solution:

• Wait 2-3 hours after spending for Facebook to finalize numbers
• Click Sync Now to get latest data
• Check again tomorrow - data should match once Facebook finalizes it

4. Different Date Ranges

Check: You're comparing same dates in both Alpha Insights and Facebook

• Alpha Insights: "Last 30 days" might mean different dates than Facebook's "Last 30 days" depending on when page loaded
• Use specific date ranges (Jan 1 - Jan 31) for accurate comparison

ROAS Doesn't Match Facebook

This is expected! Here's why:

Facebook ROAS includes:

• View-through conversions (saw ad but didn't click)
• 1-day click, 7-day view attribution by default
• Modeled conversions (Facebook's estimates)

Alpha Insights ROAS includes:

• Only confirmed orders in your WooCommerce store
• Click-based attribution (more conservative)
• Actual revenue (no modeling)

Result: Alpha Insights ROAS is typically 20-40% lower than Facebook's reported ROAS, but it's more accurate for actual profitability.

Recommendation: Use Alpha Insights numbers for business decisions - they reflect true profit, not Facebook's optimistic estimates.

Missing Orders/Revenue

Symptoms: You know orders came from Facebook but they're not showing in campaign revenue

Causes & solutions:

1. Missing UTM Parameters

Issue: Your Facebook ads don't have UTM parameters in the URL

Solution:

1. In Facebook Ads Manager, edit your ads

2. 			?utm_source=facebook&utm_medium=cpc&utm_campaign=YOUR_CAMPAIGN_NAME
   		

3. Future orders will be properly attributed

2. Attribution Window Missed

Issue: Customer clicked ad but ordered outside attribution window

Example:7-day attribution window, but customer clicked ad and ordered 10 days later

Solution:

• Increase attribution window to 14 or 28 days
• Or accept that some conversions aren't immediately attributed (this is normal for higher-consideration products)

3. Traffic Source Not Detected

Issue: Customer came from Facebook but referrer was lost

Causes:

• Customer went through redirect service
• Customer bookmarked product page after first visit
• Customer entered site through different page

Solution:

• Always use UTM parameters (most reliable)
• Enable first-touch attribution in addition to last-touch

4. Orders Before Integration

Issue: Historical orders before you connected Facebook Ads

Solution:

• Alpha Insights can only attribute orders that occurred after connection
• Historical attribution is not possible (Facebook doesn't provide retroactive visitor data)

Campaign Issues

Campaign Names Don't Match

Issue: Campaign names in Alpha Insights differ from Facebook Ads Manager

Causes:

• Facebook API returns campaign IDs, names are fetched separately
• You renamed campaign in Facebook after initial sync

Solution:

1. Click Sync Now to refresh campaign names
2. If still wrong, disconnect and reconnect integration

Deleted Campaign Still Showing

Cause: Alpha Insights keeps historical data even if campaign is deleted in Facebook

This is intentional! You want historical profit data for deleted campaigns.

If you really want to hide it:

1. Go to Facebook Campaigns list
2. Filter to show only Active campaigns

Duplicate Campaigns

Cause: Campaign was disconnected and reconnected, or imported twice

Solution:

1. Go to Facebook Campaigns
2. Identify duplicate (usually has "(2)" in name)
3. Click Delete on duplicate
4. Original campaign data is preserved

API and Technical Issues

"API Rate Limit Exceeded"

Cause: Too many requests to Facebook API in short time

Facebook's Rate Limits: Facebook Marketing API has rate limits that vary by ad account size and usage. Limits are automatically managed by Facebook and reset hourly.

When this happens in Alpha Insights:

• You're making too many API calls in a short period
• You have many campaigns (50+) and frequent sync schedule
• Multiple WordPress sites connected to the same ad account

Solutions:

1. Change API Call Schedule to "Every 12 Hours" or "Daily" in Settings → Facebook Integration
2. Lower the "Number Of Results To Collect Per Call" setting (default 50, try 25)
3. Increase "Request Timeout" if you're getting timeouts (default 5 seconds, try 10-15)
4. If you have multiple WordPress sites: stagger their sync schedules so they don't all sync at once
5. Wait 1 hour for rate limit to reset automatically
6. Archive old/ended campaigns in Facebook to reduce data volume

"API Error: Unknown Error"

Cause: Temporary Facebook API issue

Solution:

• Wait 15-30 minutes and try again
• Check Facebook API Status Page for outages
• If persists longer than 2 hours, contact support

"Invalid Access Token"

Cause: Token expired or was revoked

Solution:

1. Click Reconnect
2. Complete authentication again

Data Management and Cleanup Tools

Delete All Facebook Data

If you need to start fresh or remove all Facebook integration data:

Location: Settings → Facebook Integration → API Tools → Facebook Data Deletion

Two deletion tools available:

1. Delete All Expense Data:
   • Removes all daily ad spend entries stored as expenses
   • These are the expense posts with reference "Facebook API"
   • Does not affect your Facebook ad account
   • Safe to use if you want to re-import expense data
2. Delete All Campaign Data:
   • Removes all campaign posts (custom post type: facebook_campaign)
   • Deletes all campaign metrics, daily data, and historical information
   • Does not affect your Facebook ad account
   • Use if you want to completely reset and re-import campaigns

When to use:

• Data appears corrupted or inaccurate
• You want to switch to a different ad account
• You're troubleshooting sync issues
• You've made changes in Facebook and want clean import

After deletion: Click "Refresh All Campaign Data" to re-import everything from Facebook

Note: These deletions only affect your WordPress database. Your actual Facebook ad account and data in Facebook Ads Manager are completely unaffected.

Getting Help

Before Contacting Support

Gather this information:

1. Screenshot of the error message
2. Connection status from Settings → Facebook Integration (API Status, Connection Expiry Date, Last API Check)
3. Recent sync log entries (visible at bottom of Facebook Integration settings page)
4. Facebook Ad Account ID and name
5. When the issue started
6. How many campaigns you have
7. Your API Call Schedule setting

Check the Facebook API Log

Alpha Insights maintains a detailed log of all Facebook API interactions:

Location: Settings → Facebook Integration → scroll to bottom → Facebook API Log

What you'll see:

• API request attempts and responses
• Error messages from Facebook
• Success confirmations
• Token validation attempts
• Data sync operations

Using the log: Look for error messages, failed requests, or patterns that coincide with when your issues occur

Contact Support

Open a support ticket with:

• Clear description of the issue
• Steps you've already tried from this troubleshooting guide
• Screenshots of error messages and settings
• Excerpt from Facebook API Log showing errors
• Your API Status information
• Number of campaigns you're tracking

Prevention Tips and Best Practices

Maintain Connection Health

• Token expiration: Facebook access tokens extend to 60 days automatically when validated. Check "Connection Expiry Date" in settings monthly
• Reconnect when needed: If you see "Token Expired" status, use the "Reconnect Facebook" button
• Monitor API Status: Check that API Status shows "Healthy" with green indicator

Optimize Sync Settings

• Choose appropriate schedule: "Every 6 Hours" is recommended for most users - balances data freshness with API usage
• Adjust for scale: If you have 50+ campaigns, consider "Every 12 Hours" or "Daily" to avoid rate limits
• Monitor sync completion: Check "Last Successful Data Fetch" regularly

Use Tracking Parameters

• Always use meta_cid: Add meta_cid={{campaign.id}} to all Facebook ad URLs for accurate order attribution
• Test your tracking: Manually visit an ad URL and place a test order to verify tracking works
• Check order meta: Verify _wpd_ai_meta_campaign_id is being stored on orders

Keep Software Updated

• WordPress core: Keep WordPress updated for security and compatibility
• Alpha Insights: Update when new versions are released (check for updates regularly)
• WooCommerce: Keep WooCommerce updated for best compatibility

Manage Permissions Carefully

• Stable access: Don't frequently change who has admin access to your Facebook ad account
• Maintain access: Ensure the Facebook account used to connect maintains admin rights
• Business Manager: Keep Business Manager settings stable

Regular Monitoring

• Weekly review: Check Facebook Campaigns list weekly to verify data is syncing
• Compare with Facebook: Spot-check that spend amounts match Facebook Ads Manager (within 5-10%)
• Watch for sync gaps: If "Last Successful Data Fetch" is more than 2x your sync frequency, investigate