Shopping Campaigns

A Shopping campaign is a campaign type that helps promote your products by giving users detailed product information before they even click your ad. Ads in Shopping campaigns show users a photo of your product, plus a title, price, store name, and more.

This guide describes how to set up and manage Shopping campaigns in the AdWords API.

Linking your Merchant Center and AdWords accounts

Before you can create a Shopping campaign, you need to first link your AdWords account to your Google Merchant Center account. This involves two steps:

1. Send an invitation from your Merchant Center account to your AdWords account.
2. Accept the invitation in your AdWords account.

Send an invitation from your Merchant Center account

You can use the Merchant Center user interface to send this invitation, or use the Content API for Shopping to update the adwordsLinks of your Account.

Managing invitations in your AdWords account

Starting with v201609, you can use getServiceLinks and mutateServiceLinks of CustomerService to retrieve, accept, and reject links between your AdWords account and other services, including Merchant Center.

To retrieve all links to your account, simply call getServiceLinks with a predicate on serviceType = MERCHANT_CENTER as follows:

Java

// Get the CustomerService.
CustomerServiceInterface customerService =
    adWordsServices.get(session, CustomerServiceInterface.class);

// Create a selector that filters by service type.
Selector selector =
    new SelectorBuilder()
        .fields("ServiceType")
        .equals("ServiceType", ServiceType.MERCHANT_CENTER.getValue())
        .build();

// Get the service links.
ServiceLink[] serviceLinks = customerService.getServiceLinks(selector);

// Display the results.
if (serviceLinks != null) {
  for (ServiceLink serviceLink : serviceLinks) {
    System.out.printf(
        "Found service link with service link ID %d, type %s, name '%s', and status %s.%n",
        serviceLink.getServiceLinkId(),
        serviceLink.getServiceType(),
        serviceLink.getName(),
        serviceLink.getLinkStatus());
  }
} else {
  System.out.println("No service links found.");
}

To accept an invitation, call mutateServiceLinks and pass a SET operation that changes the linkStatus from PENDING to ACTIVE. Make sure you set the serviceType and the serviceLinkId on the operand.

Java

// Get the CustomerService.
CustomerServiceInterface customerService =
    adWordsServices.get(session, CustomerServiceInterface.class);

// Create the operation to set the status to ACTIVE.
ServiceLinkOperation op = new ServiceLinkOperation();
op.setOperator(Operator.SET);
ServiceLink serviceLink = new ServiceLink();
serviceLink.setServiceLinkId(serviceLinkId);
serviceLink.setServiceType(ServiceType.MERCHANT_CENTER);
serviceLink.setLinkStatus(ServiceLinkLinkStatus.ACTIVE);
op.setOperand(serviceLink);

// Update the service link.
ServiceLink[] mutatedServiceLinks =
    customerService.mutateServiceLinks(new ServiceLinkOperation[] {op});

// Display the results.
for (ServiceLink mutatedServiceLink : mutatedServiceLinks) {
  System.out.printf(
      "Service link with service link ID %d, type '%s' updated to status: %s.%n",
      mutatedServiceLink.getServiceLinkId(),
      mutatedServiceLink.getServiceType(),
      mutatedServiceLink.getLinkStatus());
}

To reject an invitation, call mutateServiceLinks and pass a REMOVE operation with an operand that has serviceType and serviceLinkId set.

Java

// Get the CustomerService.
CustomerServiceInterface customerService =
    adWordsServices.get(session, CustomerServiceInterface.class);

// Create the operation to remove the service link.
ServiceLinkOperation op = new ServiceLinkOperation();
op.setOperator(Operator.REMOVE);
ServiceLink serviceLink = new ServiceLink();
serviceLink.setServiceLinkId(serviceLinkId);
serviceLink.setServiceType(ServiceType.MERCHANT_CENTER);
op.setOperand(serviceLink);

// Remove the service link.
ServiceLink[] mutatedServiceLinks =
    customerService.mutateServiceLinks(new ServiceLinkOperation[] {op});

// Display the results.
for (ServiceLink mutatedServiceLink : mutatedServiceLinks) {
  System.out.printf(
      "Service link with service link ID %d and type '%s' was removed.%n",
      mutatedServiceLink.getServiceLinkId(), mutatedServiceLink.getServiceType());
}

Creating a Shopping campaign

Note: This guide uses the CampaignService and AdGroupCriterionService for ease of explanation, but you may perform the same operations using BatchJobService. See the batch jobs guide for more details.

