Facebook Ads Settings

Connect your Facebook Ads account to Alpha Insights for automatic ad spend tracking, campaign performance insights, and profit-based ROAS calculations. This powerful integration eliminates manual data entry and provides campaign-level profitability analysis.

Accessing Facebook Ads Settings

1. Go to Alpha Insights → Settings
2. Navigate to the Facebook settings page
3. You’ll see the Facebook API configuration interface

Integration Status: Beta

The Facebook Ads integration is currently in beta. It’s fully functional and production-ready, with ongoing improvements and feature additions.

What This Integration Does

• Automatic ad spend tracking: Daily Facebook ad spend imported as expenses
• Campaign insights: Performance metrics for each campaign (impressions, clicks, CPC, etc.)
• Profit per campaign: Track which campaigns actually drive profit using UTM tracking
• True ROAS calculations: Return on Ad Spend based on profit, not just revenue
• No manual data entry: Everything syncs automatically on schedule
• Historical data import: Fetch up to 36 months of past data

API Connection

Connect Alpha Insights to your Facebook Ad Account using secure OAuth authentication.

Connect To Facebook

Connection Status Display

Shows your current connection status:

• Connected To: Ad account name with green status circle (when connected)
• Ad Account ID: Your Facebook ad account ID number
• Access Token: Masked token for security (hidden by default)

Initial Connection Setup

1. Click Connect to Facebook button
2. Facebook popup window opens
3. Log in with Facebook account that has admin access to your ad account
4. Facebook asks for permissions – click “Continue” to grant ads_read permission
5. Select your Ad Account from the list provided
6. Click Connect Account button
7. A success screen appears with your connected account name
8. Click Fetch All Data to immediately import your historical ad data
9. Or click outside the modal to configure settings first, then fetch data later using “Refresh All Campaign Data” button
10. If data fetch is successful, you’ll see a completion message
11. If data fetch fails (e.g., large account, API issues), you’ll see a helpful message explaining your account IS connected and you can fetch data later
12. Page reloads to show your active connection status

Important requirements:

• Must have Admin access to the Facebook Ad Account
• Ad Account must be active (not disabled or restricted)
• Business Manager accounts: Ensure you’re added as admin
• Personal ad accounts: Log in with the account owner

Reconnecting

Facebook access tokens expire after maximum 60 days. When expiry approaches or token expires:

1. You’ll see “Token Invalid” or “Connection Expired” status
2. Click Reconnect Facebook button
3. Log in to Facebook again
4. Grant permissions
5. Connection restored with new 60-day token

Tip: Set a calendar reminder to reconnect every 55 days to avoid interruption

Disconnecting

To remove the Facebook connection:

1. Click Remove Connection button
2. Confirm disconnection
3. Access token is cleared from database
4. Scheduled syncs stop immediately
5. Historical data remains in database (unless you delete it)

API Status

View detailed connection health information:

API Status:

• Healthy: Connection working normally (green)
• Needs Attention: Token expiring soon or minor issues (yellow)
• Error: Connection failed or token invalid (red)
• Not Configured: Not yet connected (gray)

Connection Expiry Date: When your access token expires (60 days max from connection)

API Status Message: Detailed error or success message from last API check

Last API Check: Timestamp of most recent connection verification

Alpha Campaign Profit Tracking

The most powerful feature – track which Facebook campaigns actually drive profit, not just revenue.

How It Works

1. You add a special tracking parameter to your Facebook ad URLs
2. When someone clicks your ad, this parameter is captured in their session
3. When they make a purchase, the order is linked to the specific Facebook campaign
4. Alpha Insights calculates the profit for that order
5. You can see true profit-based ROAS, not just revenue-based

UTM Tracking Key / Values

The magic parameter: meta_cid={{campaign.id}}

What it does:

• meta_cid = Meta Campaign ID (Facebook’s parent company)
• {{campaign.id}} = Facebook dynamic parameter that auto-fills with actual campaign ID

Setting Up UTM Tracking

Method 1: In Facebook Ads Manager (Recommended)

1. Go to Facebook Ads Manager
2. For each ad campaign, edit the ad
3. Find the “Website URL” or landing page URL field
4. Add the tracking parameter to your URL

Examples:

Original URL:
https://yourstore.com/products

Add parameter:
https://yourstore.com/products?meta_cid={{campaign.id}}

If URL already has parameters (contains ?):
https://yourstore.com/products?color=blue&meta_cid={{campaign.id}}
(Use & instead of ?)

Facebook automatically replaces {{campaign.id}} with the actual campaign ID when someone clicks

Method 2: URL Parameters at Campaign Level

