Mutate

Google Ads scripts offer support for generic mutates that are available in the Google Ads API. Most operations that can be performed from GoogleAdsService.mutate can also be performed in Google Ads scripts, including creating and managing campaigns.

Since this feature allows access to such a large portion of the Google Ads API, it's important to have a basic understanding of Google Ads API conventions in order to use this feature. Many aspects can be skipped, such as developer tokens and authorization, as those are handled for you by Google Ads scripts, but you do have to form a valid mutate request.

Here are some basic resources on the Google Ads API REST interface that you should be familiar with before continuing with this guide:

• REST Interface Design
• Resource Names
• JSON Mappings
• Mutate

Basic example

To demonstrate the functionality, consider this basic example which creates a campaign budget:

const budgetResult = AdsApp.mutate({
    campaignBudgetOperation: {
      create: {
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });

A call to AdsApp.mutate takes a JSON object that represents a single MutateOperation. Within this object, you specify which kind of operation you're performing—in this case, a campaignBudgetOperation. You then specify either create, remove, or both update and updateMask. The specific fields within create and update depends on the specific type of resource you're operating on.

Build an operation

There are a few strategies you could use to build a valid operation. Sticking with the campaign budget example, you could look up the REST reference documentation for campaign budget to see a list of all its valid fields, and then fill out the appropriate fields, or write custom JavaScript code in your script to construct an appropriate object.

Alternatively, you could try building an operation dynamically using the "Try this" feature for campaign budget, which lets you build a request body dynamically by picking and choosing which fields you want to add. You can then extract the contents of the operation from the generated result and add it to your mutate call after specifying the operation type.

Operation types

Create

Specify create in your operation, passing in an object represesentation of the resource you would like to create.

See above for an example of the create operation.

Remove

Specify remove in your operation, passing in the resource name of the resource you would like to remove, for example:

AdsApp.mutate({
    adGroupOperation: {
        remove: "customers/[CUSTOMER_ID]/adGroups/[AD_GROUP_ID]"
    }
});

If you don't know the resource name for an entity, you can fetch it using an Adsapp.search request.

Update

Specify update in your operation, passing in an object with the resource name specified so that the system can determine which object you would like to update. Additionally, fill out any fields that you would like to update the values for, and specify an updateMask which indicates exactly which fields you plan to change in this request. Don't include the resource name in the update mask.

Example of an update operation:

const campaignResult = AdsApp.mutate({
    campaignOperation: {
        update: {
            resourceName: "customers/[CUSTOMER_ID]/campaigns/[CAMPAIGN_ID]",
            status: "PAUSED",
            name: "[Paused] My campaign"
        },
        updateMask: "name,status"
    }
});

Handling results

Regardless of the operation type, the return value is a MutateResult. You can use the returned resource name to query the current state of the resource after the mutate, and check whether the operation was successful or what errors occurred if any.

Here's an example showing a basic flow for checking a result and printing some information to the logs:

const result = AdsApp.mutate( ... );
if (result.isSuccessful()) {
    console.log(`Resource ${result.getResourceName()} successfully mutated.`);
} else {
    console.log("Errors encountered:");
    for (const error of result.getErrorMessages()) {
        console.log(error);
    }
}

Multiple operations

Google Ads scripts also supports mutating multiple operations in a single request with the AdsApp.mutateAll method. You can make entities that are dependent on each other, such as a full campaign hierarchy in a single request. You can optionally make the entire set of operations atomic, so if any one fails, then none are performed.

The return value is an array of MutateResult objects, one for each operation you provided and in the same order as the initial operations.

This feature functions the same as the Google Ads API feature, so consult the Google Ads API best practices guide for a full explanation of temp IDs and other considerations; note that the guide uses snake_case to represent field names, whereas the Google Ads scripts documentation is using lowerCamelCase. Both of these cases are accepted in Google Ads scripts, so you can copy code directly from that guide.

To make multiple operations in a single request, collect all your operations into an array and then call AdsApp.mutateAll. The mutateAll call takes the array of operations as a first argument and an optional second argument of options, including:

• apiVersion: You can specify a custom API version, such as V16, if you would like to use a version other than the scripts default. You can use any publicly available version at the time.
• partialFailure: This field defaults to true. If set to true, then valid operations are performed and failed operations return errors. If set to false, then if any operation fails, no operations are performed, effectively making this set of operations atomic.

Here's an example with multiple operations which creates a campaign budget, campaign, and ad group in an atomic request.

const operations = [];
const customerId = 'INSERT_CUSTOMER_ID_HERE';
const budgetId = `customers/${customerId}/campaignBudgets/-1`;
const campaignId = `customers/${customerId}/campaigns/-2`;
operations.push({
    campaignBudgetOperation: {
      create: {
        resourceName: budgetId,
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });
operations.push({
    campaignOperation: {
      create: {
        resourceName: campaignId,
        name: 'New Campaign ' + new Date(),
        advertisingChannelType: 'SEARCH',
        manualCpc: {},
        campaignBudget: budgetId,
        advertisingChannelType: 'DISPLAY',
        networkSettings: {
          targetContentNetwork: true
        }
      }
    }
  });
operations.push({
    adGroupOperation: {
      create: {
        campaign: campaignId,
        name: 'New AdGroup ' + new Date(),
        optimizedTargetingEnabled: true
      }
    }
  });
const results = AdsApp.mutateAll(
    operations, {partialFailure: false});