Resource service mutates

Page Summary

outlined_flag

• Using a resource's individual service is the most straightforward way to mutate it, although it is the least flexible.

• Each mutable resource has a corresponding service and a set of operations to create, update, or remove the resource.

• To mutate a resource, you create an object, put it inside a corresponding operation object, and send it to the resource-specific mutate endpoint.

• A single mutate request can contain multiple operations, but each operation is treated independently and cross-referencing is not allowed.

Using a resource's dedicated service is the most direct way to create, update, or remove entities of a single resource type in the Google Ads API.

Mutate endpoints

Each mutable resource has a corresponding service and operation type. To mutate a resource using its dedicated service, populate one of the following fields on the operation and send it to the service's mutate endpoint:

• Create (create): A new resource object to create.
• Update (update): The modified resource object, accompanied by an update_mask specifying the changed fields.
• Remove (remove): The resource_name string of the target resource to remove.

For example, to create a new Campaign, complete the following steps:

1. Construct a Campaign object with your chosen attributes.
2. Assign it to the create field of a CampaignOperation.
3. Send the operation in a MutateCampaignsRequest to CampaignService.MutateCampaigns.

This same pattern applies across all resource-specific services in the Google Ads API:

• AdGroup: Pass an AdGroupOperation to AdGroupService.MutateAdGroups.
• CampaignCriterion: Pass a CampaignCriterionOperation to CampaignCriterionService.MutateCampaignCriteria.

The following REST JSON payload illustrates a request to CampaignService.MutateCampaigns:

{
  "customerId": "CUSTOMER_ID",
  "operations": [
    {
      "create": {
        "name": "Interplanetary Cruise #1",
        "advertisingChannelType": "SEARCH",
        "status": "PAUSED",
        "manualCpc": {},
        "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/BUDGET_ID",
        "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING"
      }
    }
  ],
  "partialFailure": false,
  "validateOnly": false
}

Multiple operations and limitations

Most resource-specific mutate requests accept a repeated operations field, so a single request can contain multiple operations for that resource type (up to 10,000 operations per request, or 20,000 for AdGroupCriterionService.MutateAdGroupCriteria; CustomerService.MutateCustomer accepts a singular operation field). By default, all operations in the request execute atomically unless the service supports partial_failure and you set it to true.

However, individual resource services have two important limitations:

• Single resource type: A request to a resource service can only mutate resources managed by that specific service.
• No cross-resource temporary IDs: Because a resource-specific mutate call only accepts a single resource type, you cannot assign a temporary negative ID to a parent resource (such as customers/CUSTOMER_ID/campaigns/-1) and reference it from a child resource of a different type (such as an AdGroup) in the same request. (Self-referencing temporary IDs within the same resource type are supported for hierarchical trees such as AdGroupCriterion listing groups and AssetGroupListingGroupFilter nodes.)

If you need to mutate multiple resource types in a single request or reference temporary resource names across different resource types, use GoogleAdsService.Mutate instead.

Version-specific differences

Keep the following difference across supported Google Ads API versions in mind when mutating resources:

• Lifecycle goal services: Customer Retention goals are mutated across all supported versions through GoalService.MutateGoals (retention_goal_settings) and CampaignGoalConfigService.MutateCampaignGoalConfigs (campaign_retention_settings) using a standard repeated operations field. In v25 and later, New Customer Acquisition (new_customer_acquisition_goal_settings / campaign_new_customer_acquisition_settings) and Loyalty Retention (loyalty_retention_goal_settings / campaign_loyalty_retention_settings) are also mutated through GoalService.MutateGoals and CampaignGoalConfigService.MutateCampaignGoalConfigs. This replaces CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals and CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals, which are used for New Customer Acquisition in v23 and v24 and accept a singular operation field.