Learn more about migrating to the Google Ads API by watching our latest webinar

Mutate Ads

Mutate expanded text ad

As mentioned previously, only certain ad types are mutable. The following code example illustrates how to modify an existing expanded text ad.


private void runExample(GoogleAdsClient googleAdsClient, long customerId, long adId) {
  // Creates an AdOperation to update an ad.
  AdOperation.Builder adOperation = AdOperation.newBuilder();

  // Creates an Ad in the update field of the operation.
  Ad.Builder adBuilder =
          .setResourceName(ResourceNames.ad(customerId, adId))

  // Sets the expanded text ad properties to update on the ad.
      .setHeadlinePart1("Cruise to Pluto #" + getShortPrintableDateTime())
      .setHeadlinePart2("Tickets on sale now")
      .setDescription("Best space cruise ever.");

  // Sets the update mask (the fields which will be modified) to be all the fields we set above.

  // Creates a service client to connect to the API.
  try (AdServiceClient adServiceClient =
      googleAdsClient.getLatestVersion().createAdServiceClient()) {
    // Issues the mutate request.
    MutateAdsResponse response =
            String.valueOf(customerId), ImmutableList.of(adOperation.build()));

    // Displays the result.
    for (MutateAdResult result : response.getResultsList()) {
      System.out.printf("Ad with resource name '%s' was updated.%n", result.getResourceName());


public void Run(GoogleAdsClient client, long customerId, long adId)
    // Get the AdService.
    AdServiceClient adService = client.GetService(Services.V8.AdService);

    Ad ad = new Ad()
        ResourceName = ResourceNames.Ad(customerId, adId),
        ExpandedTextAd = new ExpandedTextAdInfo()
            // Update some properties of the expanded text ad.
            HeadlinePart1 = "Cruise to Pluto #" + ExampleUtilities.GetShortRandomString(),
            HeadlinePart2 = "Tickets on sale now",
            Description = "Best space cruise ever.",
        FinalUrls = { "http://www.example.com/" },
        FinalMobileUrls = { "http://www.example.com/mobile" }

    AdOperation operation = new AdOperation()
        Update = ad,
        UpdateMask = FieldMasks.AllSetFieldsOf(ad)

        // Issue the update request.
        MutateAdsResponse response = adService.MutateAds(customerId.ToString(),
            new[] { operation });

        // Display the results.
        foreach (MutateAdResult updatedAd in response.Results)
            Console.WriteLine($"Ad with resource ID = '{updatedAd.ResourceName}' was " +
    catch (GoogleAdsException e)
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");


public static function runExample(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    int $adId
) {
    // Creates an ad with the specified resource name and other changes.
    $ad = new Ad([
        'resource_name' => ResourceNames::forAd($customerId, $adId),
        'expanded_text_ad' => new ExpandedTextAdInfo([
            'headline_part1' => 'Cruise to Pluto #' . Helper::getShortPrintableDatetime(),
            'headline_part2' => 'Tickets on sale now',
            'description' => 'Best space cruise ever'
        'final_urls' => ['http://www.example.com'],
        'final_mobile_urls' => ['http://www.example.com/mobile']

    // Constructs an operation that will update the ad, using the FieldMasks to derive the
    // update mask. This mask tells the Google Ads API which attributes of the ad you want to
    // change.
    $adOperation = new AdOperation();

    // Issues a mutate request to update the ad.
    $adServiceClient = $googleAdsClient->getAdServiceClient();
    $response = $adServiceClient->mutateAds($customerId, [$adOperation]);

    // Prints the resource name of the updated ad.
    /** @var Ad $updatedAd */
    $updatedAd = $response->getResults()[0];
        "Updated ad with resource name: '%s'.%s",


def main(client, customer_id, ad_id):
    ad_service = client.get_service("AdService")
    ad_operation = client.get_type("AdOperation")

    # Update ad operation.
    ad = ad_operation.update
    ad.resource_name = ad_service.ad_path(customer_id, ad_id)
    ad.expanded_text_ad.headline_part1 = (
        f"Cruise to Pluto {str(uuid.uuid4())[:8]}"
    ad.expanded_text_ad.headline_part2 = "Tickets on sale now"
    ad.expanded_text_ad.description = "Best space cruise ever."
        ad_operation.update_mask, protobuf_helpers.field_mask(None, ad._pb)

    # Updates the ad.
    ad_response = ad_service.mutate_ads(
        customer_id=customer_id, operations=[ad_operation]
        f'Ad with resource name "{ad_response.results[0].resource_name}" '
        "was updated."


def update_expanded_text_ad(customer_id, ad_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  ad_resource_name = client.path.ad(customer_id, ad_id)

  # Create the operation for updating the ad.
  ad_operation = client.operation.update_resource.ad(ad_resource_name) do |ad|
    ad.final_urls << 'http://www.example.com'
    ad.final_mobile_urls << 'http://www.example.com/mobile'
    ad.expanded_text_ad = client.resource.expanded_text_ad_info do |eta|
      eta.headline_part1 = "Cruise to Pluto #{(Time.new.to_f * 100).to_i}"
      eta.headline_part2 = 'Tickets on sales now'

  # Update the ad.
  response = client.service.ad.mutate_ads(
    customer_id: customer_id,
    operations: [ad_operation],

  puts "Updated expanded text ad #{response.results.first.resource_name}."


sub update_expanded_text_ad {
  my ($api_client, $customer_id, $ad_id) = @_;

  # Create an ad with the proper resource name and any other changes.
  my $ad = Google::Ads::GoogleAds::V8::Resources::Ad->new({
      resourceName => Google::Ads::GoogleAds::V8::Utils::ResourceNames::ad(
        $customer_id, $ad_id
      expandedTextAd =>
          # Update some properties of the expanded text ad.
          headlinePart1 => "Cruise to Pluto #" . uniqid(),
          headlinePart2 => "Tickets on sale now",
          description   => "Best space cruise ever."
      finalUrls       => ["http://www.example.com/"],
      finalMobileUrls => ["http://www.example.com/mobile"]});

  # Create an ad operation for update, using the FieldMasks utility to derive
  # the update mask.
  my $ad_operation =
      update     => $ad,
      updateMask => all_set_fields_of($ad)});

  # Issue a mutate request to update the ad.
  my $ads_response = $api_client->AdService()->mutate({
      customerId => $customer_id,
      operations => [$ad_operation]});

  printf "Updated ad with resource name: '%s'.\n",

  return 1;