Google Ads

Managing Accounts  |  AdWords API  |  Google Developers

This guide explains how to manage Google Ads accounts—including manager, client,
and test accounts—using the AdWords API.

This guide assumes you’re already familiar with Google Ads manager and client
accounts. If you need to brush up on the basics of Google Ads accounts and
access levels, see the Google Ads Help Center manager
account
and access
levels
pages.

Creating and organizing accounts

CustomerService and ManagedCustomerService are the API services used
to create accounts, obtain account information, and manage links between
accounts. For managing
account labels, use
AccountLabelService.

CustomerService

CustomerService provides information about your accounts.
It has a getCustomers() method that takes no arguments and
returns a list of Customer objects containing fields such as customerId,
currencyCode, and dateTimeZone. CustomerService also has a mutate()
method that can be used to update various attributes of a customer, including
the autoTaggingEnabled and conversionTrackingSetting fields.

If no clientCustomerId is specified in a request, the response will contain
multiple entries if more than one account is directly accessible by the
authenticated account. If you only want results for a single account, you must
specify the clientCustomerId in your request.

Example response:


   123456789
   USD
   America/New_York
   myaccount
   false

The Reference documentation contains a list of values for currencies and
timezones.

ManagedCustomerService

ManagedCustomerService also has a get() method and a generic selector.
There are more fields to choose from than with CustomerService–consult the
reference documentation for more details.

In addition to a list of accounts that meet the criteria in your selector,
you’ll also get a list of ManagedCustomerLink objects that describe the
relationship between accounts.


 3
 ManagedCustomerPage
 
    Account Created with MCS
    789
    false
    ZAR
    Pacific/Pago_Pago
 
 
    Google Ads Test Manager Account
    123
    true
    USD
    America/New_York
 
 
    myaccount
    456
    false
    USD
    America/New_York
 
 
    123
    456
 
 
    123
    789
 

ManagedCustomerService is also used to create new accounts. These new
accounts will belong to the effective user, which must also be a manager account.
Here is a sample request:

The field canManageClients is read-only, and is ignored when creating a new
client account.

The account management folder of each client library
contains a code example for creating accounts:

Linking accounts

Linking a manager and client account allows the manager account to make requests on behalf of its client accounts.

ManagedCustomerService is used to manage links between accounts, allowing for
automated management of your account hierarchy:

To link a manager account and a client account:

  1. The manager account must extend an invitation to the client account.
  2. The client must accept the invitation.

Extending invitations

A manager account can invite a client account or another manager account to be managed.

In this scenario, the MANAGER_ID can be either the manager account you’re authenticated
as, or another child manager account within your hierarchy. CLIENT_CID must be a
client or manager account that is not currently managed by a manager account in your hierarchy.

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.PENDING);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.ADD);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

Invitations are extended by sending an ADD operation with a PENDING link
status.

Get pending invitations

Invitations that have not been acted on can be retrieved with
ManagedCustomerService.getPendingInvitations, from either the client or
manager account. After the client responds by accepting or declining, or if the
manager account rescinds the invitation, the invitation is no longer pending.

Only ACTIVE links will be displayed in a ManagedCustomerService.get() call–CANCELLED, REFUSED, and
INACTIVE links are never returned.

The following call returns all pending invitations for the manager account.

PendingInvitationSelector selector = new PendingInvitationSelector();
PendingInvitation[] invitations = managedCustomerService.getPendingInvitations(selector);

You can also set the
managerCustomerIds
and
clientCustomerIds
fields with manager and client account customer IDs (respectively), to return pending
invitations for those accounts. Note that the clientCustomerIds must be managed
through the hierarchy of the effective account to see their links. When the
effective user is a client account, only pending invitations for that account
will be seen.

This request returns PendingInvitations with ManagedCustomer records.
The name, customerId, canManageClients fields will be
populated for both manager and client.

Rescinding invitations

If you send an invitation to manage a client account but then change
your mind, you can rescind the invitation by setting the link status to
CANCELLED in a SET operation, with the effective account as a manager account
that can manage this link.

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.CANCELLED);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

Client declines

The client can also decline the invitation by setting the link status to REFUSED
in a SET operation. The effective user must match or manage as an
administrative owner
the CLIENT_CID in this request.

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.REFUSED);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

Client accepts

The client accepts the invitation by using SET to set the link status to ACTIVE.
As with declining, the effective user must match or manage as an
administrative owner
the CLIENT_CID in this request.

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.ACTIVE);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

