Share your feedback about the AdWords API! Take our annual survey.

Account Management Samples

The code samples below provide examples of common account management functions using the AdWords API. Client Library.

Accept an invitation for linking to a manager account

#!/usr/bin/env ruby
# Encoding: utf-8
#
# Copyright:: Copyright 2016, Google Inc. All Rights Reserved.
#
# License:: Licensed under the Apache License, Version 2.0 (the "License");
#           you may not use this file except in compliance with the License.
#           You may obtain a copy of the License at
#
#           http://www.apache.org/licenses/LICENSE-2.0
#
#           Unless required by applicable law or agreed to in writing, software
#           distributed under the License is distributed on an "AS IS" BASIS,
#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
#           implied.
#           See the License for the specific language governing permissions and
#           limitations under the License.
#
# This example accepts a pending invitation to link your AdWords account to a
# Google Merchant Center account.

require 'adwords_api'

def accept_service_link(service_link_id)
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
  # the configuration file or provide your own logger:
  # adwords.logger = Logger.new('adwords_xml.log')

  # Get the CustomerService.
  customer_srv = adwords.service(:CustomerService, API_VERSION)

  # Create the operation to set the status to ACTIVE.
  operation = {
    :operator => 'SET',
    :operand => {
      :service_link_id => service_link_id,
      :service_type => 'MERCHANT_CENTER',
      :link_status => 'ACTIVE'
    }
  }

  # Update the service link.
  mutated_service_links = customer_srv.mutate_service_links([operation])

  # Display the results.
  mutated_service_links.each do |mutated_service_link|
    puts ("Service link with service link ID %d, type '%s' updated to status:" +
        "%s.") % [
          mutated_service_link[:service_link_id],
          mutated_service_link[:service_type],
          mutated_service_link[:link_status]
        ]
  end
end

if __FILE__ == $0
  API_VERSION = :v201809

  begin
    service_link_id = 'INSERT_SERVICE_LINK_ID_HERE'.to_i

    accept_service_link(service_link_id)

  # Authorization error.
  rescue AdsCommon::Errors::OAuth2VerificationRequired => e
    puts "Authorization credentials are not valid. Edit adwords_api.yml for " +
        "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " +
        "to retrieve and store OAuth2 tokens."
    puts "See this wiki page for more details:\n\n  " +
        'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2'

  # HTTP errors.
  rescue AdsCommon::Errors::HttpError => e
    puts "HTTP Error: %s" % e

  # API errors.
  rescue AdwordsApi::Errors::ApiException => e
    puts "Message: %s" % e.message
    puts 'Errors:'
    e.errors.each_with_index do |error, index|
      puts "\tError [%d]:" % (index + 1)
      error.each do |field, value|
        puts "\t\t%s: %s" % [field, value]
      end
    end
  end
end

Create a new account under an AdWords manager

#!/usr/bin/env ruby
# Encoding: utf-8
#
# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
#
# License:: Licensed under the Apache License, Version 2.0 (the "License");
#           you may not use this file except in compliance with the License.
#           You may obtain a copy of the License at
#
#           http://www.apache.org/licenses/LICENSE-2.0
#
#           Unless required by applicable law or agreed to in writing, software
#           distributed under the License is distributed on an "AS IS" BASIS,
#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
#           implied.
#           See the License for the specific language governing permissions and
#           limitations under the License.
#
# This example illustrates how to create an account. Note by default this
# account will only be accessible via parent AdWords manager account.

require 'adwords_api'
require 'adwords_api/utils'

def create_account()
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
  # the configuration file or provide your own logger:
  # adwords.logger = Logger.new('adwords_xml.log')

  managed_customer_srv = adwords.service(:ManagedCustomerService, API_VERSION)

  # Create a local Customer object.
  customer = {
    :name => 'Account created with ManagedCustomerService',
    :currency_code => 'EUR',
    :date_time_zone => 'Europe/London'
  }

  # Prepare operation to create an account.
  operation = {
      :operator => 'ADD',
      :operand => customer
  }

  # Create the account. It is possible to create multiple accounts with one
  # request by sending an array of operations.
  response = managed_customer_srv.mutate([operation])

  response[:value].each do |new_account|
    puts "Account with customer ID '%s' was successfully created." %
        AdwordsApi::Utils.format_id(new_account[:customer_id])
  end
end

