The AdWords API is no longer supported. Use the Google Ads API instead.

Account Management Samples

Stay organized with collections Save and categorize content based on your preferences.

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/perl -w
#
# Copyright 2017, Google Inc. All Rights Reserved.
#
# 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.

use strict;

use lib "../../../lib";
use utf8;

use Google::Ads::AdWords::Client;
use Google::Ads::AdWords::Logging;
use Google::Ads::AdWords::v201809::ServiceLink;
use Google::Ads::AdWords::v201809::ServiceLinkOperation;

use Cwd qw(abs_path);
use Data::Uniqid qw(uniqid);

# Replace with valid values of your account.
my $service_link_id = "INSERT_SERVICE_LINK_ID_HERE";

# Example main subroutine.
sub accept_service_link {
  my $client          = shift;
  my $service_link_id = shift;

  my $service_link = Google::Ads::AdWords::v201809::ServiceLink->new({
    serviceLinkId => $service_link_id,
    serviceType   => "MERCHANT_CENTER",
    linkStatus    => "ACTIVE"
  });

  # Create the operation to set the status to ACTIVE.
  my $op = Google::Ads::AdWords::v201809::ServiceLinkOperation->new({
    operator => "SET",
    operand  => $service_link
  });

  # Update the service link.
  my $mutated_service_links =
    $client->CustomerService->mutateServiceLinks({operations => [$op]});

  # Display the results.
  foreach my $mutated_service_link ($mutated_service_links) {
    printf(
      "Service link with service link ID %d, " .
        "type '%s' updated to status: %s.\n",
      $mutated_service_link->get_serviceLinkId(),
      $mutated_service_link->get_serviceType(),
      $mutated_service_link->get_linkStatus());

  }

  return 1;
}

# Don't run the example if the file is being included.
if (abs_path($0) ne abs_path(__FILE__)) {
  return 1;
}

# Log SOAP XML request, response and API errors.
Google::Ads::AdWords::Logging::enable_all_logging();

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201809"});

# By default examples are set to die on any server returned fault.
$client->set_die_on_faults(1);

# Call the example
accept_service_link($client, $service_link_id);

accept_service_link.pl

Create a new account under an AdWords manager

#!/usr/bin/perl -w
#
# Copyright 2017, Google Inc. All Rights Reserved.
#
# 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. By default, this account
# will only be visible via the parent AdWords manager account.

use strict;

use lib "../../../lib";
use utf8;

use Google::Ads::AdWords::Client;
use Google::Ads::AdWords::Logging;
use Google::Ads::AdWords::v201809::ManagedCustomer;
use Google::Ads::AdWords::v201809::ManagedCustomerOperation;

use Cwd qw(abs_path);
use Data::Uniqid qw(uniqid);

# Example main subroutine.
sub create_account {
  my $client = shift;

  # Create an account object with a currencyCode and a dateTimeZone
  # See https://developers.google.com/adwords/api/docs/appendix/currencycodes
  # and https://developers.google.com/adwords/api/docs/appendix/timezones
  my $account = Google::Ads::AdWords::v201809::ManagedCustomer->new({
      name         => "Managed Account #" . uniqid(),
      currencyCode => "USD",
      dateTimeZone => "America/New_York",
  });

  # Create the operation
  my $operation = Google::Ads::AdWords::v201809::ManagedCustomerOperation->new({
      operator => "ADD",
      operand  => $account
  });

  # Perform the operation. It is possible to create multiple accounts with one
  # request by sending multiple operations.
  my $response =
    $client->ManagedCustomerService->mutate({operations => [$operation],});

  if ($response) {
    my $new_account = $response->get_value();
    print "Account with customer ID ", $new_account->get_customerId(),
      " was created.\n";
  } else {
    print "No account was created.\n";
  }

  return 1;
}

# Don't run the example if the file is being included.
if (abs_path($0) ne abs_path(__FILE__)) {
  return 1;
}

# Log SOAP XML request, response and API errors.
Google::Ads::AdWords::Logging::enable_all_logging();

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201809"});

# By default examples are set to die on any server returned fault.
$client->set_die_on_faults(1);

