Updating Facebook UTMs on Ads

One of the ways that advertisers measure the return on investment of advertising is tying ads to revenue. So for example, for every 1,000 clicks on an online digital Ads, how many of those people actually buy the product?

The way this is tracked is that you put in what is called a UTM tag on the link you are advertising. UTM stands for Urchin Tracking Modules and you can read it’s history here. The UTM parameters are appended to a link. So if the link you are advertising is:


then UTM parameters are added at the end like so:


These tags are then analyzed by either Google Analytics, Facebook, or you can use something else that gets this traffic. What we like about Matomo is that it gives it to you instantly where as with Google and Facebook you have to wait for their systems to kick in. They aren’t very instant. With Matomo you own the data, you get it all.

So the question arises, what if you have 3000+ ads out and you want to update all of them to include UTM parameters? Well, this is a very good case for automation. Seems like it should be easy enough. But here is the first problem:

  1. In order to use Facebook APIs you have to create a Facebook Application
  2. You then need to request permissions to use the APIs to read and to write
  3. This request includes creating a video and signing all kinds of T&Cs.
  4. Then you are rate limited until you have made several successful calls after a certain number of days.

That whole process for new people will take you about a week if you are lucky.

Now you have access to the APIs and can use them (yes you can use a test account first if you want). But now you have to figure out how to change the one url_tags parameter that has all the UTM goodness. We changed ours to be:

utm parameters we append.

It seems like this should be easy! Find the Ad ID and then update the url_tags right? Ha ha! Uh no.

It turns out that each Ad object has an AdCreative object. This AdCreative is where the URL tags live. So then you just have to update the AdCreative object that belongs to the Ad right? Ha ha! That would be too obvious. No.

If you look at the update documentation, the only fields on AdCreative you can update are account_id , adlabels, name, and status. So if you want to update just the url_tags, you have to copy the existing one, and then add it to the existing Ad object.

Ok, so now you get the basic idea of what you have to do. So let’s try to do this in Python because a lot of the world uses Python for data analytics and so do we. There should be a well documented library that does this right? And the Facebook docs (docs from a world class organization) should have everything you need right? I’m sorry, but no.

The current docs mention remote_update but this is deprecated. Instead we should use api_update or api_create, but ahem, this is also being deprecated… So what do you do?

Well, I’ll spare you the days of horror I went through. I still don’t even know if I’m doing it right! But I made it work as follows:

# get ad creative
ad = Ad(<ad Id>)
ac = AdCreative(<ad creative id>)
d = ac.export_all_data()
d['url_tags'] = 'utm_media=social...'
# remove a few of the fields not allowed, code not shown
# create a new ad creative based on the old Ad Creative
new_ac = AdAccount(ad_account_id).create_ad_creative(
                fields=fbfields.ad_creative, params=d
ad['creative']['id'] = new_ac['id']
update = ad.api_update( params={"creative" : new_ac})

Once this is done you can automate the entire process of adding tags.

Bonus! You may find that if you are updating Instagram Ads as well you also have to connect the Instagram Account to your Business Manager. You’ll get 400 errors if you don’t stating you are not authorized. Inside Instagram Accounts, under Connected Assets you need to ad the Facebook Ad Account. That way you can manage it from the apps.

After the changes are reviewed, you can see the results coming in. As we track them ourselves, we have access to the data in real time and don’t have to wait for Google or Facebook to tell us if our ads worked. To decipher what they mean, this post has some good information. For example, some of our ads were placed on the an (Audience Network), fb, ig.

This way we can start tracking which one of our ads is performing the best.