if __FILE__ == $0
  API_VERSION = :v201809

  begin
    create_account()

  # Authorization error.
  rescue AdsCommon::Errors::OAuth2VerificationRequired => e
    puts "Authorization credentials are not valid. Edit adwords_api.yml for " +
        "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " +
        "to retrieve and store OAuth2 tokens."
    puts "See this wiki page for more details:\n\n  " +
        'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2'

  # HTTP errors.
  rescue AdsCommon::Errors::HttpError => e
    puts "HTTP Error: %s" % e

  # API errors.
  rescue AdwordsApi::Errors::ApiException => e
    puts "Message: %s" % e.message
    puts 'Errors:'
    e.errors.each_with_index do |error, index|
      puts "\tError [%d]:" % (index + 1)
      error.each do |field, value|
        puts "\t\t%s: %s" % [field, value]
      end
    end
  end
end

Get all account changes during the past 24 hours

#!/usr/bin/env ruby
# Encoding: utf-8
#
# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
#
# License:: Licensed under the Apache License, Version 2.0 (the "License");
#           you may not use this file except in compliance with the License.
#           You may obtain a copy of the License at
#
#           http://www.apache.org/licenses/LICENSE-2.0
#
#           Unless required by applicable law or agreed to in writing, software
#           distributed under the License is distributed on an "AS IS" BASIS,
#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
#           implied.
#           See the License for the specific language governing permissions and
#           limitations under the License.
#
# This example gets all account changes that happened within the last 24 hours,
# for all your campaigns.

require 'adwords_api'
require 'date'
require 'pp'

def get_account_changes()
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
  # the configuration file or provide your own logger:
  # adwords.logger = Logger.new('adwords_xml.log')

  campaign_srv = adwords.service(:CampaignService, API_VERSION)
  customer_sync_srv = adwords.service(:CustomerSyncService, API_VERSION)

  today_at_midnight = DateTime.parse(Date.today.to_s)
  yesterday_at_midnight = DateTime.parse((Date.today - 1).to_s)
  min_date_time = yesterday_at_midnight.strftime("%Y%m%d %H%M%S")
  max_date_time = today_at_midnight.strftime("%Y%m%d %H%M%S")

  # Get all the campaigns for this account.
  selector = {
    :fields => ['Id']
  }
  response = campaign_srv.get(selector)

  campaign_ids = []

  if response and response[:entries]
    campaign_ids = response[:entries].map { |campaign| campaign[:id] }
  else
    raise StandardError, 'No campaigns were found.'
  end

  # Create a selector for CustomerSyncService.
  selector = {
    :campaign_ids => campaign_ids,
    :date_time_range => {
      :min => min_date_time,
      :max => max_date_time
    }
  }

  # Get all account changes for the campaigns.
  campaign_changes = customer_sync_srv.get(selector)

  # Display changes.
  if campaign_changes
    puts "Most recent change: %s" % campaign_changes[:last_change_timestamp]
    campaign_changes[:changed_campaigns].each do |campaign|
      puts "Campaign with ID %d was changed:" % campaign[:campaign_id]
      puts "\tCampaign change status: '%s'" % campaign[:campaign_change_status]
      unless ['NEW', 'FIELDS_UNCHANGED'].include?(
          campaign[:campaign_change_status])
        puts "\tAdded campaign criteria: '%s'" %
            campaign[:added_campaign_criteria].pretty_inspect.chomp
        puts "\tRemoved campaign criteria: '%s'" %
            campaign[:removed_campaign_criteria].pretty_inspect.chomp

        if campaign[:changed_ad_groups]
          campaign[:changed_ad_groups].each do |ad_group|
            puts "\tAd group with ID %d was changed:" % ad_group[:ad_group_id]
            puts "\t\tAd group changed status: '%s'" %
                ad_group[:ad_group_change_status]
            unless ['NEW', 'FIELDS_UNCHANGED'].include?(
                ad_group[:ad_group_change_status])
              puts "\t\tAds changed: '%s'" %
                  ad_group[:changed_ads].pretty_inspect.chomp
              puts "\t\tCriteria changed: '%s'" %
                  ad_group[:changed_criteria].pretty_inspect.chomp
              puts "\t\tCriteria removed: '%s'" %
                  ad_group[:removed_criteria].pretty_inspect.chomp
            end
          end
        end
      end
      puts
    end
  else
    puts 'No account changes were found.'
  end
end

