Set Bids

Bids can be set at different levels of the campaign hierarchy: campaign, ad group and ad group criterion. A bid set at a lower level will override those set at higher levels. For example, a bid set on an individual ad group within a campaign would override the campaign-level bid strategy's bid.

Updating bids

Multiple bids of different types can be set simultaneously (for example, cpc_bid_micros and cpm_bid_micros but only the bid that's relevant for the currently selected bidding strategy type will be used to bid for your ads.

The following code example updates the CPC bid of an existing ad group.

Java

public static void main(String[] args) {
  UpdateAdGroupParams params = new UpdateAdGroupParams();
  if (!params.parseArguments(args)) {

    // Either pass the required parameters for this example on the command line, or insert them
    // into the code here. See the parameter class definition above for descriptions.
    params.customerId = Long.parseLong("INSERT_CUSTOMER_ID_HERE");
    params.adGroupId = Long.parseLong("INSERT_AD_GROUP_ID_HERE");
    params.cpcBidMicroAmount = Long.parseLong("INSERT_CPC_BID_MICRO_AMOUNT_HERE");
  }

  GoogleAdsClient googleAdsClient;
  try {
    googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
  } catch (FileNotFoundException fnfe) {
    System.err.printf(
        "Failed to load GoogleAdsClient configuration from file. Exception: %s%n", fnfe);
    return;
  } catch (IOException ioe) {
    System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
    return;
  }

  try {
    new UpdateAdGroup()
        .runExample(
            googleAdsClient, params.customerId, params.adGroupId, params.cpcBidMicroAmount);
  } catch (GoogleAdsException gae) {
    // GoogleAdsException is the base class for most exceptions thrown by an API request.
    // Instances of this exception have a message and a GoogleAdsFailure that contains a
    // collection of GoogleAdsErrors that indicate the underlying causes of the
    // GoogleAdsException.
    System.err.printf(
        "Request ID %s failed due to GoogleAdsException. Underlying errors:%n",
        gae.getRequestId());
    int i = 0;
    for (GoogleAdsError googleAdsError : gae.getGoogleAdsFailure().getErrorsList()) {
      System.err.printf("  Error %d: %s%n", i++, googleAdsError);
    }
  }
}

C#

public void Run(GoogleAdsClient client, long customerId, long adGroupId,
    long? cpcBidMicroAmount)
{
    AdGroupServiceClient adGroupService = client.GetService(Services.V4.AdGroupService);

    // Create an ad group with the specified ID.
    AdGroup adGroup = new AdGroup();
    adGroup.ResourceName = ResourceNames.AdGroup(customerId, adGroupId);

    // Pause the ad group.
    adGroup.Status = AdGroupStatusEnum.Types.AdGroupStatus.Paused;

    // Update the CPC bid if specified.
    if (cpcBidMicroAmount != null)
    {
        adGroup.CpcBidMicros = cpcBidMicroAmount;
    }

    // Create the operation.
    AdGroupOperation operation = new AdGroupOperation()
    {
        Update = adGroup,
        UpdateMask = FieldMasks.AllSetFieldsOf(adGroup)
    };

    try
    {
        // Update the ad group.
        MutateAdGroupsResponse retVal = adGroupService.MutateAdGroups(
            customerId.ToString(), new AdGroupOperation[] { operation });

        // Display the results.
        MutateAdGroupResult adGroupResult = retVal.Results[0];

        Console.WriteLine($"Ad group with resource name '{adGroupResult.ResourceName}' " +
            "was updated.");
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}

PHP

public static function runExample(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    int $adGroupId,
    $bidMicroAmount
) {
    // Creates an ad group object with the specified resource name and other changes.
    $adGroup = new AdGroup([
        'resource_name' => ResourceNames::forAdGroup($customerId, $adGroupId),
        'cpc_bid_micros' => new Int64Value(['value' => $bidMicroAmount]),
        'status' => AdGroupStatus::PAUSED
    ]);

    // Constructs an operation that will update the ad group with the specified resource name,
    // using the FieldMasks utility to derive the update mask. This mask tells the Google Ads
    // API which attributes of the ad group you want to change.
    $adGroupOperation = new AdGroupOperation();
    $adGroupOperation->setUpdate($adGroup);
    $adGroupOperation->setUpdateMask(FieldMasks::allSetFieldsOf($adGroup));

    // Issues a mutate request to update the ad group.
    $adGroupServiceClient = $googleAdsClient->getAdGroupServiceClient();
    $response = $adGroupServiceClient->mutateAdGroups(
        $customerId,
        [$adGroupOperation]
    );

    // Prints the resource name of the updated ad group.
    /** @var AdGroup $updatedAdGroup */
    $updatedAdGroup = $response->getResults()[0];
    printf(
        "Updated ad group with resource name: '%s'%s",
        $updatedAdGroup->getResourceName(),
        PHP_EOL
    );
}

Python

def main(client, customer_id, ad_group_id, bid_micro_amount):
    ad_group_service = client.get_service('AdGroupService', version='v3')

    # Create ad group operation.
    ad_group_operation = client.get_type('AdGroupOperation', version='v3')
    ad_group = ad_group_operation.update
    ad_group.resource_name = ad_group_service.ad_group_path(
        customer_id, ad_group_id)
    ad_group.status = client.get_type('AdGroupStatusEnum', version='v3').PAUSED
    ad_group.cpc_bid_micros.value = bid_micro_amount
    fm = protobuf_helpers.field_mask(None, ad_group)
    ad_group_operation.update_mask.CopyFrom(fm)

    # Update the ad group.
    try:
        ad_group_response = ad_group_service.mutate_ad_groups(
            customer_id, [ad_group_operation])
    except google.ads.google_ads.errors.GoogleAdsException as ex:
        print('Request with ID "%s" failed with status "%s" and includes the '
              'following errors:' % (ex.request_id, ex.error.code().name))
        for error in ex.failure.errors:
            print('\tError with message "%s".' % error.message)
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print('\t\tOn field: %s' % field_path_element.field_name)
        sys.exit(1)

    print('Updated ad group %s.' % ad_group_response.results[0].resource_name)

Ruby

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

  resource_name = client.path.ad_group(customer_id, ad_group_id)

  operation = client.operation.update_resource.ad_group(resource_name) do |ag|
    ag.status = :PAUSED
    ag.cpc_bid_micros = bid_micro_amount
  end

  response = client.service.ad_group.mutate_ad_groups(customer_id, [operation])

  puts "Ad group with resource name = '#{response.results.first.resource_name}' was updated."
end

Perl

sub update_ad_group {
  my ($api_client, $customer_id, $ad_group_id, $cpc_bid_micro_amount) = @_;

  # Create an ad group with the proper resource name and any other changes.
  my $ad_group = Google::Ads::GoogleAds::V4::Resources::AdGroup->new({
      resourceName =>
        Google::Ads::GoogleAds::V4::Utils::ResourceNames::ad_group(
        $customer_id, $ad_group_id
        ),
      status       => PAUSED,
      cpcBidMicros => $cpc_bid_micro_amount
    });

  # Create an ad group operation for update, using the FieldMasks utility to
  # derive the update mask.
  my $ad_group_operation =
    Google::Ads::GoogleAds::V4::Services::AdGroupService::AdGroupOperation->new(
    {
      update     => $ad_group,
      updateMask => all_set_fields_of($ad_group)});

  # Update the ad group.
  my $ad_group_response = $api_client->AdGroupService()->mutate({
      customerId => $customer_id,
      operations => [$ad_group_operation]});

  printf "Updated ad group with resource name: '%s'.\n",
    $ad_group_response->{results}[0]{resourceName};

  return 1;
}

Removing bids

To remove a bid, update its field back to null.

Display Network criteria dimensions

For ads running on the Display Network, there are a number of different dimensions for which an ad group bid can be set. If multiple bids are set in different dimensions, the display_custom_bid_dimension field can be used to specify the dimension that should be used for absolute bids. Ads on the search network will always use keyword bids.

You can also set a bid adjustment which will be used when the criterion is not in an absolute bidding dimension. It can be accessed via the bid_modifier field of the ad group criterion.