Bidding

AdWords gives you several ways to bid for your ads, depending on what matters most to you and your business.

In the AdWords API, all bidding parameters are managed via one or both of the following:

With either object, you can use its biddingStrategyType field, its biddingScheme field, or both, to specify a bidding type. The biddingScheme allows you to set additional parameters specific to a bidding type. When both fields are specified, their types must match.

Strategy types

In the table below, the Valid Contexts column indicates whether a given BiddingStrategyType and associated BiddingScheme type can be used in one or both of the contexts mentioned above:

  • A standard strategy with a BiddingStrategyConfiguration object.
  • A portfolio strategy with a SharedBiddingStrategy object.
BiddingStrategyType BiddingScheme Descriptive name Valid Contexts
BUDGET_OPTIMIZER

No longer available after v201702. Use TARGET_SPEND instead.

BudgetOptimizerBiddingScheme Budget optimizer Standard
CONVERSION_OPTIMIZER

No longer available after v201702. Use TARGET_CPA instead.

ConversionOptimizerBiddingScheme Focus on conversions - use CPA bids Standard
ENHANCED_CPC EnhancedCpcBiddingScheme Enhanced CPC Portfolio
MANUAL_CPC ManualCpcBiddingScheme Focus on clicks - use maximum CPC bids Standard
MANUAL_CPM ManualCpmBiddingScheme Viewable CPM.

Works only with Display Network Only campaigns

Standard
PAGE_ONE_PROMOTED PageOnePromotedBiddingScheme Target search page location Portfolio
TARGET_CPA TargetCpaBiddingScheme Target cost per acquisition (CPA) - must meet eligibility requirements Portfolio
Standard
TARGET_OUTRANK_SHARE TargetOutrankShareBiddingScheme Target outranking share Portfolio
TARGET_ROAS TargetRoasBiddingScheme Target return on ad spend - must meet eligibility requirements Portfolio
TARGET_SPEND

enhancedCpcEnabled can only be set on a standard strategy.

TargetSpendBiddingScheme Maximize clicks Portfolio
Standard
NONE Special bidding strategy type used to clear the bidding strategy at AdGroup and AdGroupCriterion. Portfolio
Standard

Errors result if you try to use a BiddingStrategyType or BiddingScheme in the wrong context:

  • Using a portfolio-only type or scheme in the context of a standard strategy generates a BiddingErrors error with reason INVALID_ANONYMOUS_BIDDING_STRATEGY_TYPE.
  • Using a standard-only type or scheme in the context of a portfolio strategy generates a BiddingErrors error with reasonBIDDING_STRATEGY_NOT_SUPPORTED.

Overriding standard bidding strategies set at higher levels

Overriding bidding strategies only applies to versions earlier than v201705. Start migrating your code to only set bidding strategies at the campaign level.

You can't set a different bidding strategy at a lower level from that at a higher level. For example, setting a MANUAL_CPM strategy at the ad group level when a MANUAL_CPC strategy exists at the campaign level will throw an error.

You can set a MANUAL_CPC strategy at a lower level when another MANUAL_CPC exists at a higher level; however, you would be better off just setting the bid directly.

Overriding target ROAS at the ad group level

The TargetRoasBiddingScheme set at the campaign level can be overriden at the ad group level by setting the bidding configuration's targetRoasOverride at the ad group level. The other fields cannot be overriden.

Setting bids

Bids can be set at the ad group and ad group criterion levels. A criterion bid will override an ad group bid.

Multiple bids of different types can be set in a single strategy simultaneously (for example, CpcBid and CpmBid) but only the bid that matches the selected biddingStrategyType will be used.

Reporting also returns only the currently active bid. If you transition to a different bidding type the corresponding bid is used.

The following code example uses a mutate call to add a CPC bid at the ad group level.

// Create ad group bid.
BiddingStrategyConfiguration biddingStrategyConfiguration =
    new BiddingStrategyConfiguration();
CpcBid bid = new CpcBid();
bid.setBid(new Money(null, 10000000L));

