Connecting Facebook Ads to Alpha Insights

Connecting your Facebook Ads account allows Alpha Insights to automatically track your ad spend and calculate true Return on Ad Spend (ROAS). This guide walks you through the complete setup process using Facebook Marketing API v22.0.

Why Connect Facebook Ads?

• Automatic ad spend tracking– No manual data entry needed
• Real-time ROAS calculations– See if ads are profitable immediately
• Campaign-level insights– Know which specific campaigns drive profit
• Attribution matching– Connect ad clicks to actual orders
• Historical data sync– Import past ad spend automatically

Before You Begin

Requirements

Active Facebook Ads account with running or past campaigns

Admin access to the Facebook Ad Account you want to connect

Facebook Business Manager account (recommended but not required)

Alpha Insights Pro license activated

What You’ll Need

• Your Facebook login credentials
• Access to the Facebook account that manages your ads
• 5-10 minutes for setup

Step-by-Step Connection Process

Step 1: Access Facebook Integration Settings

1. Log in to your WordPress admin dashboard
2. Go to Alpha Insights → Settings
3. Click the Facebook Integration tab

Step 2: Start Connection

1. Click the Connect Facebook Ads button
2. A popup window will appear

Step 3: Log In to Facebook

1. In the popup, log in with your Facebook account
2. Use the account that has access to your ad account
3. If you’re already logged in to Facebook in your browser, it may skip this step

Step 4: Grant Permissions

Facebook will ask for permissions. Alpha Insights needs:

• ads_read– Read your ad campaign data, ad spend, and account details

Important: Alpha Insights only READS your ad data. It is read-only access and cannot create, modify, or delete ads or campaigns.

1. Review the permissions
2. Click Continue or Allow

Step 5: Select Ad Account

1. You’ll see a list of ad accounts you have access to
2. Select the ad account you want to track
3. Click Connect Account

Tip: The ad account ID is shown in parentheses (e.g., “My Store Ads (act_123456789)”)

Step 6: Fetch All Historical Data

After successful connection, you’ll see a confirmation screen:

1. A success message showing “Successfully Connected!” with your account name
2. A Fetch All Data button
3. Information explaining this will load all historical ad spend data
4. Click Fetch All Data to begin importing your data

Note: This initial data fetch loads all available historical data (up to 37 months). After this, data will automatically sync on your configured schedule.

Alternative: Fetch Data Later

If you prefer to configure settings first before fetching data:

1. You can skip the “Fetch All Data” step by closing the modal
2. Go to Settings → Facebook Integration
3. Configure your sync settings (described below)
4. Click Refresh All Campaign Data when ready

Step 7: Configure Sync Settings

Back in Alpha Insights, configure:

API Call Schedule

Choose how often Alpha Insights queries Facebook API for ad spend and campaign insights:

• Daily – Minimal API usage, data updates once per day
• Every 12 Hours – Balanced approach, updates twice daily
• Every 6 Hours (recommended) – More frequent updates for active campaigns

Recommendation: Every 6 hours for active campaigns provides good balance between data freshness and API usage.

Historical Data Import

When you first connect, Alpha Insights automatically imports all available historical data from your Facebook ad account:

• Facebook Marketing API provides access to up to 37 months of historical data
• All past campaigns, ad spend, and metrics are automatically imported
• Initial import happens in the background and may take 5-30 minutes depending on data volume
• You can manually refresh data anytime using the “Refresh All Campaign Data” button

Currency Settings

Automatic Currency Detection and Conversion:

• Alpha Insights automatically detects your Facebook ad account currency
• If your ad account currency differs from your WooCommerce store currency, all monetary values are automatically converted
• Converted values are marked in the data and both original and converted amounts are stored
• Exchange rates are applied at the time of data sync

Step 8: Data Fetch Complete

If data fetch is successful:

1. You’ll see an “All Set!” message
2. The success message shows how many campaigns were found and synced
3. The page will automatically reload to show your updated connection status
4. You can also click Done to reload immediately

If Data Fetch Fails

In case of large ad accounts or temporary API issues, you may see:

• A warning message: “Connection Successful – However, we couldn’t fetch your data at this time”
• Your account IS connected (authentication worked)
• Helpful suggestions for next steps:
  • Try fetching data again later from the Facebook settings page
  • Consider adjusting date range settings for large ad accounts
