DataStated Documentation Add my site
Add my site

Connect Meta Ads

Compare Meta's claimed conversions with processor-confirmed orders attributed to Meta Ads. Campaign, ad-set and ad reports contain Meta's own results; monetary comparisons require known USD ad currency and compatible processor-confirmed payments.

Provider activation pending

As of September 11, 2026, the Meta app is unpublished and ads_read testing has not started. Hosted customer connection is not ready. The steps below describe the implemented flow once provider access is enabled and a live pull has been verified.

1. Tag your ads

DataStated classifies paid Meta traffic from the landing URL. An fbclid needs a paid utm_medium to map to Meta Ads. Without a click id, utm_source can be meta, facebook, fb, instagram or ig, again beside a paid medium such as cpc or paid_social (full list). A bare fbclid or utm_source=meta without a paid medium is plain Meta and is excluded from Meta's verified side. Facebook can add fbclid to organic links too. Captured URL parameters classify traffic; they do not prove that Meta served an ad. A click id takes precedence over the source, and the referrer is the fallback.

Include a paid medium in your ad links. A missing click id or referrer makes consistent UTMs especially useful, although browsers and redirects can remove parameters too. In Ads Manager, at the ad level under Tracking → URL parameters, set:

utm_source=meta&utm_medium=paid&utm_campaign={{campaign.name}}&utm_content={{ad.name}}

2. Connect

  • Open your site's settings in the dashboard, choose the Revenue tab, and in the Meta Ads card click Connect Meta Ads. Only a site owner can do this.
  • Meta's dialog asks for one permission, ads_read. That is read access to ad reporting and nothing else: no permission to edit campaigns, change budgets or post, so nothing on your account can be changed from here.
  • If the login manages one ad account, it is connected on the spot. If it manages several, the card lists them; pick one and click Connect account. A login with no ad accounts is told so; sign in with the login that runs your ads.

The token Meta issues is exchanged for a long-lived one, sealed with AES-256-GCM before it is stored, and never shown to anyone, including you. Reporting requests include an app-secret proof; the access token still needs to be kept secret. Each sync reads daily spend, impressions, clicks, purchases and purchase value for every campaign, and the same rows per ad set and ad. Purchases are read from one rollup, omni_purchase first, so a sale Meta reports under several action types is counted once.

3. What you will see

Numbers come in on the sync that runs every six hours, and the first pass reaches 90 days back, with completion depending on the account size and successful provider reads. Until that first pass lands, the platform side of the comparison carries an Example badge and the Ads panel says the connection is live and numbers appear on the next sync. To pull sooner, call the API:

curl -X POST -H "Authorization: Bearer dsk_YOUR_KEY" \
  https://app.datastated.com/api/sites/acme.com/sync

The What each platform claims panel shows platform-claimed conversion counts beside processor-confirmed orders attributed to its paid channel. Orders without payment confirmation are listed separately. Example claims are labeled; they are not results from your account.

For a window whose ad records all carry provider-reported USD, the Money section shows spend and platform-reported revenue, CPC and ROAS. Campaign, ad-set/ad-group and ad rows remain platform reports. Revenue gaps and efficiency figures also require processor-confirmed payments with compatible USD currency. Unknown, mixed or non-USD ad currency leaves combined dollar figures unavailable and shows currency groups separately, without conversion. Re-sync older records to obtain their account currency. Journey rows separately show Touched, Started and Closed. See comparison scope.

4. Why the numbers differ

Meta counts a purchase when someone buys within its attribution window after clicking an ad, or after only seeing one. Your site records the visit that happened and the order that followed. Someone who saw an ad on their phone and bought on a laptop is a Meta sale and a direct order on your site. Where Meta cannot observe a conversion, on iOS in particular, it models one; your site models nothing. Both sides have blind spots: your site misses anyone running an ad blocker, and Meta grades its own homework. The two reports use different evidence and do not establish a lower or upper bound on the sales an ad caused.

5. Troubleshooting

  • No spend showing. Check the currency-scope notice. Combined dollar amounts need known USD ad currency; older rows with unknown currency need a re-sync. Mixed or non-USD amounts are not converted. For missing activity, also check the selected account and date range.
  • Claims but no attributed orders. Meta reported sales and your site recorded no order from a Meta-tagged visit. Confirm the tag is installed and orders are tracked (Goals and orders), then open the UTM sources tab and check what arrived: a utm_source spelled any way but meta, facebook, fb, instagram or ig, or a utm_medium that is not a paid one, is the usual cause.
  • "Meta access has lapsed." Long-lived tokens expire after about 60 days. The worker re-exchanges them before that, but if Meta rejects one (a password change, the app removed from your Facebook settings, or lost access to the ad account) the card asks you to Reconnect Meta. Numbers already pulled stay.
  • Wrong account. Click Reconnect and choose again; the new choice replaces the old one. Disconnect removes DataStated's access on Meta's side too.

Questions? Email us at hello@datastated.com.