# Call the example
create_account($client);


create_account.pl

Get all account changes during the past 24 hours

#!/usr/bin/perl -w
#
# Copyright 2017, Google Inc. All Rights Reserved.
#
# 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.

use strict;
use lib "../../../lib";
use utf8;

use Google::Ads::AdWords::Client;
use Google::Ads::AdWords::Logging;
use Google::Ads::AdWords::v201809::CustomerSyncSelector;
use Google::Ads::AdWords::v201809::DateTimeRange;
use Google::Ads::AdWords::v201809::Selector;

use Cwd qw(abs_path);

sub get_formatted_list ($);

# Example main subroutine.
sub get_account_changes {
  my $client = shift;

  # A date range of last 24 hours.
  my ($sec, $min, $hour, $mday, $mon, $year) = localtime(time - (60 * 60 * 24));
  my $min_date_time = sprintf(
    "%d%02d%02d %02d%02d%02d",
    ($year + 1900),
    ($mon + 1),
    $mday, $hour, $min, $sec
  );
  ($sec, $min, $hour, $mday, $mon, $year) = localtime(time);
  my $max_date_time = sprintf(
    "%d%02d%02d %02d%02d%02d",
    ($year + 1900),
    ($mon + 1),
    $mday, $hour, $min, $sec
  );

  # Get a list of all campaign ids.
  my @campaign_ids = ();
  my $campaigns    = $client->CampaignService()->get({
      serviceSelector =>
        Google::Ads::AdWords::v201809::Selector->new({fields => ["Id"]})});
  if ($campaigns->get_entries()) {
    foreach my $campaign (@{$campaigns->get_entries()}) {
      push @campaign_ids, $campaign->get_id();
    }
  }

  # Create date time range.
  my $date_time_range = Google::Ads::AdWords::v201809::DateTimeRange->new({
      min => $min_date_time,
      max => $max_date_time
  });

  # Create selector.
  my $selector = Google::Ads::AdWords::v201809::CustomerSyncSelector->new({
      dateTimeRange => $date_time_range,
      campaignIds   => \@campaign_ids
  });

  # Get all account changes for campaign.
  my $account_changes =
    $client->CustomerSyncService()->get({selector => $selector});

  # Display changes.
  if ($account_changes && $account_changes->get_changedCampaigns()) {
    printf "Displaying changes up to: %s\n",
      $account_changes->get_lastChangeTimestamp();
    foreach my $campaign_changes (@{$account_changes->get_changedCampaigns()}) {
      printf "Campaign with id \"%d\" was changed:\n",
        $campaign_changes->get_campaignId();
      printf "\tCampaign changed status: %s\n",
        $campaign_changes->get_campaignChangeStatus();
      if ($campaign_changes->get_campaignChangeStatus() ne "NEW") {
        printf "\tAdded campaign criteria: %s\n",
          get_formatted_list($campaign_changes->get_addedCampaignCriteria());
        printf "\tRemoved campaign criteria: %s\n",
          get_formatted_list($campaign_changes->get_removedCampaignCriteria());

        if ($campaign_changes->get_changedAdGroups()) {
          foreach
            my $ad_group_changes (@{$campaign_changes->get_changedAdGroups()})
          {
            printf "\tAd group with id \"%d\" was changed:\n",
              $ad_group_changes->get_adGroupId();
            printf "\t\tAd group changed status: %s\n",
              $ad_group_changes->get_adGroupChangeStatus();
            if ($ad_group_changes->get_adGroupChangeStatus() ne "NEW") {
              printf "\t\tAds changed: %s\n",
                get_formatted_list($ad_group_changes->get_changedAds());
              printf "\t\tCriteria changed: %s\n",
                get_formatted_list($ad_group_changes->get_changedCriteria());
              printf "\t\tCriteria removed: %s\n",
                get_formatted_list($ad_group_changes->get_removedCriteria());
            }
          }
        }
      }
      print "\n";
    }
  } else {
    print "No account changes were found.\n";
  }

  return 1;
}

sub get_formatted_list ($) {
  my $list = $_[0];
  if (!$list) {
    return "{ }";
  }
  return "{ " . join(", ", @{$list}) . " }";
}