When creating a Shopping campaign, you set the budgets, bids, and settings. The simplest type of Shopping campaign has one bid for all products.

There are two steps unique to setting up a Shopping campaign:

1. Setting the campaign's advertisingChannelType to SHOPPING.

2. Creating a ShoppingSetting and add it to the campaign.

Both steps are shown in the code below.

Campaign campaign = new Campaign();
campaign.setAdvertisingChannelType(AdvertisingChannelType.SHOPPING);
// Recommendation: Set the campaign to PAUSED when creating it to stop
// the ads from immediately serving. Set to ENABLED once you've added
// targeting and the ads are ready to serve.
campaign.setStatus(CampaignStatus.PAUSED);

ShoppingSetting shoppingSetting = new ShoppingSetting();
shoppingSetting.setMerchantId(MERCHANT_ID);
shoppingSetting.setSalesCountry("GB");
shoppingSetting.setCampaignPriority(0);
shoppingSetting.setEnableLocal(true);
campaign.setSettings(new Setting[] {shoppingSetting});

As shown in the sample above, a ShoppingSetting has the following properties:

merchantId (required)

The Merchant Center Account ID that your products belong to.

salesCountry (required)

Only products with a matching target country in Merchant Center will be selected. Note that this does not affect ads targeting.

campaignPriority (optional, default: 0)

Either 0, 1, or 2. This determines which campaign should take priority when more than one campaign uses the same Merchant Center data feed. The campaign with the higher priority will be selected. If two campaigns have the same priority, then each ad will be covered by the one that sets the highest bid for the product.

enableLocal (optional, default: false)

If set to true, this flag enables local inventory ads in your Shopping campaigns.

purchasePlatform (optional, default: MERCHANT)

Indicates the platform on which a shopping product can be purchased. Available starting with v201705, and only if your Merchant Center account is enabled for Purchases on Google.

Creating a Shopping ad group and ads

In order to serve ads for your Shopping campaign, you must create an AdGroup with at least one ad in the ad group.

Shopping campaigns support two types of ad groups:

• SHOPPING_PRODUCT_ADS: This is the default ad group type for shopping campaigns, serving standard product ads.
• SHOPPING_SHOWCASE_ADS: This ad group type is limited to serving Showcase ads in shopping results. To create one, you need to:
  1. Set the adGroupType field of your ad group to SHOPPING_SHOWCASE_ADS.
  2. Set the biddingStrategyType of your ad group's biddingStrategyConfiguration to MANUAL_CPC or ENHANCED_CPC.

Note: The type of an ad group cannot be changed once created.

Note: You need to use the new AdWords UI to work with Showcase ad groups. See our help center article for more details.

Once you create the required type of ad group, complete the basic setup of your campaign by adding a ProductAd or a ShowcaseAd to your ad group.

Next, you need to decide which products to include and how much to bid for them.

Partitioning

The full power of Shopping campaigns comes from dividing your product inventory along multiple dimensions and working with product groups individually. Consider the diagram below, where the products have been broadly divided as Electronics (which is further divided by brand), Toys and "Everything else" (which is further divided by Used status)

You create this structure as a tree. Each level of the tree represents a partition.

Each node in the tree is either a subdivision or a unit. A subdivision introduces a new level in the tree, while units are leaves of the tree. Each subdivision must always be completely partitioned, so it must contain a unit type representing Other. In the example, the root, Category: Electronics and Category: (Other) nodes are subdivisions.

Nodes are objects of the ProductPartition class, a subclass of the Criterion class. ProductPartitions are linked to the AdGroup with either BiddableAdGroupCriterion or NegativeAdGroupCriterion.

Note: A ProductPartition tree can be no more than seven levels deep.

The combination of ProductPartition type and AdGroupCriterion type produces the following effects:

ProductPartition Type	AdGroupCriterion Type	Effect
UNIT	BiddableAdGroupCriterion	A bid for items matching this leaf of the tree.
UNIT	NegativeAdGroupCriterion	This combination indicates that you do not wish to bid for this particular leaf in this ad group, but that other ad groups and (lower priority) campaigns may do so.

Other combinations result in an error.

A ProductPartition also has a caseValue which can be any of several subclasses of the ProductDimension type. A ProductDimension represents the values associated with your products, such as brand, category, or condition. A full description of the available ProductDimension types is available in the reference documentation.

Each immediate child of a subdivision must have a caseValue of the same ProductDimension subtype. Only the root node doesn't have a caseValue.

