Campaign Budgets

Budgets are used to manage the amount of money spent for your AdWords campaigns. This guide describes everything you need to know to work with budgets in the AdWords API, including sharing, assigning, removing, and tracking the performance of budgets.

Sharing budgets

A budget can apply to a single campaign, or shared across many campaigns.

When you create a new Budget using the AdWords API, it's shareable by default. You can verify this by checking the value for isExplicitlyShared through an API call to the BudgetService:

• isExplicitlyShared = true means the budget can be shared among multiple campaigns
• isExplicitlyShared = false means the budget can be used by only one campaign

Note: You can only set isExplicitlyShared to false when creating the budget (it's set to true by default). Once the budget is created, you cannot change isExplicitlyShared from true to false. You can change isExplicitlyShared from false to true, but only if there are no experiments running on the campaign that's using the budget.

Explicitly shared budgets appear in an account's Shared Library in the AdWords user interface, whereas a non-shared budget appears only within its associated campaign's Settings.

Assigning a budget to a campaign

To assign a budget to a campaign, create a Budget object with BudgetService, and then use the resulting budget ID in a subsequent call to CampaignService. Note that if the campaign operation fails but the budget operation succeeds, an orphaned budget (a budget associated with no campaign) will still be created. We recommend you either reuse or remove such budgets.

New campaign

For a new campaign, in the CampaignService.mutate() ADD operation, set the campaign's budget attribute to a Budget object with its budgetId set to the ID of a budget, as demonstrated in the Java code example below. In the example, a shared budget is created because isExplicitlyShared is left at its default value of true.

// Get the BudgetService.
BudgetServiceInterface budgetService =
    adWordsServices.get(session, BudgetServiceInterface.class);

// Create a budget, which can be shared by multiple campaigns.
Budget sharedBudget = new Budget();
sharedBudget.setName("Interplanetary Cruise #" + System.currentTimeMillis());
Money budgetAmount = new Money();
budgetAmount.setMicroAmount(50000000L);
sharedBudget.setAmount(budgetAmount);
sharedBudget.setDeliveryMethod(BudgetBudgetDeliveryMethod.STANDARD);
BudgetOperation budgetOperation = new BudgetOperation();
budgetOperation.setOperand(sharedBudget);
budgetOperation.setOperator(Operator.ADD);

// Execute the new budget operation and save the assigned budget ID.
Long budgetId =
    budgetService.mutate(new BudgetOperation[] {budgetOperation}).getValue(0).getBudgetId();
Campaign campaign = new Campaign();
campaign.setName("Interplanetary Cruise #" + System.currentTimeMillis());
campaign.setStatus(CampaignStatus.PAUSED);
campaign.setAdvertisingChannelType(AdvertisingChannelType.SEARCH);

// Set the bidding strategy configuration.
BiddingStrategyConfiguration biddingStrategyConfiguration =
    new BiddingStrategyConfiguration();
biddingStrategyConfiguration.setBiddingStrategyType(BiddingStrategyType.MANUAL_CPC);
campaign.setBiddingStrategyConfiguration(biddingStrategyConfiguration);

// Only the budgetId should be set.
Budget budget = new Budget();
budget.setBudgetId(budgetId);
campaign.setBudget(budget);
CampaignServiceInterface campaignService =
    adWordsServices.get(session, CampaignServiceInterface.class);
CampaignOperation operation = new CampaignOperation();
operation.setOperand(campaign);
operation.setOperator(Operator.ADD);
CampaignOperation[] operations = new CampaignOperation[] {operation};
CampaignReturnValue result = campaignService.mutate(operations);

Replacing a campaign's budget

To replace the budget of an existing campaign, use a CampaignService.mutate() SET operation, and set the budget attribute of the campaign to a Budget object with its budgetId set to the ID of the existing budget (along with any other campaign fields that you might want to set). Note that this will replace the existing budget assigned to the campaign with the one specified by the budgetId, since a campaign can be associated with only one budget at a time.

Dissociating a budget from a campaign

A campaign must always be associated with a budget. You can remove a budget from a campaign by by changing the ID of the budget associated with the campaign, thereby replacing it with another budget. To identify campaigns using a particular budget, see Retrieving the list of campaigns for a given Budget.

Removing a budget

Like campaigns, budgets cannot be completely deleted—you can only set its status to REMOVED To do that, first ensure that no ENABLED or PAUSED campaigns are using the budget. Next, send a BudgetService.mutate() REMOVE request with the ID of the budget. If its ReferenceCount field is greater than 0, there are ENABLED or PAUSED campaigns still using the budget. (A budget's ReferenceCount field can be retrieved as the ReferenceCount field in a BudgetService.get() operation, or the BudgetReferenceCount field in a CampaignService.get() operation.)

// Retrieve a budget with budget ID of interest
Long budgetId =  Long.parseLong("INSERT_BUDGET_ID_HERE");
Selector selector = new SelectorBuilder()
    .fields(BudgetField.BudgetId, BudgetField.BudgetReferenceCount)
    .orderAscBy(BudgetField.BudgetId)
    .equals(BudgetField.BudgetId, budgetId.toString())
    .build();
// (Code Excluded) Get a Budget object from the result of BudgetService.get
// Remove the budget only if its referenceCount == 0 (no campaigns are using it)
if (budget.getReferenceCount() == 0) {
    BudgetServiceInterface budgetService =
        adWordsServices.get(session, BudgetServiceInterface.class);
    BudgetOperation operation = new BudgetOperation();
    operation.setOperand(budget);
    operation.setOperator(Operator.REMOVE);
    BudgetOperation[] operations = new BudgetOperation[] {operation};
    BudgetReturnValue result = budgetService.mutate(operations);
}

Additionally, you can remove a non-shared budget being used by a single campaign by removing that campaign. When you set the status of such a campaign to REMOVED, the status of its non-shared budget will also be set to REMOVED automatically.

Retrieving the list of campaigns for a given budget

Getting a list of campaigns that are using the same budget can be helpful when balancing budget utilization. Make a CampaignService.get() operation requesting, at minimum, the Id field along with a predicate of BudgetId equal to the desired budget's ID:

Long budgetId =  Long.parseLong("INSERT_BUDGET_ID_HERE");
Selector selector = new SelectorBuilder()
    .fields(CampaignField.Id, CampaignField.BudgetId)
    .orderAscBy(CampaignField.Id)
    .equals(CampaignField.BudgetId, budgetId.toString())
    .build();

Alternatively, you can use this AWQL statement to get the same results:

SELECT BudgetId, BudgetName, Amount, IsBudgetExplicitlyShared,
       AssociatedCampaignId, Impressions
FROM BUDGET_PERFORMANCE_REPORT
WHERE BudgetId = <YOUR_BUDGET_ID>

Tracking performance

You can retrieve the budget performance stats for your campaigns using a Budget Performance Report, which includes all statistics aggregated by default at the budget level, one row per budget. If segment fields are used, you may get more than one row per budget. See segmentation for details.

Restrictions

Any campaign that has Campaign Experiments enabled must have its own non-shared budget.

Common Errors

Error	Description
BudgetError.CANNOT_UPDATE_BUDGET_TO_IMPLICITLY_SHARED	Indicates that you tried to set the isExplicitlyShared value of a budget from true to false in a SET operation. Once a budget is explicitly shared (isExplicitlyShared = true), you cannot change isExplicitlyShared back to false.
EntityCountLimitExceeded.ACCOUNT_LIMIT	Indicates you've reached the maximum number of budgets in an account.
CampaignError.CAMPAIGN_CANNOT_USE_SHARED_BUDGET	The campaign to which you're trying to add the budget is using campaign experiments, and the budget is already being used by another campaign.
BudgetError.CANNOT_EDIT_SHARED_BUDGET	You're trying to modify the budget associated with a campaign using the CampaignService. You can only modify budgets via the BudgetService.
BudgetError.BUDGET_IN_USE	You're trying to remove a budget associated with one or more active or paused campaigns.