AdWords API
Hide

Managing Customer Accounts

This guide gives an overview of CustomerService and ManagedCustomerService which are used to obtain AdWords account information, create accounts, and manage the links between accounts.

The AdWords API allows you to make changes to the links in your account hierarchy--this allows automated management of your manager accounts as well as client accounts (accounts that serve ads). Employing a hierarchy can ease management of a large number of accounts.

To manage links between accounts, use ManagedCustomerService:

To create a link between a manager account and a new client account:

  1. The manager account must ADD a PENDING link.
  2. The client must SET it to ACTIVE.

This allows the manager account to make requests on their behalf.

Extending invitations

A manager account can invite a client account or another manager account to agree to be managed. In this scenario, the MANAGER_ID can either be the manager account you are 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. Once the client responds by accepting or declining, or the manager account rescinds the invitation, they are no longer pending. Only ACTIVE links will be displayed in a ManagedCustomerService.get call--CANCELLED, REFUSED, and INACTIVE links will never be returned.

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

This call will return all pending invitations for the manager account. 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. Name, login, companyName, customerId, canManageClients fields will be populated for both manager and client.

Rescinding invitations

If you've extended an invitation to manage a client account but then changed 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 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 must SET the link status to ACTIVE to complete the account link process. As with declining, the effective user must match or manage 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 their manager have decided to part ways, the account link can be terminated by SETting 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 AdWords 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.

Managing accounts

CustomerService

CustomerService is designed to provide customer information for a single customer at a time. It has a get method that takes no arguments and returns a Customer record containing fields such as customerId, currencyCode, and dateTimeZone. There is also a mutate method that can be used to update both autoTaggingEnabled and conversionTrackingSetting fields of a customer.

The authenticated account is always returned. You must specify a clientCustomerId when authenticating as a manager account to obtain info for a specific account.

Example response:

<rval>
   <customerId>123456789</customerId>
   <currencyCode>USD</currencyCode>
   <dateTimeZone>America/New_York</dateTimeZone>
   <descriptiveName>myaccount</descriptiveName>
   <canManageClients>false</canManageClients>
</rval>

Our 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.

<rval>
 <totalNumEntries>3</totalNumEntries>
 <Page.Type>ManagedCustomerPage</Page.Type>
 <entries>
    <name>Account Created with MCS</name>
    <login/>
    <companyName/>
    <customerId>789</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>ZAR</currencyCode>
    <dateTimeZone>Pacific/Pago_Pago</dateTimeZone>
 </entries>
 <entries>
    <name>Adwords Test Manager Account</name>
    <login>[email protected]</login>
    <companyName/>
    <customerId>123</customerId>
    <canManageClients>true</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
 </entries>
 <entries>
    <name>myaccount</name>
    <login>[email protected]</login>
    <companyName/>
    <customerId>456</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
 </entries>
 <links>
    <managerCustomerId>123</managerCustomerId>
    <clientCustomerId>456</clientCustomerId>
 </links>
 <links>
    <managerCustomerId>123</managerCustomerId>
    <clientCustomerId>789</clientCustomerId>
 </links>
</rval>

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

<operations>
  <operator>ADD</operator>
  <operand>
    <name>Foo</name>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
  </operand>
</operations>

Example response:

<rval>
  <value>
    <name>Foo</name>
    <customerId>9876543210</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
  </value>
</rval>

Fields such as companyName, login, and canManageClients are read-only and will be ignored when creating a new Customer account. ManagedCustomerService cannot be used to update a Customer account once it has been created.

Manager account limits

There are some limitations that you should be aware of when working with manager accounts.

Limitation Description Recommendation
An AdWords account can be managed by up to 5 manager accounts. If an AdWords account is already managed by 5 manager accounts, that AdWords account cannot add another manager account. For each AdWords account, check if your manager account can be added, or can replace one of the existing 5 manager accounts.
From the top to bottom (top-level manager account to bottommost AdWords account), there can be no more than 6 levels in a hierarchy. If a hierarchy you're trying to manage already has 6 levels, linking another top-level manager account will not work since then there would be 7 levels and thus exceed the limit. Reduce the hierarchy from 6 to 5 levels first, by moving either a manager account or the bottommost AdWords accounts up one level.
A manager account can't be directly managed by more than 1 other manager account. Most practical use cases can be addressed with either a single-level structure or a two-tiered, one manager-per-AdWords-account hierarchy, without needing to have multiple parent manager accounts managing the same child account. See this help center article for more information about linking manager accounts.
Maximum of 20 pending manager account invitations. If you are inviting AdWords accounts to a manager account, keep in mind there is a limit of 20 pending invitations. If you've reached this limit, then at least one pending invitation must be accepted or declined before you can send more. Send and accept invitations in batches. If you must invite a large number of AdWords accounts to a manager account, consider retrieving OAuth 2.0 refresh tokens for each account ahead of time.

AdWords accounts rarely come close to these limitations. If an AdWords account that you need to manage has already maxed out on any of the above limits, you'll have to fix the issues prior to linking that account.

In addition to these structural limits, be careful to not exceed operational rate limits.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.

Send feedback about...

This page
Documentation feedback
AdWords API
Product feedback