Mutate resources

  • The Google Ads API offers resource-specific services for mutating individual resource types like campaigns.

  • The GoogleAdsService.Mutate endpoint provides benefits like grouping actions across different resource services and using temporary resource names.

  • You can use GoogleAdsService.Mutate to perform linked operations, such as creating a complete campaign structure in a single request.

  • Generally, cross-account mutation is not permitted unless the account is the manager of the client that created the object.

The Google Ads API provides multiple ways to mutate resources depending on your use case:

  • Resource service mutates: Each mutable resource has a dedicated service that executes operations for that specific resource type. For example, the Campaign resource uses the CampaignService.MutateCampaigns endpoint for creating, updating, or removing campaigns.
  • Bulk mutates: The GoogleAdsService.Mutate endpoint wraps a sequence of mutate operations across multiple resource types (and, in v23 and later, supported action operations such as booking or quoting campaigns) in a single synchronous request.
  • Asynchronous batch jobs: For large-scale mutations or long-running workloads, BatchJobService executes operations asynchronously without risking synchronous request timeouts. Unlike GoogleAdsService.Mutate, BatchJobService always executes under partial-failure semantics and does not support validate_only mode or action operations (book_campaigns_operation, quote_campaigns_operation). Because partial failure is always active, BatchJobService rejects resource operations whose underlying services don't support partial failure (such as CustomerOperation, CampaignConversionGoalOperation, ConversionGoalCampaignConfigOperation, CustomConversionGoalOperation, and CustomerConversionGoalOperation) with MutateError.OPERATION_DOES_NOT_SUPPORT_PARTIAL_FAILURE.

Benefits of bulk mutates

Using GoogleAdsService.Mutate provides the following benefits (see Mutate best practices for implementation guidance):

  • Grouped actions across different resource services: Whereas individual resource service calls only accept operations for a single resource type, GoogleAdsService.Mutate lets you mutate multiple resource types in one call.
  • Temporary resource names: You can assign negative integer IDs (such as customers/CUSTOMER_ID/campaigns/-1) to newly created parent entities and reference those temporary IDs in child operations within the same request.

With these capabilities, you can use GoogleAdsService.Mutate to create an entire campaign hierarchy atomically so that all operations succeed or fail together, or set partial_failure to true to commit valid operations independently.

Next
Resource mutates