The Facebook Ads connection brings spend, impressions, clicks and campaign structure into KO. Joined with the website connection, that is what turns “we spent €4,000 on Facebook” into cost per lead per campaign.
One connection carries one ad account, and the account should not be swapped later — pick it deliberately.
Set up the connection in KO
- In Connects, click Add connect….
- In the Advertisement category, choose Facebook Ads and click Connect.
- In Connection, click Connect and sign in to Facebook in the window that opens.
- In that window, tick every Page and ad account — see below, this is the step that goes wrong most often.
- Check Connected user: it shows the Facebook account the connection now works on behalf of.
- Choose the Ad account. The list shows each account’s name, currency, status and id. Choose deliberately: do not swap the account on a working connection — the statistics already collected stay with the previous one while new figures arrive from another, and one connection ends up holding two different sources of spend. A second ad account means a second connection.
Tick every Page and ad account
Facebook keeps permissions as one list per user and rewrites that list on every authorisation. Tick fewer boxes than last time and access disappears from connections set up earlier — in this project and in others that authorised as the same Facebook user. Leads and spend simply stop arriving for them.
So: tick all Pages and all ad accounts, even the ones this project does not need.
If the window shows no list at all, click Edit previous settings — Facebook hides the list when the same user authorises again.
Set up statistics
In the Statistics section:
- Account currency is read from Facebook and shown as is. KO converts amounts to the project currency, set in the project’s Settings.
- Add VAT to spend adds a percentage on top of what Facebook reports. Facebook reports spend without it, so a project that pays VAT on ads under-counts cost per lead until this is filled in. The value applies to the whole statistics period and can be changed at any time.
- Campaigns to show in statistics selects which campaigns KO reads. Campaigns left unticked do not appear in reports at all — including their spend.
Describe how your ads are tagged
The Ad tags section is how KO knows which visits belong to which ad. It does not change anything in Facebook: KO reads the tags, it does not write them.
The defaults describe the tagging KO expects:
| Field | Default |
|---|---|
utm_source | facebook-ads |
utm_medium | cpc |
utm_campaign | {{campaign.id}}_{{campaign.name}} |
utm_content | {{adset.name}}|{{ad.name}} |
utm_term | ({{site_source_name}}: {{placement}}) |
Two rules decide what KO uses for a given ad:
- if the ad has its own URL tags in Facebook, those win;
- if it has none, KO assumes the ads are tagged as described here.
Which means the fields have to match the tagging your ads actually carry. Tag ads as
fb while this section says facebook-ads, and the spend and the visits land in two
different rows of the report instead of one.
Turn the connection on
Fill in Notify when the balance drops below if you want the balance warning, then switch the connection status to Active:
- Active — everything works.
- Setting up — everything works, but data updates are paused.
- Archived — the connection is off; data and statistics are kept.
- Delete — removes the connection’s data and statistics.
Data updates only run in Active, so a connection left in Setting up stays silently empty.
Check that data is coming in
- Connected user names the Facebook account you authorised as.
- The Ad account list contains your accounts. An empty list means the authorisation did not grant access to them — repeat it and tick everything.
- Campaigns to show in statistics fills with your campaigns after Reload data. Campaigns arriving is the sign that the account is readable.
- Once the status is Active, spend for recent days appears in the project’s reports next to the leads.
If it doesn’t add up
Spend arrives, leads arrive, nothing joins up. The tagging on the ads and the Ad tags section disagree. Compare a real ad’s URL with what the section says, and make them match — the report joins on the UTM values, not on the account.
A connection that used to work stopped. KO reports that the link with Facebook dropped and the account has to be reconnected. Two usual causes: someone re-authorised the same Facebook user with fewer Pages ticked, or the Facebook password changed.
The wrong ad account is selected. Do not switch it on this connection: the statistics already collected for the previous account will not disappear when the field changes. Archive the connection and create a new one for the correct account.
A campaign is missing from every report. Check Campaigns to show in statistics — an unticked campaign contributes nothing, and its spend disappears with it.
The balance is never checked. Accounts on post-payment have no balance to read, so the balance notification cannot work for them.
The amounts differ from the Facebook interface. Two things move them apart: Add VAT to spend, and conversion into the project currency. Compare against the account currency before concluding the numbers are wrong.