1. In Facebook Ads Manager, go to campaign settings
2. Find “URL Parameters” section (under “Tracking”)
3. Enter: meta_cid={{campaign.id}}
4. This applies to all ads in the campaign automatically

Recommendation: Use Method 2 for new campaigns – it’s easier and applies to all ads

Testing Your Tracking

1. Click your Facebook ad (or use Preview URL from Facebook)
2. Look at the URL in your browser
3. You should see: meta_cid=123456789 (with an actual number)
4. This confirms tracking is working

Viewing Campaign Profit

After setting up tracking:

1. Wait for orders to come in from your Facebook ads
2. Go to Alpha Insights campaign reports
3. You’ll see profit attributed to each Facebook campaign
4. Calculate true ROAS: (Profit ÷ Ad Spend) × 100

Example:

• Campaign: Summer Sale
• Ad Spend: $500
• Revenue from orders: $2,000
• Profit from orders: $800
• Revenue ROAS: 400% ($2,000 ÷ $500)
• Profit ROAS: 160% ($800 ÷ $500)

Why profit ROAS matters: A campaign with high revenue might have low profit if products have low margins

API Settings

Configure how Alpha Insights syncs with Facebook.

API Call Schedule

What it does: Controls how often Alpha Insights checks Facebook for new data

Options:

• Daily: Checks once per day (sufficient for most stores)
• Every 12 Hours: Checks twice daily (morning and evening)
• Every 6 Hours: Checks four times daily (most current data)

What gets synced on schedule:

• Daily ad spend amounts
• Campaign insights and metrics
• Campaign status changes
• Past 30 days of data (updated/created)

Recommendation:

• Daily: Perfect for most stores – checks once per day
• 12 Hours: If you actively monitor and adjust campaigns
• 6 Hours: Only if you need very current data (uses more API quota)

Collect Campaign Insights

Options: True or False

What it does: When enabled, fetches detailed metrics for each campaign:

• Impressions
• Clicks
• Click-through rate (CTR)
• Cost per click (CPC)
• Cost per thousand impressions (CPM)
• Conversions (if tracked by Facebook Pixel)

Recommendation: Keep enabled (True) for full campaign reporting and analysis

Collect Daily Ad Spend

Options: True or False

What it does: Automatically creates expense records for your daily Facebook ad spend

How it works:

1. Every day (per schedule), Alpha Insights checks your Facebook ad spend
2. Creates an expense entry for that day’s total spend
3. Expense is categorized in your selected expense category
4. This expense is included in net profit calculations
5. Shows up in expense reports and net profit calculations

Recommendation: Keep enabled (True) for automatic expense tracking – no manual data entry needed

Ad Spend Expense Category

What it is: The expense category where Facebook ad spend is stored

How to configure:

1. Select category from dropdown (shows all your expense categories)
2. Or click Add New Category to create one
3. Common names: “Facebook Advertising”, “Digital Marketing”, “Paid Ads”

Why it matters: Allows you to separate Facebook ad costs from other expenses in reports

Recommendation: Create a dedicated “Facebook Ads” category for clean reporting

Request Timeout

Default: 5 seconds

Range: 5-60 seconds

What it does: How long to wait for Facebook API responses before timing out

When to change:

• Getting timeout errors in sync logs
• Large ad account with many campaigns
• Slow server or network connection

Recommendation: Keep at 5 seconds unless experiencing timeout issues

Number Of Results To Collect Per Call

Default: 50

Range: 1-500

What it does: How many records Facebook returns per API request

Technical details:

• Facebook tells us if there are more results to fetch
• Alpha Insights automatically makes additional requests until all data is collected
• Lower number = more API requests, less chance of timeout
• Higher number = fewer API requests, more efficient but may timeout

When to change: Only reduce if experiencing timeout errors

API Data

View information about synced Facebook data in your database.

Daily Expenses Stored: Number of daily ad spend expense records created

Campaigns Stored: Number of Facebook campaigns being tracked

Last Successful Data Fetch: When the last sync completed successfully

Next Scheduled Data Fetch: When the next automatic sync will run

Use this to verify:

• Data is syncing (check Last Successful timestamp)
• Number of campaigns matches your expectations
• Next sync is scheduled correctly

API Tools

Maintenance and data management tools for your Facebook integration.

Refresh All API Data

What it does: Immediately fetches all Facebook data for all time (up to 36 month limit)

When to use:

• After first connecting your Facebook account
• If you think data is missing or out of sync
• After making changes to API settings
• To backfill historical data

How it works:

1. Click Refresh All Campaign Data button
2. Process runs in background (takes 1-3 minutes depending on account size)
3. Creates new records or updates existing ones
4. Does NOT delete any data
5. Facebook API limit: 36 months maximum history

Note: This is a large API request – use sparingly. Regular scheduled syncs only check past 30 days.

Check API Status

What it does: Immediately tests your Facebook API connection and displays status

When to use:

• Troubleshooting connection issues
• After reconnecting your account
• Verifying token is still valid
• Checking for API errors

Results shown:

• Connection status (Healthy, Error, etc.)
• API status message (success or error details)
• Token expiry information
• Ad account accessibility

Delete All Expense Data

What it does: Removes all Facebook ad spend expense records from your database

Important notes:

• Only deletes data stored in Alpha Insights
• Does NOT affect your Facebook ad account
• Cannot be undone
• Does not delete campaign insights (only expenses)

When to use:

• Starting fresh after testing
• Connected wrong ad account and want to clean up
• Before permanently disconnecting integration

Delete All Campaign Data

What it does: Removes all Facebook campaign insights from your database

Important notes:

• Only deletes data in Alpha Insights
• Does NOT affect Facebook
• Cannot be undone
• Does not delete expense records (only campaign insights)

When to use: Same scenarios as deleting expense data

Important Information

Facebook API Limitations

• 36-month limit: Facebook API can only fetch back 36 months of historical data
• Access token expiry: Tokens expire after 60 days maximum – requires reconnection
• Single account: Can only connect one Facebook Ad Account per WordPress site
• Admin access required: Must have admin permissions on the ad account
• Read-only access: Alpha Insights cannot make changes to your ad account

Data Syncing Details

• No duplication: When syncing, Alpha Insights creates new records or updates existing ones – never duplicates
• Scheduled syncs: Check past 30 days and update/create accordingly
• Full refresh: Checks all data up to 36 months back
• Currency conversion: If ad account currency differs from store currency, amounts are automatically converted

Privacy and Security

• Read-only: Alpha Insights only reads data, cannot modify anything in Facebook
• Encrypted storage: Access tokens are encrypted in database
• No customer data: Only campaign metrics are accessed, no personal customer information
• Secure authentication: Uses Facebook OAuth 2.0 standard

Facebook API Log

At the bottom of the settings page, you’ll see the Facebook API Log.

What it shows:

• Recent API calls and their results
• Success/error messages
• Timestamps of sync operations
• Detailed error information when issues occur

Use for troubleshooting:

• Check if syncs are running
• Identify specific error messages
• Verify connection health over time
• Provide to support when requesting help

Troubleshooting

Connection Failed / Token Invalid

Solution: Click “Reconnect Facebook” and log in again

Permission Denied Error

Cause: Logged in Facebook account doesn’t have admin access to ad account

Solution: Log in with an account that has admin permissions, or request admin access

No Campaigns Showing

Check:

• Connection status is “Healthy”
• “Collect Campaign Insights” is enabled
• Clicked “Refresh All Campaign Data”
• Campaigns are active in Facebook Ads Manager

Ad Spend Not Matching Facebook

Common reasons:

• Currency mismatch – check if ad account uses different currency
• Time zone differences – check WordPress timezone setting
• Sync hasn’t run yet – wait for scheduled sync or click “Refresh”
• Looking at different date ranges

Syncs Not Running

Check:

• Connection status is healthy
• API call schedule is configured
• WordPress cron is running (requires site traffic)
• Check API log for error messages

Best Practices

Setup

• Use a business Facebook account for connection, not personal
• Create dedicated expense category for Facebook ads
• Add UTM tracking to all active campaigns immediately
• Run “Refresh All Campaign Data” after initial connection
• Set calendar reminder to reconnect every 55 days

Ongoing Use

• Check API status weekly to ensure connection is healthy
• Review Facebook API log monthly for any error patterns
• Always use UTM tracking on new campaigns
• Keep “Collect Campaign Insights” enabled for full reporting
• Use daily or 12-hour sync schedule for active campaigns

Campaign Tracking

• Add UTM parameter to ALL Facebook ads for complete tracking
• Test tracking by clicking your own ads and checking URL
• Name campaigns clearly in Facebook – names appear in Alpha Insights
• Use campaign-level URL parameters to avoid individual ad editing

Summary

The Facebook Ads integration provides:

• Automatic tracking: No manual data entry required
• True profitability: See which campaigns actually drive profit
• Complete insights: Full campaign metrics in one place
• Easy expense management: Ad spend automatically categorized
• Reliable syncing: Scheduled updates keep data current

Once configured, the Facebook integration runs automatically, providing you with accurate campaign profitability analysis and eliminating manual ad spend tracking!