Facebook / Meta Ads Integration

Connecting your Facebook / Meta Ads account to Attribution.ai enables automatic spend syncing, campaign performance tracking, and conversion matching via Facebook Click Identifiers (fbclid). This guide covers the complete setup process, what data is synced, required permissions, and how to troubleshoot common issues.

Prerequisites

Before connecting Facebook Ads, ensure you have:

An active Facebook Business Manager account
Admin access to the specific ad account you want to connect (Page-level admin access alone is not sufficient -- you need ad account admin access)
The Attribution.ai pixel installed on your Shopify store (required for click ID matching)
At least one active or recently paused campaign in the ad account

Step-by-Step Setup

In your Attribution.ai dashboard, navigate to Settings > Integrations.
Find Facebook / Meta Ads in the list of available integrations and click Connect.
You will be redirected to Facebook's OAuth authorization page. Log in with the Facebook account that has admin access to your ad account.
Review the permission requests and click Continue. Attribution.ai requests read-only access to your ad account data.
If you manage multiple ad accounts under your Business Manager, you will see a list of available accounts. Select the specific ad account(s) you want to connect. You can connect multiple accounts.
Click Confirm to complete the authorization.
You will be redirected back to Attribution.ai with a confirmation message. The initial data sync begins immediately.

Required Permissions

During the OAuth flow, Attribution.ai requests the following Facebook permissions:

Permission	Purpose
`ads_read`	Read campaign, ad set, and ad performance data
`ads_management`	Access ad account structure and metadata (read-only usage)
`business_management`	List available ad accounts under your Business Manager

Attribution.ai only reads data from your ad account. It does not create, modify, or delete any ads, campaigns, or audiences.

What Data Is Synced

Once connected, Attribution.ai pulls the following data from your Facebook Ads account:

Spend and Performance Data

Daily spend broken down by campaign, ad set, and individual ad
Impressions: Total ad impressions per day
Clicks: Link clicks and all clicks
Reach: Unique users who saw your ads
Frequency: Average number of times each user saw your ads

Campaign Structure

Campaign names, IDs, and objectives (Conversions, Traffic, Awareness, etc.)
Ad set names, targeting metadata, and budget settings
Ad creative names and IDs
Campaign status (active, paused, archived)

Click ID Matching

Attribution.ai's pixel captures the fbclid parameter that Facebook appends to ad destination URLs
When a visitor with an fbclid later makes a purchase, Attribution.ai matches the click to the specific Facebook campaign, ad set, and ad that drove the visit
This click-level matching enables precise, ad-level attribution rather than just campaign-level estimates

Sync Frequency and Historical Data

Automatic sync: Every six hours, Attribution.ai pulls the latest spend and performance data from your Facebook Ads account
Historical import: On first connection, up to 90 days of historical data is imported so you have spend context immediately
Manual sync: You can trigger an immediate sync at any time from Settings > Integrations by clicking the sync button on the Facebook card
Data finalization: Facebook may adjust reported metrics for up to 72 hours after the original reporting date. Attribution.ai re-syncs recent dates during each sync cycle to capture these adjustments

How Facebook Attribution Works in Attribution.ai

Attribution.ai uses multiple signals to attribute conversions to Facebook:

Click ID matching (strongest signal): When a customer clicks a Facebook ad, the fbclid parameter is appended to the URL. The Attribution.ai pixel captures this and stores it in the visitor's session. When that visitor purchases, the fbclid links the order to the specific ad.
UTM parameter matching: If your Facebook ads use UTM parameters (e.g., utm_source=facebook), Attribution.ai also uses these for attribution. This serves as a fallback when fbclid is not available.
Survey responses: If a customer reports discovering your brand through Facebook or social media in the post-purchase survey, this is incorporated into Attribution.ai's triangulated attribution logic.
Referrer matching: Visits referred from facebook.com or instagram.com domains are attributed to Facebook/Meta organic or paid channels based on the presence of click IDs and UTM parameters.

Best Practices

UTM Parameters

While fbclid provides strong click-level matching, we recommend also using consistent UTM parameters on your Facebook ad URLs:

utm_source=facebook
utm_medium=paid_social
utm_campaign={campaign_name}
utm_content={ad_name}

UTM parameters provide redundant tracking that helps when fbclid is stripped by redirects or privacy tools. They also make your Attribution.ai reports easier to read because campaign and ad names appear directly in the data.

Attribution Window Alignment

Facebook Ads Manager uses its own attribution window (typically 7-day click, 1-day view by default). Attribution.ai uses a separate lookback window (default: 30 days). These do not need to match exactly, but be aware that comparing numbers between the two systems will show differences if the windows are different.

For the most consistent comparison, set your Attribution.ai lookback window in Settings > Attribution to align with your Facebook attribution window.

Campaign Naming Conventions

Use consistent naming conventions in your Facebook campaigns. Attribution.ai groups data by campaign name, so inconsistent naming (e.g., "Summer Sale 2026" vs "summer-sale-2026" vs "SS2026") creates fragmented data.

Troubleshooting

Authorization Errors

"You don't have permission": You need admin access to the ad account, not just the Facebook Page. Go to Facebook Business Manager > Business Settings > Ad Accounts and verify your role is "Admin" for the account you are trying to connect.
"Business not verified": Facebook requires Business Verification for some API features. Verify your business at business.facebook.com/settings/info.
OAuth redirect fails: Clear your browser cache and cookies for facebook.com, then try connecting again. If the issue persists, try a different browser.

Missing Campaigns

Only active and recently paused campaigns are synced. Campaigns archived more than 90 days ago will not appear.
Newly created campaigns may take up to 24 hours to appear in synced data. Ensure the campaign has delivered at least one impression.
If specific campaigns are missing, trigger a manual sync from the Integrations page.

Spend Discrepancies

Minor differences (under 5%) between Attribution.ai and Facebook Ads Manager are normal. Common causes include:

Time zone differences: Facebook reports based on the ad account's time zone. Ensure your Attribution.ai store time zone matches or account for the difference when comparing.
Attribution window differences: Facebook's default attribution counts view-through conversions; Attribution.ai focuses on click-through by default.
Data finalization timing: Facebook adjusts numbers for up to 72 hours. If comparing recent dates, wait for finalization.
Currency conversion: If your ad account uses a different currency than your store, exchange rate timing can cause small differences.

If discrepancies exceed 5%, check that you are comparing the same date range, the same metrics (link clicks vs all clicks), and the same attribution window in both systems.

Token Expiration

Facebook access tokens expire periodically (typically every 60 days). When this happens:

You will see a "Reconnect Required" banner on the Facebook integration card in your dashboard.
Click the banner or go to Settings > Integrations > Facebook > Reconnect.
Complete the OAuth flow again. Your historical data is preserved -- only the authorization token is refreshed.

If you see frequent token expirations, ensure your Facebook account has a stable admin role on the ad account and that your Facebook account's password has not changed recently.

No fbclid Values in Event Data

If your Events tab shows Facebook referral traffic but no fbclid values:

Verify that your Facebook ad URLs point directly to your Shopify store (not through a URL shortener, landing page builder, or redirect service that strips query parameters).
Check that your Shopify theme is not stripping URL parameters on redirect (some themes with aggressive redirect rules can cause this).
Confirm that the Attribution.ai pixel is installed on the landing page that Facebook ads link to.

Disconnecting Facebook Ads

To disconnect the Facebook integration:

Go to Settings > Integrations.
Click the three-dot menu on the Facebook card.
Select Disconnect.
Confirm the disconnection.

Historical data synced before disconnection is preserved in your Attribution.ai account. Only new data will stop syncing.