# Don't run the example if the file is being included.
if (abs_path($0) ne abs_path(__FILE__)) {
  return 1;
}

# Log SOAP XML request, response and API errors.
Google::Ads::AdWords::Logging::enable_all_logging();

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201809"});

# By default examples are set to die on any server returned fault.
$client->set_die_on_faults(1);

# Call the example
get_account_changes($client);

get_account_changes.pl

Get the account hierarchy under the current account

#!/usr/bin/perl -w
#
# Copyright 2017, Google Inc. All Rights Reserved.
#
# 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 the account hierarchy under the current account.
#
# Note: This example won't work if your token is not approved and you are only
# targeting test accounts. See
# https://developers.google.com/adwords/api/docs/test-accounts

use strict;
use lib "../../../lib";
use utf8;

use Google::Ads::AdWords::Client;
use Google::Ads::AdWords::Logging;
use Google::Ads::AdWords::v201809::Paging;
use Google::Ads::AdWords::v201809::Selector;

use Cwd qw(abs_path);

use constant PAGE_SIZE => 500;

sub display_customers_tree;

# Example main subroutine.
sub get_account_hierarchy {
  my $client = shift;

  # Create selector.
  my $paging = Google::Ads::AdWords::v201809::Paging->new({
      startIndex    => 0,
      numberResults => PAGE_SIZE
  });
  my $selector = Google::Ads::AdWords::v201809::Selector->new({
      fields => ["Name", "CustomerId"],
      paging => $paging
  });

  my $page;
  my $customers = {};
  my $root_account;
  my $child_links  = {};
  my $parent_links = {};
  do {
    # Get account graph.
    $page =
      $client->ManagedCustomerService()->get({serviceSelector => $selector});

    # Display accounts graph.
    if ($page->get_entries()) {
      # Create map from customerId to parent and child links.
      if ($page->get_links()) {
        foreach my $link (@{$page->get_links()}) {
          if (!$child_links->{$link->get_managerCustomerId()}) {
            $child_links->{$link->get_managerCustomerId()} = [];
          }
          push @{$child_links->{$link->get_managerCustomerId()}}, $link;
          if (!$parent_links->{$link->get_clientCustomerId()}) {
            $parent_links->{$link->get_clientCustomerId()} = [];
          }
          push @{$parent_links->{$link->get_clientCustomerId()}}, $link;
        }
      }
      # Create map from customerID to account, and find root account.
      foreach my $customer (@{$page->get_entries()}) {
        $customers->{$customer->get_customerId()} = $customer;
        if (!$parent_links->{$customer->get_customerId()}) {
          $root_account = $customer;
        }
      }
    }
    $paging->set_startIndex($paging->get_startIndex() + PAGE_SIZE);
  } while ($paging->get_startIndex() < $page->get_totalNumEntries());

  # Display customers tree.
  print "CustomerId, Name\n";
  display_customers_tree($root_account, undef, $customers, $child_links, 0);

  return 1;
}

# Displays an account tree, starting at the account and link provided, and
# recursing to all child accounts.
sub display_customers_tree {
  my ($customer, $link, $customers, $links, $depth) = @_;
  print "-" x ($depth * 2);
  print " ";
  print $customer->get_customerId();
  print ", " .
    ($customer->get_name() ne "" ? $customer->get_name() : "(no name)");
  print "\n";
  if ($links->{$customer->get_customerId()}) {
    foreach my $child_link (@{$links->{$customer->get_customerId()}}) {
      my $child_account = $customers->{$child_link->get_clientCustomerId()};
      display_customers_tree($child_account, $child_link, $customers, $links,
        $depth + 1);
    }
  }
}

# Don't run the example if the file is being included.
if (abs_path($0) ne abs_path(__FILE__)) {
  return 1;
}

# Log SOAP XML request, response and API errors.
Google::Ads::AdWords::Logging::enable_all_logging();

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201809"});

# By default examples are set to die on any server returned fault.
$client->set_die_on_faults(1);

# Call the example
get_account_hierarchy($client);

get_account_hierarchy.pl