if __FILE__ == $0
  API_VERSION = :v201809

  begin
    get_account_changes()

  # Authorization error.
  rescue AdsCommon::Errors::OAuth2VerificationRequired => e
    puts "Authorization credentials are not valid. Edit adwords_api.yml for " +
        "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " +
        "to retrieve and store OAuth2 tokens."
    puts "See this wiki page for more details:\n\n  " +
        'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2'

  # HTTP errors.
  rescue AdsCommon::Errors::HttpError => e
    puts "HTTP Error: %s" % e

  # API errors.
  rescue AdwordsApi::Errors::ApiException => e
    puts "Message: %s" % e.message
    puts 'Errors:'
    e.errors.each_with_index do |error, index|
      puts "\tError [%d]:" % (index + 1)
      error.each do |field, value|
        puts "\t\t%s: %s" % [field, value]
      end
    end
  end
end

Get the account hierarchy under the current account

#!/usr/bin/env ruby
# Encoding: utf-8
#
# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
#
# License:: Licensed under the Apache License, Version 2.0 (the "License");
#           you may not use this file except in compliance with the License.
#           You may obtain a copy of the License at
#
#           http://www.apache.org/licenses/LICENSE-2.0
#
#           Unless required by applicable law or agreed to in writing, software
#           distributed under the License is distributed on an "AS IS" BASIS,
#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
#           implied.
#           See the License for the specific language governing permissions and
#           limitations under the License.
#
# This example illustrates how to retrieve the account hierarchy under an
# account. This example needs to be run against an AdWords manager account.

require 'adwords_api'
require 'adwords_api/utils'

def get_account_hierarchy()
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
  # the configuration file or provide your own logger:
  # adwords.logger = Logger.new('adwords_xml.log')

  managed_customer_srv = adwords.service(:ManagedCustomerService, API_VERSION)

  # Get the account hierarchy for this account.
  selector = {
    :fields => ['CustomerId',  'Name'],
    :paging => {
      :start_index => 0,
      :number_results => PAGE_SIZE
    }
  }

  # Set initial values
  offset, page = 0, {}

  accounts = {}
  child_links = {}
  parent_links = {}
  root_account = nil

  begin
    page = managed_customer_srv.get(selector)

    if page and page[:entries]
      if page[:links]
        page[:links].each do |link|
          unless child_links.include?(link[:manager_customer_id])
            child_links[link[:manager_customer_id]] = []
          end
          child_links[link[:manager_customer_id]] << link
          unless parent_links.include?(link[:client_customer_id])
            parent_links[link[:client_customer_id]] = []
          end
          parent_links[link[:client_customer_id]] << link
        end
      end

      page[:entries].each do |account|
        accounts[account[:customer_id]] = account
        unless parent_links.include?(account[:customer_id])
          root_account = account
        end
      end

      # Increment values to request the next page.
      offset += PAGE_SIZE
      selector[:paging][:start_index] = offset
    end
  end while page[:total_num_entries] > offset

  if root_account.nil?
    puts "Unable to determine a root account."
  else
    puts "CustomerId, Name"
    display_account_tree(root_account, accounts, child_links, 0)
  end
end

def display_account_tree(account, accounts, links, depth)
  prefix = '-' * depth * 2
  puts '%s%s, %s' % [prefix, account[:customer_id], account[:name]]
  if links.include?(account[:customer_id])
    links[account[:customer_id]].each do |child_link|
      child_account = accounts[child_link[:client_customer_id]]
      display_account_tree(child_account, accounts, links, depth + 1)
    end
  end
end

if __FILE__ == $0
  API_VERSION = :v201809
  PAGE_SIZE = 500

  begin
    get_account_hierarchy()

  # Authorization error.
  rescue AdsCommon::Errors::OAuth2VerificationRequired => e
    puts "Authorization credentials are not valid. Edit adwords_api.yml for " +
        "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " +
        "to retrieve and store OAuth2 tokens."
    puts "See this wiki page for more details:\n\n  " +
        'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2'

  # HTTP errors.
  rescue AdsCommon::Errors::HttpError => e
    puts "HTTP Error: %s" % e

  # API errors.
  rescue AdwordsApi::Errors::ApiException => e
    puts "Message: %s" % e.message
    puts 'Errors:'
    e.errors.each_with_index do |error, index|
      puts "\tError [%d]:" % (index + 1)
      error.each do |field, value|
        puts "\t\t%s: %s" % [field, value]
      end
    end
  end
end

Send feedback about...

AdWords API
AdWords API
Need help? Visit our support page.