Dynamic Product Pricing using the AdWords API

in AdWords API

I'm often asked to develop tools that upload ads and keywords to AdWords from product catalogs, but sometimes my customers don't want to upload new ads, they just want to change the price that's displayed in them. PPC Tool developers like Marin Software and Podium AdTech provide this type of functionality, but it's just a small part of their complete package, which can be quite expensive.

Fortunately, you don't need to use expensive software to automatically modify the prices displayed in your ads: It's just a feature of the AdWords API called AdParams, which enables you to dynamically insert parameterized values into existing ads. This works in a similar way to dynamic keyword insertion, just with a bit of code. In this article I will present a basic PHP script that anyone with an AdWords API token can use without needing to resort to full service software in order to use a small portion of its functionality.

How Ad Parameters Work

Ad Parameters work in a similar way to dynamic keyword insertion; the difference is that instead of a keyword being inserted into the ad, a value associated with the keyword is used instead. The process for creating a parameterized ad is as follows:

  • Create an ad with a placeholder for the parameter using a specific syntax.
  • Associate each keyword within the ad group with a value to be inserted when the ad is shown.
  • When a keyword triggers an ad, the placeholder in the ad is replaced by the value you associated with the keyword.

Creating an Ad With a Parameter

Lets start by creating an example ad; the syntax for inserting the parameter is {param1:default}, so we can go into AdWords and build an ad like this:

An Ad with Ad Parameters
An Ad with Ad Parameters

As we haven't specified any parameters yet, it will just appear in the search results with the default we've set to $10:

An Ad with a Default Price
An Ad with a Default Price

Loading a Price Per Keyword

We now need to use the AdWords API to set a price to display in the ad depending on the keyword used in the search query. Here's a PHP script that does just that:

<?php
require_once 'Google/Api/Ads/AdWords/Lib/AdWordsUser.php';
 
// AdWords API Credentials
$username = "[email protected]";
$password = "pa55word";
$customerId = "123-456-7890";
$developerToken = "aaabbbccc1111DDD";
 
// Create an AdWords API user
$user = new AdWordsUser(null, $username, $password, $developerToken);
$user->SetClientId($customerId);
 
// Get a reference to the AdParam service
$adParamService = $user->GetService('AdParamService', 'v201109');
 
// Create an AdParam for a specific keyword
$adGroupId = "KEYWORD_ADGROUP_ID";
$criterionId = "KEYWORD_ID";
$insertionText = "$20";
$paramIndex = "1";
$adParam = new AdParam($adGroupId, $criterionId, $insertionText, $paramIndex);
 
// Upload the new AdParam to AdWords
$operation = new AdParamOperation();
$operation->operand = $adParam;
$operation->operator = "SET";
$operations = array($operation);
$adParams = $adParamService->mutate($operations);
?>
Setting the Parameter Values in an Ad

If you modify the appropriate variables in this script and run it, then—within five minutes—doing a search on your selected keyword should reveal a modified ad:

An Ad with a New Price
An Ad with a New Price

How the Code Works

The first part of the script is the standard boilerplate code to access the API: You need to enter your developer token into the $developerToken variable, your Google Account login email and password into the $username and $password variables, and the customer ID of the account you want to access in the $customerId variable.

Next we get a reference to the API service we want to use:

$adParamService = $user->GetService('AdParamService', 'v201109');
The AdParam Service

Then, the most important part of the script is where the Ad Parameter is created:

$adGroupId = "KEYWORD_ADGROUP_ID";
$criterionId = "KEYWORD_ID";
$insertionText = "$20";
$paramIndex = "1";
$adParam = new AdParam($adGroupId, $criterionId, $insertionText, $paramIndex);
Creating an Ad Parameter

To use this snippet of code, you need to know the API Ids of the AdGroup and Keyword for which you want to attach the Ad Parameter; I usually obtain these by running a report. Then you need to enter your new product price into the $insertionText variable, and also specify the index of the parameter into the $paramIndex variable; I'll explain these two variables next.

The Insertion Text

The $insertionText variable is the key variable within the example code: It specifies the replacement value that you want to appear in your ad when someone does a search for the selected keyword. This is where you enter your updated product price: $20, in the above example.

However, you can use this variable for more than just price changes: It can contain any number, so you can use it anywhere you want variable numbers in your ads; maybe for a “20% discount”, or it's even just about possible to use a basic numeric date like “4/1” etc. You just need to follow certain rules about how your numbers need to be formatted:

  • You can use periods and commas for fractions and thousand separators: eg 1,100.00.
  • You can add currency symbols and codes before and after the number: eg $100 or 19.99GBP.
  • You can use a plus or minus symbol before or after the number: eg -20, or 30+.
  • Two—and only two—numbers can be separated using a forward slash: eg 200.5/50.

You also need to note that the maximum number of characters the value can contain is 25; additionally you'll need to consider how this affects the overall character limits normally applied to ad copy.

The Parameter Index

You may have noticed in that the syntax for the ad placeholder I showed earlier used the term param1, instead of just param; this is because it's actually possible place more than one parameter in an ad: You can use up to two. To achieve this, you simply enter the {param1:default} and {param2:default} code into your ad, then specify which placeholder is to get which value using the $paramIndex variable.

Removing an AdParam from a Keyword

If you want to remove the price that you've set for a keyword, then you can simply use the same code as above, but change the service operation from ADD to REMOVE:

// Upload the new AdParam to AdWords
$operation = new AdParamOperation();
$operation->operand = $adParam;
$operation->operator = "REMOVE";
$operations = array($operation);
$adParams = $adParamService->mutate($operations);
?>
Deleting an Ad Parameter

The Advantages of Using AdParams over Modifying Ads

Making small changes to ads has several disadvantages: However small the change, you are creating a new ad, so you loose all the click history, and will have to wait for the approval process to complete again. The AdParam Service doesn't suffer from these problems, as you're still using the same ad; you retain the history and the changes will be live in less than five minutes.

Without AdParams you could try using the API to create many variations of each ad, then just activate the ones with the current price and pause the rest; however, creating ads uses a lot more API units than creating an AdParam (40 vs 0.1), and you would also need to use units for activating and pausing the ads (1 per ad).

Finally, AdParams make it possible for you to build a system that will take your product catalog, select any prices that have changed, then modify all the appropriate ads in AdWords. The exact details about how such a system would work depends on the format of your catalog and how it relates to the structure of your AdWords account, but the code in this tutorial should provide a good starting point that you can develop further.

Update (23 Aug 2012): If you want to check out AdParams, but don't have API access or don't want to develop a full API client yourself, then you can check out the recent addition of Ad Parameters to AdWords Scripts!

Comments

I'm keen to get feedback on my posts, so if you have any questions or comments, then please send me a message and I'll be happy to help.

Ewan

Hi Jan,

Thanks for stopping by my blog; I'll be sure to check out the stuff you've written about the AdWords API as well.

Regards,

Ewan

Reply

Jan

Hi, nice post. I got some C#/.NET code as well here: Google AdWords API - it includes AdParams as well and also gives an idea on what to do with the API and when to use it. Regards, Jan

Reply