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

Because the operations field of a mutate request is repeated, a single request can contain multiple operations (up to 10,000 operations per request) for that resource type. By default, all operations in the request execute atomically unless you set partial_failure 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 temporary resource IDs or cross-referencing: Operations in a resource-specific mutate call are processed independently. You cannot assign temporary negative IDs (such as customers/CUSTOMER_ID/campaigns/-1) or reference newly created entities from other operations in the same request.

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

Version-specific differences

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

• Lifecycle goal services: In v25 and later, all lifecycle goals—including New Customer Acquisition (new_customer_acquisition_goal_settings), Customer Retention (retention_goal_settings), and Loyalty Retention (loyalty_retention_goal_settings)—are mutated through GoalService.MutateGoals and CampaignGoalConfigService.MutateCampaignGoalConfigs using a standard repeated operations field. This replaces CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals and CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals (which are used for New Customer Acquisition in v24 and earlier and accept a singular operation field).
• Campaign date and time fields: When creating or updating a Campaign, v23 and later use start_date_time and end_date_time (yyyy-MM-dd HH:mm:ss), replacing the date-only start_date and end_date fields used in v22.
• Synthetic content attestation mutability: Although Asset.synthetic_content_info and Ad.synthetic_content_info appear in the schema for v22 and later, the synthetic_content_info.advertiser_attestation.status and synthetic_content_info.advertiser_attestation.source fields are only mutable in v23 and later (system_attestation is always OUTPUT_ONLY). Attempting to mutate advertiser_attestation subfields in v22 returns an immutable-field error ("The field attempted to be mutated is immutable" or "Field cannot be set").