ProductPartition root = new ProductPartition();
root.setPartitionType(ProductPartitionType.SUBDIVISION);
root.setId(-1);

ProductPartition node1 = new ProductPartition();
node1.setPartitionType(ProductPartitionType.UNIT);
node1.setCaseValue(new ProductBrand(null, "Brand A"));
node1.setParentCriterionId(root.getId());

Remember that each subdivision must contain an "empty" caseValue of the correct type, representing "all other values".

ProductPartition node2 = new ProductPartition();
node2.setPartitionType(ProductPartitionType.UNIT);
node2.setCaseValue(new ProductBrand());
node2.setParentCriterionId(root.getId());

Temporary IDs

Criteria are not assigned IDs until the mutate request that creates them is processed by the server. However, a ProductPartition is invalid until it is complete, so whenever you create a subdivision you must also create at least one of its children in the same operation.

To allow you to set the parentCriterionId for the child nodes, you can use temporary criterion IDs. These are locally unique (rather than globally unique) identifiers that apply only within the context of a single mutate request. Any negative integer can be used as a temporary ID. In the sample code above, the ID of the root ProductPartition is set to -1.

When the request is processed, each Criterion is assigned a positive global ID as usual.

Product dimensions

The following ProductDimension types are available for Shopping campaigns:

• ProductBiddingCategory
• ProductBrand
• ProductCanonicalCondition
• ProductCustomAttribute
• ProductOfferId
• ProductType
• ProductChannel
• ProductChannelExclusivity

ProductBiddingCategory, ProductCustomAttribute, and ProductType are further split into subtypes. When subdividing by one of these types, each caseValue for that subdivision must also be of the same subtype.

ProductBiddingCategory and ProductType are hierarchical, with the subtypes representing depth within the hierarchy. The category Media is a BIDDING_CATEGORY_L1 while Books is a BIDDING_CATEGORY_L2 and has Media as its parent. You cannot subdivide by a caseValue unless the parent has already been subdivided further up the tree.

For example, you cannot have the Books category as a node directly under the root, nor can Books be directly under Electronics, since Electronics is not the parent of Books.

ProductCustomAttribute is not hierarchical. Instead, the subtypes CUSTOM_ATTRIBUTE_0 through CUSTOM_ATTRIBUTE_4 map to the values custom attribute 0 to custom attribute 4 in Merchant Center.

You can specify local, online, or both channels through the product dimensions ProductChannel and ProductChannelExclusivity.

Bidding categories

The values for the ProductBiddingCategory type are fixed IDs. You can retrieve the full set of bidding categories from the ConstantDataService method getProductBiddingCategoryData. We highly recommended that you cache the results of this call as the data set is large and changes infrequently.

Modifying existing ProductPartition trees

The tree must always remain complete, so any mutate operation that would make a tree invalid must be part of the same request as an operation that fixes it again. To be valid, all child nodes of a subdivision must have a caseValue of the same type, and every subdivision must contain an "other" node.

If you wish to further subdivide a leaf node you must remove the existing unit and replace it with a subdivision with the same caseValue. You can then add your refinements as children of the new node.

Removing a subdivision causes all of its children to be recursively removed too.

Filter by product dimensions

You can add a ProductScope criterion to filter the products in a campaign. You can create at most one ProductScope per campaign. A ProductScope is a container for one or more ProductDimensions that represent a simple filter on one aspect of a product. For example, if you add a ProductBrand subtype of ProductDimension and set its value to Nexus, the campaign will apply only to products that have "Nexus" set as the brand in Merchant Center.

ProductScope productScope = new ProductScope();
productScope.setDimensions(new ProductDimension[] {new ProductBrand(null, "Nexus")});

You can add up to seven ProductDimensions to a ProductScope. Products must match all of the given ProductDimensions to be included in the campaign.

Bidding restrictions

The bidding restrictions on a shopping ad group varies based on whether its type is SHOPPING_PRODUCT_ADS or SHOPPING_SHOWCASE_ADS. The following table summarizes the differences.

	SHOPPING_PRODUCT_ADS	SHOPPING_SHOWCASE_ADS
Bidding Strategy	Only the following types are supported: MANUAL_CPC ENHANCED_CPC TARGET_ROAS TARGET_SPEND	Only the following types are supported: MANUAL_CPC ENHANCED_CPC
Bidding strategy at ad group level	Optional	Required
Bids at product partition node level	Required	Not allowed

Reporting

Shopping campaigns introduce two new reports, a Product Partition report and a Shopping Performance report.

See the Reporting guide for more information.