When a client or its manager have decided to part ways, the account link can
be terminated: Use SETto set the LinkStatus to INACTIVE.

ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.INACTIVE);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

This can be done as either the manager or client account.

Moving client accounts

You can easily move Google Ads accounts from one manager account to another using
ManagedCustomerService.mutateManager().
Both client and manager accounts can be moved using the mutateManager() method.

MoveOperation op = new MoveOperation();
op.setOldManagerCustomerId(MANAGER_CID);
op.setOperator(Operator.SET);
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.ACTIVE);
link.setManagerCustomerId(NEW_MANAGER_CID);
op.setOperand(link);
managedCustomerService.mutateManager(new MoveOperation[]{op});

The new manager and old manager must both be managed by the effective account.
The link status must be ACTIVE. Use the NEW_MANAGER_CID as the link’s
managerCustomerId and specify the old MANAGER_CID in the MoveOperation‘s
oldManagerCustomerId.

AccountLabelService

Account labels can be used
to help organize and manage accounts. Through AccountLabelService, you can
add, update, or remove labels at the account level. With the API, you can manage
your submanager’s account labels as well.

Manager account limit

Your manager account may eventually reach the limit on the number of
accounts
to which it can be linked.
At that point, you must create a new parallel top-level manager account to
handle new client accounts.

To obtain access to the new top-level manager account, you need to repeat the
OAuth2 authorization
for it. Note that you still use the developer token from your primary manager
account when making API requests.

Authentication

Calls made against the AdWords API require an
approved developer token, and credentials generated in
OAuth2,
for the targeted account.

The simplest approach is to authenticate as a manager
account. Once you’re authenticated, you are granted access to all accounts
under that manager account. Authentication is handled using
OAuth2.

Developer token

When you sign up
for the AdWords API, a developer token is automatically generated for you.
Right after you apply, your token will be pending approval.

While waiting for token approval, you’ll be able to make calls against
test accounts.
After token approval, you’ll be able to target production Google Ads accounts.

OAuth2 credentials

Each request to the AdWords API must be authorized to make changes or
retrieve data for a specified Google Ads account. The
OAuth2 credentials used in
an API call determine which account(s) can be targeted.

Calls made with the credentials of a manager account can target the
manager account, or any accounts for which you have the OAuth2 credentials.
For example, let’s look at a typical Google Ads account hierarchy:

Your developer token can belong to Root Manager Account 1, or even a different
manager account in another hierarchy: It doesn’t affect which accounts you can target,
as long as you supply the client customer ID
for the targeted account.

To make API calls against Client account A, you can use the OAuth2 credentials
of a login associated with Client account A, and set the clientCustomerId request header
to the customer ID of either Client A, Manager Account 2, or Root Manager Account 1.

In this structure, OAuth2 credentials for a login associated with Manager
Account 3 can make calls only against Client Account C. These credentials
cannot make calls targeting Client Account A or B, because it doesn’t manage
them. OAuth2 credentials of a login associated with Root Manager Account 1
can make calls against any of the accounts in the hierarchy.

Calls made with the credentials of a manager account can only target the manager
account or accounts that are beneath it in the hierarchy. Thus, in this hierarchy,
only Root Manager Account 1 can make calls against Client Account D.

If you use either of the manager accounts, then set the clientCustomerId to that manager
account, or one of its child accounts.

Test accounts

Production manager and client accounts establish structure and organization, but
what about testing experimental changes, or testing API calls while you’re
developing—without affecting your production environment? That’s the
purpose of test accounts.

Test accounts allow you to try out new API implementations or account
configurations, prior to implementing the changes in your production
environment.

Test accounts can be set up in a hierarchy and organized just like production
accounts, but provide extra benefits during active development. Particularly,
test accounts:

  • Don’t require an approved developer token, so you can
    start experimenting with the API immediately, even before your application
    is reviewed or approved.
  • Can’t serve ads or interact with your production
    accounts in any way.
  • Can be viewed and manipulated in the Google Ads UI, just like production
    accounts.
  • Have the same restrictions (including rate
    limits
    ) as production accounts.

Because test and production accounts cannot interact in any way, you cannot use
a test account under your existing production manager account. To use test
accounts, you’ll need a new account hierarchy, with a test manager account as
the root.

Test accounts are accessible from the Google Ads UI, and appear with a red
label:

