This guide will present an overview of CustomerService and ManagedCustomerService which are used to obtain AdWords customer account information, create accounts and manage the links between accounts.
Managing account links
With v201302, we’ve introduced the ability to make changes to the links in your account hierarchy - this allows automated management of your My Client Center (MCC) accounts as well as client accounts (accounts that serve ads).
- ManagedCustomerService.mutateLink is used to invite a client account, rescind the invitation, decline and accept (as a client account) as well as terminate links between an MCC account and a client account.
- ManagedCustomerService.getPendingInvitations lets you see all invitations that have not yet been accepted or declined.
- ManagedCustomerService.mutateManager lets you change the manager of a client account from one MCC to another.
To create a link between an MCC and a new client account:
- The MCC must ADD a PENDING link
- The client must SET it to ACTIVE
This allows the MCC to make requests on their behalf.
Manager extends invitation
An MCC account can invite a client account or MCC to be managed by an MCC. In this scenario, the MANAGER_ID can either be the MCC you are authenticated with, or another sub-MCC within your account hierarchy. CLIENT_CID must be a client or MCC account that is not currently managed by an MCC 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.
getPendingInvitations
Invitations that have not been acted on can be retrieved with ManagedCustomerService.getPendingInvitations from either the client side or the MCC side. Once the client responds by accepting or declining, or the MCC 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 effective account. You can also set the managerCustomerIds and clientCustomerIds fields with MCC 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.
Manager rescinds invitation
If you’ve extended an invitation to manage a client account and you’ve changed your mind, you can rescind the invitation by setting the link status to CANCELLED in a SET operation with the effective account as an MCC that could 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});
Manager OR client terminates links
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 MCC or the client.
MutateManager
You can easily move client accounts from one MCC to another using ManagedCustomerService.mutateManager.
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.
MutateManager cannot be used to move an MCC account under a different manager. To move an MCC within your hierarchy, you must terminate the existing link, invite the target MCC under its new manager and accept on its behalf.
Managing accounts
CustomerService
CustomerService is designed to provide Customer information for a single customer at a time. It has a single method (get) that takes no arguments and returns a Customer record containing fields such as customerId, currencyCode, dateTimeZone among its fields. The effective account is always returned. When you don’t specify a clientCustomerId field, the authenticated user will be used to determine an account. You can specify a clientCustomerId when authenticating as an MCC to obtain account 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, but it takes a generic selector. There are more fields to choose from than with CustomerService - consult the documentation for more details. Note that unlike CustomerService, you’ll need to ask for the fields you want, just like with other services that use generic selectors.
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 MCC</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 an MCC account. See below for an example request:
<operations>
<operator>ADD</operator>
<operand>
<name>Foo</name>
<currencyCode>USD</currencyCode>
<dateTimeZone>America/New_York</dateTimeZone>
</operand>
</operations>
And 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.