The AdWords API is regularly updated by Google with their latest capabilities. While it's great not to have to wait too long to get access to new capabilities, it comes with a downside too: AdWords Scripts may stop working on the day Scripts switch to using a newer version of the API.
The reason is that new API version may rename or remove metrics and attributes. An AdWords Script that is not updated with these latest names will stop working.
You can find the release dates of new API versions here and the table looks like this:
The release date is not always the date that AdWords Scripts start to use the newer version. As a result, it is very tricky to ensure that scripts you write continue to work.
Luckily there is a solution and it's as simple as telling your script which API version it should use by including the optional apiVersion argument.
A reporting call without the API version:
var report2 = AdWordsApp.report( 'SELECT AdGroupId, Id, KeywordText, Impressions, Clicks ' + 'FROM KEYWORDS_PERFORMANCE_REPORT ' + 'DURING 20130101,20130301');
And that same call with the API version:
var report2 = AdWordsApp.report( 'SELECT AdGroupId, Id, KeywordText, Impressions, Clicks ' + 'FROM KEYWORDS_PERFORMANCE_REPORT ' + 'DURING 20130101,20130301', { apiVersion: 'v201605' });
By telling the script which API version to use, you guarantee that it will continue to work on the day that Google switches the default the a new version because you now control the switch that tells the script when your code has been updated and should start using a new API version.
You'll still need to do the migration at some point, but you'll have several months to do so. The sunset date in the table above indicates the final day that a script can use a particular API version. After that date, the old version will cease to work.
Note that you do NOT have to go through every API version. It's completely acceptable to skip a version if you don't need any of its capabilities. For example, say you were using v201609. Since it doesn't sunset until October 2, 2017, you could have waited for the release of v201708 on August 9, 2017, and skipped the 2 API versions in between.
The scripts in the Optmyzr Enhanced Scripts library handle all of these API transitions automatically for our users so if you'd rather not deal with API versions, it's a great solution to try. (Optmyzr is my employer)