// You can optionally provide this field.
bid.setContentBid(new Money(null, 20000000L));

biddingStrategyConfiguration.setBids(new Bids[] {bid});
adGroup.setBiddingStrategyConfiguration(biddingStrategyConfiguration);

// Create operation.
AdGroupOperation operation = new AdGroupOperation();
operation.setOperand(adGroup);
operation.setOperator(Operator.SET);
AdGroupOperation[] operations = new AdGroupOperation[] {operation};

// Update ad group.
AdGroupReturnValue result = adGroupService.mutate(operations);

Removing bids

To remove a bid from a BiddingStrategyConfiguration, update its bid field to a Money object with microAmount set to 0.

Bidding strategy transitions

To change a bidding strategy, issue a mutate() call with the updated strategy fields to the corresponding service. The example below illustrates how to change the bidding type for a campaign by setting a different biddingScheme.

// Create a new local Campaign object.
Campaign campaign = new Campaign();
campaign.setId(campaignId);

// Create a new biddingStrategyConfiguration.
BiddingStrategyConfiguration biddingStrategyConfiguration =
    new BiddingStrategyConfiguration();

// You can specify either type or scheme, or both.
biddingStrategyConfiguration.setBiddingScheme(new ManualCpcBiddingScheme());
campaign.setBiddingStrategyConfiguration(biddingStrategyConfiguration);

// Create SET operation.
CampaignOperation operation = new CampaignOperation();
operation.setOperand(campaign);
operation.setOperator(Operator.SET);
CampaignOperation[] operations = new CampaignOperation[] {operation};

// Update the campaign.
CampaignReturnValue result = campaignService.mutate(operations);

Portfolio bid strategies

You can use portfolio bid strategies with your campaigns, ad groups, or keywords. Bidding strategies at lower levels override those at higher levels (keywords' bidding strategies override those of ad groups or campaigns). Starting in v201705, the bidding strategy type cannot be overriden even though bids can be overriden.

Use the BiddingStrategyService to create a SharedBiddingStrategy and set its parameters. For example, to use an existing portfolio bid strategy for a campaign, update the campaign's biddingStrategyConfiguration with the strategy's ID:

BiddingStrategyConfiguration biddingStrategyConfiguration = new BiddingStrategyConfiguration();
biddingStrategyConfiguration.setBiddingStrategyId(strategyId);

campaign.setBiddingStrategyConfiguration(biddingStrategyConfiguration);

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 contentBidCriterionTypeGroup 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 bidModifier field of the BiddableAdGroupCriterion.

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.

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

Retrieving bid adjustments

To retrieve existing bid adjustments, use the get() or query() method of CampaignCriterionService, AdGroupBidModifierService, or CampaignBidModifierService. Similar to other services, the get() method accepts a generic selector allowing you to select response fields and filter the results set.

The code below retrieves the first 10 existing campaign-level platform criteria across all 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, AdGroupBidModifierService, or CampaignBidModifierService 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.
  • Performing an ADD operation on a an existing CampaignBidModifier, AdGroupBidModifier, or AdGroupCriterion will cause the operation to be treated like a SET.

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());
}

Migrating the bidding strategy configuration override of ad groups and keywords

Starting in v201705, the bidding strategy will no longer be allowed to be overriden at the ad group and keyword criterion levels. This means the biddingStrategyType, biddingStrategyId, and biddingScheme cannot be set at those levels. The bidding strategy can only be set at the campaign level. The only exception is that the biddingStrategyType can be set to NONE at the ad group and keyword criterion levels. This was done to simplify bidding strategies as overrides are not often used.

To migrate:

  • There is the option in all versions of setting the biddingStrategyType at the ad group and keyword criterion levels to NONE. This allows these objects to then inherit the bidding strategy configuration from the campaign. The fields related to the biddingStrategyType such as the biddingStrategyId will be cleared when NONE is specified.
  • If multiple ad groups under the same campaign do need different bidding strategies, then create separate campaigns for each of the ad groups.

Send feedback about...

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