Shopping campaigns

Page Summary

Google Ads scripts allow for managing existing shopping campaigns, including working with product group hierarchies and running reports, but do not support creating new campaigns or setting campaign-level shopping properties.
You can retrieve shopping campaigns and ad groups using specific methods like AdsApp.shoppingCampaigns() and AdsApp.shoppingAdGroups().
Product ads can be retrieved and created using methods available on the ShoppingAdGroup object.
Scripts enable traversal and updates of the product group hierarchy within a shopping ad group, including adding and removing subdivisions.
Shopping product group hierarchies include an "Everything else" product group at each level to catch products not matching defined conditions.

Google Ads scripts provide 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 (for example: campaign priority, inventory filters, etc.), or link Merchant Center accounts.

Retrieve shopping campaigns and ad groups

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

const campaignName = "My first shopping campaign";

const campaignIterator = AdsApp.shoppingCampaigns()
    .withCondition(`campaign.name = "${campaignName}"`)
    .get();

for (const campaign of campaignIterator) {
  ...
}

Once you've retrieved a campaign, you can get its ad groups in a similar manner. This is only preferable if you need to act on both the campaign and its ad groups.

const adGroupIterator = campaign.adGroups()
    .withCondition(`ad_group.name = "${adGroupName}"`)
    .get();

for (const adGroup of adGroupIterator) {
    ...
}

If you plan on acting on specific ad groups only, you can use the AdsApp.shoppingAdGroups() method to fetch ad groups without fetching the campaign first:

const adGroupIterator = AdsApp.shoppingAdGroups()
    .withCondition(`campaign.name = "${campaignName}"`)
    .withCondition(`ad_group.name = "${adGroupName}"`)
    .get();

for (const adGroup of adGroupIterator) {
    ...
}

Product ads

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

Iterate through 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 traverse 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 can also cast it to a more specific type (for example, ProductBrand) by using the corresponding casting method (for example, asBrand). The following code snippet shows how to recursively traverse the product group hierarchy.

walkTree(shoppingAdGroup.rootProductGroup(), 1);

function walkTree(root, level) {
  // Logger.log(root.getDimension());
  let 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";
  }

  const padding = new Array(level + 1).join('-');
  console.log("%s, %s, %s, %s, %s, %s",
             padding,
             description,
             root.getDimension(),
             root.getMaxCpc(),
             root.isOtherCase(),
             root.getId().toFixed());
  const children = root.children().get();
  for (const child of children) {
    walkTree(child, level + 1);
  }
}

Select a specific product group

You can select specific product groups in a product group hierarchy with the productGroups method of an AdsApp, ShoppingCampaign, or ShoppingAdGroup instance. This approach is simpler than traversing the entire product group hierarchy when selecting 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 the last month, and increases their bid by 0.01.

function main() {
  const productGroups = AdsApp.productGroups()
      .withCondition("metrics.clicks > 5")
      .withCondition("metrics.ctr > 0.01")
      .forDateRange("LAST_MONTH")
      .get();
  for (const productGroup of productGroups) {
    productGroup.setMaxCpc(productGroup.getMaxCpc() + 0.01);
  }
}

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

const root = shoppingAdGroup.rootProductGroup();

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

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

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

Similarly, you can remove a subdivision using the remove method of ProductGroup. This also deletes 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" ("Other") product group at each level to handle products that don'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.

const root = shoppingAdGroup.rootProductGroup();

const childProductGroups = root.children().get();
let everythingElseProductGroupFound = false;

for (const childProductGroup of childProductGroups) {
  if (childProductGroup.isOtherCase()) {
    console.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) {
  console.log("No 'Everything else' product group found under root " +
             "product group.");
}

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

Create a new shopping ad group

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

Reports

Google Ads scripts support product_group_view and shopping_performance_view reports to help you track the performance of your shopping campaigns. You can learn more about reporting in our reports guide.

Shopping campaigns Stay organized with collections Save and categorize content based on your preferences.