Shopping campaigns

Google Ads scripts allow for some management of your Shopping campaigns. You can use scripts to work with existing shopping campaigns, create and manage product group hierarchies and run shopping reports. However, you can't use scripts to create shopping campaigns, set shopping properties at the campaign level (e.g. campaign priority, inventory filters, etc.) or link Merchant Center accounts.

Retrieving your shopping campaigns and ad groups

Shopping campaigns are available through the shoppingCampaigns collection of an AdsApp object. You can retrieve them as you would normally retrieve campaigns in scripts:

var campaignName = "My first shopping campaign";

var campaignIterator = AdsApp.shoppingCampaigns()
    .withCondition("CampaignName = '" + campaignName + "'")
    .get();

while (campaignIterator.hasNext()) {
  var campaign = campaignIterator.next();
  ...
}

Once you've retrieved a campaign, you can get its ad groups in a similar manner:

var adGroupIterator = campaign.adGroups()
    .withCondition("AdGroupName = '" + adGroupName + "'")
    .get();

while (adGroupIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    ...
}

Alternatively, you can use the AdsApp.shoppingAdGroups() method:

var adGroupIterator = AdsApp.shoppingAdGroups()
    .withCondition("CampaignName='" + campaignName +
        "' and AdGroupName = '" + adGroupName + "'")
    .get();

while (adGroupIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    ...
}

Working with product ads

Google Ads scripts allow you to retrieve your product ads using the ads() method of the ShoppingAdGroup. You can create new product ads using the newAdBuilder() method of ShoppingAdGroup.

Iterating the product group hierarchy

You can access the root of the product group hierarchy using the rootProductGroup method of the ShoppingAdGroup. You can then use the children method to iterate the child product groups and walk the product group hierarchy. Each node is a ProductGroup object, and you can use the getDimension method to figure out the actual type of the product group. You may also cast it to a more specific type (e.g. ProductBrand) by using the corresponding casting method (e.g. asBrand). The following code snippet shows how to recursively walk the product group hierarchy.

walkTree(shoppingAdGroup.rootProductGroup(), 1);

function walkTree(root, level) {
  // Logger.log(root.getDimension());
  var description = "";
  switch (root.getDimension()) {
    case "ROOT":
      description = "Root";
      break;

    case "CATEGORY":
      description = root.asCategory().getName();
      break;

    case "BRAND":
      description = root.asBrand().getName();
      break;

    // Handle more types here.
    ...
  }

  if (root.isOtherCase()) {
    description = "Other";
  }

  var padding = new Array(level + 1).join('-');
  Logger.log("%s %s, %s, %s, %s, %s",
             padding,
             description,
             root.getDimension(),
             root.getMaxCpc(),
             root.isOtherCase(),
             root.getId().toFixed());
  var children = root.children().get();
  while (children.hasNext()) {
    var child = children.next();
    walkTree(child, level + 1);
  }
}

Selecting specific product group

You can select specific product groups in a product group hierarchy with the productGroups method of AdsApp, ShoppingCampaign or ShoppingAdGroup instance. This approach is simpler than walking the entire product group hierarchy if you wish to select specific product groups for bid management purposes. The following code snippet shows how to select all product groups with more than five clicks and a click-through rate greater than 0.01 during last month, and increases their bid by 0.01.

function main() {
  var productGroups = AdsApp.productGroups()
      .withCondition("Clicks > 5")
      .withCondition("Ctr > 0.01")
      .forDateRange("LAST_MONTH")
      .get();
  while (productGroups.hasNext()) {
    var productGroup = productGroups.next();
    productGroup.setMaxCpc(productGroup.getMaxCpc() + 0.01);
  }
}

Updating a product group hierarchy

You can add a child product group to an existing product group using its newChild method. This gives you a ProductGroupBuilderSpace object, which you can then use to build an appropriate product group. The following code snippet adds a subdivision for a "cardcow" brand under the root, and then subdivides it further for new and refurbished products.

var root = shoppingAdGroup.rootProductGroup();

// Add a brand product group for a "cardcow" under root.
var brandProductGroup = root.newChild()
    .brandBuilder()
    .withName("cardcow")
    .withBid(1.2)
    .build()
    .getResult();

// Add new conditions for New and Refurbished cardcow brand items.
var newItems = brandProductGroup.newChild()
    .conditionBuilder()
    .withCondition("New")
    .withBid(1.5)
    .build()
    .getResult();

// Refurbished items will use the bid from "cardcow" product group.
var refurbishedItems = brandProductGroup.newChild()
    .conditionBuilder()
    .withCondition("Refurbished")
    .build()
    .getResult();

Similarly, you can remove a subdivision using the remove method of ProductGroup. This will also delete the entire product group hierarchy underneath the product group being removed.

Scripts will ensure that the product group hierarchy is in a consistent state after creating each product group, so you don't need to create or delete the product group corresponding to "Everything else" when updating the product group hierarchy structure.

The "Everything else" product group

Shopping product group hierarchies contain an "Everything else" (a.k.a. "Other") product group at each level to handle products that doesn’t match the custom condition you created in the product group hierarchy. You can use the isOtherCase method to distinguish between a normal product group that you added, and the "Other" product group.

The following code snippet retrieves the "Other" product group under the root product group hierarchy, and prints its bid.

var root = shoppingAdGroup.rootProductGroup();

var childProductGroups = root.children().get();
var everythingElseProductGroupFound = false;

while (childProductGroups.hasNext()) {
  var childProductGroup = childProductGroups.next();
  if (childProductGroup.isOtherCase()) {
    Logger.log("'Everything else' product group found. Type of the " +
               "product group is %s and bid is %s.",
               childProductGroup.getDimension(),
               childProductGroup.getMaxCpc());
    everythingElseProductGroupFound = true;
    break;
  }
}
if (!everythingElseProductGroupFound) {
  Logger.log("No 'Everything else' product group found under root " +
             "product group.");
}

When you subdivide a leaf product group, then scripts will automatically create an "Other" product group, to ensure that the product group hierarchy remains valid. The "Other" product group will inherit the bid of the parent product group.

Creating a new shopping ad group

Google Ads scripts allows you to create a new shopping ad group using the newAdGroupBuilder method of ShoppingCampaign . Once you create the ShoppingAdGroup, you can then use its createRootProductGroup method to create a new product group hierarchy.

Running reports

Google Ads scripts support Product Partition report and Shopping Performance report to help you track the performance of your shopping campaigns. You can learn more about reporting in our reports guide.