If you don’t see the red Test account label on your Google Ads account
page, then the account is a production account.

Getting started with test accounts

Prior to making API requests to a test account, make sure you already have a
production (non-test) manager account and a developer token, even if the token
is still pending approval.

The first step is creating the root test manager account. All client accounts
created under the test manager account will automatically be test accounts.

Perform these steps to create and use a test manager account:

  1. If you don’t already have an API developer token or haven’t applied for
    one (approval pending):

    1. Create a production manager
      account
      (for example,
      production-manager@mycompany.example.com).
    2. Request a developer token in the
      production manager account.
  2. Create a test manager account
    (for example, test-manager@mycompany.example.com). To create a test account,
    you must have a Google account that is not already linked to
    your production manager account. Create a new Google
    account
    .
  3. Once your test manager account is established, you can proceed to make API
    calls against it. Use the production manager account’s developer token when
    making requests againsts the test manager account.
  4. When requesting an OAuth2 refresh
    token
    ,
    make sure you’re logged in as the test manager account user (for example,
    test-manager@mycompany.example.com).

The table below explains the allowed interactions between different Google Ads account types and
a developer’s token based on its approval status:

Production developer token status Google Ads account type Allowed
Pending Approval Test Yes
Pending Approval Non-Test No
Approved Test Yes
Approved Non-Test Yes

Using OAuth2 with test accounts

To access a test account using OAuth2,
the test manager account user must grant permission to your client application.
Therefore, when requesting
a refresh token
, ensure you’re logged in as the test manager account rather than the production manager account.

When you want to switch from the test manager account to the production manager account,
simply reconfigure the client library to use the production manager account’s
refresh token.

All requests to test accounts should be sent to the same endpoint as production
requests:

https://www.googleapis.com/auth/adwords/

Request and response SOAP headers are identical to those returned in production
accounts
. For
authorization headers, make sure to use your test account credentials.

Additional characteristics of test accounts

There are a few things to keep in mind when working with test accounts:

  • The TargetingIdeaService
    and TrafficEstimatorService
    return dummy data to test accounts.
  • Since test accounts don’t serve ads, they also have no metrics.
    This impacts reports:
    Values for impressions, costs, etc. will all be zero.
  • Test accounts don’t have any associated clicks, so they can’t be used to
    test offline conversion uploads.
  • The DataService won’t
    return bid landscapes for test
    accounts because bid landscapes are based on ads served from the account.
  • You can only have 50 accounts in the hierarchy of a test manager account.
  • You can’t issue mutate operations to
    BudgetOrderService from test accounts
    since the accounts don’t have associated billing.

Developing with test accounts

When signing up for AdWords API access, you may be
asked to demonstrate some features of your application. One such feature is
reporting, which can be difficult to emulate when using only test accounts.

Because test accounts don’t serve impressions, they don’t produce any metrics.
It’s still possible to download structural
reports
—but
you will see only zero-impression rows, which means that segments won’t work.

As a workaround, we suggest displaying fake data. The Token Review
team needs to see that your app can interact with and display report
data. By mocking out the report call (that is, pretending the report call succeeded,
and using a locally stored file containing fake report data), you can add
report data without actually getting it from the API.

Make sure your test report data is in the correct format. For example, if you run a
campaign performance report with date, campaign name, campaign ID,
impressions, clicks, and costs, you’ll get a file like this:

"CAMPAIGN_PERFORMANCE_REPORT (Mar 20, 2013-Mar 23, 2013)"
Day,Campaign,Campaign ID,Impressions,Clicks,Cost
20130320,Widgets,123,1211,19,14.92
20130320,Sprockets,456,300,4,2.92
20130321,Widgets,123,901,12,9.86
20130321,Sprockets,456,340,5,3.86
20130322,Widgets,123,1065,16,11.23
20130322,Sprockets,456,509,6,5.23
20130323,Widgets,123,1005,15,10.12
20130323,Sprockets,456,287,3,1.12

By constructing such a file and storing it locally, your
application can mock the call to the API. When the report is requested, return the
stored file and process that, rather than making an actual API call. You can
create a file like this for each report you want to display.

Testing with production data

You can test using production data in a read-only fashion on your production
accounts if you use the validateOnly
header

in your requests, and you have an approved developer token.

Leave a Reply

Your email address will not be published. Required fields are marked *

Back to top button
Close