• Click Done – the page reloads to show your active connection
• You can manually fetch data anytime using the “Refresh All Campaign Data” button in settings

Important: A data fetch failure does NOT mean your connection failed. Your Facebook account is connected and you can fetch data later from the settings page.

Step 9: Verify Connection

You should see:

• Status:Connected(green)
• Connected account name
• Last sync time (should be recent)
• Initial sync starting

What Happens Next?

Initial Sync

Alpha Insights immediately begins syncing your ad data:

1. First 1-2 minutes: Fetches list of campaigns
2. Next 5-15 minutes: Imports historical ad spend data (up to 37 months)
3. Ongoing: Syncs new data based on your API call schedule setting

You can use Alpha Insights during this process – data will appear as it’s imported.

What Data Is Synced?

Alpha Insights imports from Facebook Marketing API:

• Campaign names and IDs
• Campaign objectives (e.g., purchases, leads, traffic)
• Daily ad spend per campaign (stored as expenses)
• Campaign performance metrics: impressions, clicks, outbound clicks, leads, purchases, purchase value
• Campaign ROAS (calculated from Facebook’s purchase data)
• Conversion rates
• Date ranges campaigns ran
• Ad account information (name, ID, currency)

Not synced (privacy/relevance):

• Ad creative content (images, videos, copy)
• Audience targeting details
• Individual ad-level performance (data is aggregated to campaign level)

Campaign Tracking with UTM Parameters

To accurately track which orders come from specific Facebook campaigns, Alpha Insights uses the meta_cid parameter:

Required Setup: Add this to your Facebook ad URLs:

meta_cid={{campaign.id}}

Full URL Example:

https://yourstore.com/product?meta_cid={{campaign.id}}

How it works:

• The {{campaign.id}} placeholder is automatically replaced by Facebook with the actual campaign ID
• Alpha Insights captures this parameter from the landing page URL when customers visit
• When they place an order (within the attribution period), it’s matched to the specific campaign
• This enables accurate profit calculations per campaign in your reports

Note: Orders are also attributed based on traffic source referrer (facebook.com), but the meta_cid parameter provides the most accurate campaign-level attribution.

Verifying Everything Works

Check Campaign List

1. Go to Alpha Insights → Facebook Campaigns
2. You should see a list of your campaigns
3. Verify campaign names match your Facebook Ads Manager
4. Check that ad spend amounts look correct
5. Each campaign should show: Ad Spend, Website Views (Outbound Clicks), Leads, Orders, Conversion Rate, Revenue, and ROAS

Check Expenses

1. Go to Alpha Insights → Expenses
2. Filter by “Facebook Ads” category
3. You should see daily ad spend entries
4. Each entry titled “Facebook Ads | [Account Name] | [Date]”
5. Verify amounts match your daily spend in Facebook Ads Manager

Check Dashboard

1. Go to Alpha Insights → Dashboard
2. Look for the “Ad Spend” metric
3. Should show Facebook ad spend for the selected period
4. Ad spend from Facebook is automatically included in your profit calculations

If you see data in all three places, your connection is working perfectly!

Troubleshooting Connection Issues

Issue: “Connection failed” error

Possible causes:

• Popup was blocked by browser
• Facebook login credentials incorrect
• Temporary Facebook API issue

Solutions:

1. Allow popups for your WordPress site
2. Try again in incognito/private browsing mode
3. Log out of Facebook completely, then try connecting again
4. Wait 10 minutes and retry (temporary API issues)

Issue: “Permission denied”

Cause: You don’t have sufficient access to the ad account

Solution:

• Verify you have at least “Advertiser” role in Facebook Business Manager
• Admin access to the ad account is required
• If someone else manages ads, have them connect the account
• Request admin access from the ad account owner
• Wait 5 minutes after permissions are granted before trying to connect

Issue: “No ad accounts found”

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

Solution:

• Verify you logged in with the correct Facebook account
• Check Facebook Business Manager to confirm you have ad accounts
• Ask to be added to the ad account if it’s managed by someone else

Issue: “Ad spend not showing up”

Check:

1. Connection status shows “Healthy” (green)
2. Last sync time is recent (check Settings → Facebook Integration)
3. If you skipped the “Fetch All Data” step during connection, you need to fetch data manually:
   • Go to Settings → Facebook Integration
   • Click Refresh All Campaign Data button
   • Wait 1-5 minutes for data to load
4. Verify campaigns are active and have spend in Facebook Ads Manager
5. Check date range in Alpha Insights includes days with ad spend
6. Data fetch can take 5-30 minutes depending on account size

Issue: “Ad spend amounts don’t match Facebook”

Common reasons:

• Currency auto-conversion – Alpha Insights converts to your store currency if different
• Time zone difference – minor discrepancies normal due to timezone boundaries
• Sync timing – Facebook data isn’t finalized immediately
• Data still processing – initial sync can take time

Solution:

1. Wait 2-3 hours after spending for Facebook to finalize their numbers
2. Click Refresh All Campaign Data to get latest data
3. Check again tomorrow – data should match once Facebook finalizes it
4. Verify you’re comparing the same date ranges in both systems
5. Check if currency conversion is being applied (look for “currency_converted” in campaign data)

Connecting Multiple Ad Accounts

Note: Currently, Alpha Insights supports connecting one Facebook ad account at a time.

If you need to switch to a different ad account:

1. Go to Settings → Facebook Integration
2. Click Remove Connection
3. Follow the connection process again with the new ad account
4. Note: Historical data from the previous account will remain in your database unless you delete it using the data deletion tools

Managing Your Connection

Viewing Connection Status

Go to Settings → Facebook Integration to see:

• API Status: Healthy / Error / Not Configured (with status indicator)
• Connected account: Account name (automatically fetched)
• Connection Expiry Date: When the access token will expire (max 60 days)
• Last API Check: When the API status was last verified
• Daily Expenses Stored: Number of daily ad spend records
• Campaigns Stored: Number of campaigns being tracked
• Last Successful Data Fetch: When data was last synced
• Next Scheduled Data Fetch: When the next automatic sync will occur

Manual Sync

Force an immediate data sync:

1. Go to Settings → Facebook Integration
2. Click Refresh All Campaign Data
3. Wait for completion (can take 1-5 minutes depending on data volume)
4. Check “Last Successful Data Fetch” time updates

When to use: Just launched a new campaign, need immediate update, or troubleshooting sync issues

Reconnecting

If connection expires or shows errors:

1. Go to Settings → Facebook Integration
2. Click Reconnect Facebook button
3. Log in to Facebook again in the popup
4. Grant ads_read permission
5. Select your ad account
6. Save settings
7. Connection restored

Note: Facebook access tokens automatically extend to 60 days when validated. The system checks token validity on every API call. If token expires, reconnect using the button.

Disconnecting

To remove the connection:

1. Go to Settings → Facebook Integration
2. Click Remove Connection
3. Confirm disconnection
4. Historical data remains in your database but no new data syncs
5. Use the data deletion tools if you want to remove historical data

Privacy and Security

What Alpha Insights Can Access

With ads_read permission, Alpha Insights can access:

• Campaign names, IDs, and objectives
• Ad spend amounts (daily and campaign totals)
• Campaign performance metrics (impressions, clicks, leads, purchases, ROAS)
• Campaign dates and status (active, paused, ended)
• Ad account information (name, ID, currency)

Alpha Insights CANNOT:

• Create, edit, pause, or delete ads or campaigns
• Access ad creative content (images, videos, ad copy)
• See audience targeting details or custom audiences
• View or modify ad account settings
• Access Facebook Pixel data beyond what’s in campaign metrics
• Make any changes to your ad account

This is read-only access – Alpha Insights can only view data, not modify anything.

Data Storage

• All data stored locally in your WordPress database (not on external servers)
• Campaign data stored as custom post type: facebook_campaign
• Daily ad spend stored as expenses with “Facebook Ads” category
• Access tokens stored in WordPress options table
• No ad creative content is stored
• No personal customer data from Facebook is stored
• Data can be deleted using the data deletion tools in settings

Compliance

• GDPR compliant – only necessary advertising data collected
• No personal customer data shared with Facebook
• All API communication uses secure HTTPS
• Access tokens automatically extend to maintain secure connection
• Follows Facebook Marketing API Terms of Service