Register for one of our AdWords API workshops (30 August - 16 September).

Bid Modifiers

Campaign and ad group level bid adjustments give you more control over your bids in AdWords campaigns, providing the option to increase or decrease bids for certain criteria.

Note: This guide covers bid modifiers for Platform (campaign and ad group) and PreferredContent (ad group only) criteria. For all other criterion types, bid modifiers are only supported at the ad group level and are maintained via AdGroupCriterionService and specified via the bidModifier attribute of BiddableAdGroupCriterion. Please see the Bidding guide for details.

Within the AdWords API, campaign level adjustments are accessible via CampaignCriterionService, and ad group level adjustments are accessible via AdGroupBidModifierService.

This guide contains examples in Java. Refer to the client libraries page for examples in other languages.

Important changes to platform bid adjustments

In v201603 and earlier, bid adjustments for Platform criteria were only supported for the HighEndMobile criterion (ID=30001). Starting with v201605, you can make bid adjustments for all Platform IDs, but only on test accounts. Support for production accounts will be added in the coming months.

As a result of these changes, you should review your application's bidding functionality, particularly if your application calculates base bids or device (Platform) adjustments.

  • If your code surfaces bid information (max CPC) via a user interface, we recommend also surfacing device bid adjustments (tablet, desktop, and mobile) so that users have visibility into the actual bids by device type.
  • Your code should no longer assume that max CPC equates to desktop/tablet bids when calculating bids and/or device bid adjustments. For instance, if you are calculating a recommended mobile bid adjustment, you may need to take into account the desktop bid modifier.

Retrieving bid adjustments

In order to retrieve existing bid adjustments, use the get or query method of CampaignCriterionService or AdGroupBidModifierService. Similarly to other services, the get method accepts a generic selector allowing you to select response fields and filter the results set.

The code below will retrieve the first 10 existing campaign-level platform criteria across all of your campaigns:

// Get the CampaignCriterionService.
CampaignCriterionServiceInterface campaignCriterionService =
    adWordsServices.get(session, CampaignCriterionServiceInterface.class);

// Create a selector that limits to the first 10 platform criteria found.
Selector selector =
    new SelectorBuilder()
        .fields(
            CampaignCriterionField.CampaignId,
            CampaignCriterionField.Id,
            CampaignCriterionField.CriteriaType,
            CampaignCriterionField.BidModifier)
        .equals(CampaignCriterionField.CriteriaType, "PLATFORM")
        .equals(CampaignCriterionField.IsNegative, "false")
        .limit(10)
        .build();

// Make a 'get' request.
CampaignCriterionPage campaignCriterionPage = campaignCriterionService.get(selector);

// Display the results.
if (campaignCriterionPage.getEntries() != null) {
  for (CampaignCriterion campaignCriterion : campaignCriterionPage.getEntries()) {
    String value =
        campaignCriterion.getBidModifier() == null
            ? "unset"
            : String.format("%.2f", campaignCriterion.getBidModifier());
    System.out.printf(
        "Campaign ID %d, criterion ID %d has campaign level bid modifier %s.%n",
        campaignCriterion.getCampaignId(), campaignCriterion.getCriterion().getId(), value);
  }
} else {
  System.out.println("No campaign criteria found.");
}

Adding, updating and removing bid adjustments

Use the mutate method of CampaignCriterionService or AdGroupBidModifierService to add or amend a bid adjustment. To add a new bid modifier use the ADD operator; to update an existing bid override to a new value, use the SET operator. To remove a bid modifier override, use the REMOVE operator.

Note: Refer to the campaign and ad group API documentation for the valid range of bidModifier values for each criterion type.

This example demonstrates how to add a new campaign level mobile bid adjustment:

// Get the CampaignCriterionService.
CampaignCriterionServiceInterface campaignCriterionService =
    adWordsServices.get(session, CampaignCriterionServiceInterface.class);

// Create mobile platform. The ID can be found in the documentation.
// https://developers.google.com/adwords/api/docs/appendix/platforms
Platform mobile = new Platform();
mobile.setId(30001L);

// Create criterion with modified bid.
CampaignCriterion campaignCriterion = new CampaignCriterion();
campaignCriterion.setCampaignId(campaignId);
campaignCriterion.setCriterion(mobile);
campaignCriterion.setBidModifier(BID_MODIFIER);

// Create SET operation.
CampaignCriterionOperation operation = new CampaignCriterionOperation();
operation.setOperand(campaignCriterion);
operation.setOperator(Operator.SET);

// Update campaign criterion.
CampaignCriterionReturnValue result =
    campaignCriterionService.mutate(new CampaignCriterionOperation[] {operation});
for (CampaignCriterion campaignCriterionResult : result.getValue()) {
  System.out.printf("Campaign criterion with campaign ID %d, criterion ID %d, "
      + "and type '%s' was modified with bid %.4f.%n",
      campaignCriterionResult.getCampaignId(),
      campaignCriterionResult.getCriterion().getId(),
      campaignCriterionResult.getCriterion().getType(),
      campaignCriterionResult.getBidModifier());
}

Send feedback about...

AdWords API
AdWords API
Need help? Visit our support page.