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

Campaign Budgets

Budgets are used to manage the amount of money spent for each of your AdWords campaign. They can be created via the AdWords user interface or the AdWords API. A budget can either be shared across many campaigns or confined to a single campaign. When you create a new Budget using the AdWords API, it's shareable by default. You can verify this by checking if isExplicitlyShared is set to true.

A budget can have one of two states:

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

Explicitly shared budgets appear in an account's Shared Library in the AdWords user interface, whereas a non-shared budget will only appear within its associated campaign's Settings. For the AdWords API, you can make an API call to the BudgetService to check a budget's isExplicitlyShared value.

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 code example (Java) 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();
BudgetOperation budgetOperation = new BudgetOperation();

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

// Set the bidding strategy configuration.
BiddingStrategyConfiguration biddingStrategyConfiguration =
    new BiddingStrategyConfiguration();

// Only the budgetId should be set.
Budget budget = new Budget();
CampaignServiceInterface campaignService =
    adWordsServices.get(session, CampaignServiceInterface.class);
CampaignOperation operation = new CampaignOperation();
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 replacing it with another budget, i.e., changing the ID of the budget associated with the campaign. To identify campaigns that are 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. There are ENABLED or PAUSED campaigns still using the budget if its ReferenceCount field is greater than 0. (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)
    .equals(BudgetField.BudgetId, budgetId.toString())
// (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();
    BudgetOperation[] operations = new BudgetOperation[] {operation};
    BudgetReturnValue result = budgetService.mutate(operations);

Retrieving the list of campaigns for a given budget

Getting the 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 equals to the desired budget's ID:

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

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

SELECT BudgetId, BudgetName, Amount, IsBudgetExplicitlyShared,
       AssociatedCampaignId, Impressions

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.


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 You've 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 You've reached the maximum number of budgets in an account.
CampaignError.CAMPAIGN_CANNOT_USE_SHARED_BUDGET The campaign you're trying to add the budget to 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.

Send feedback about...

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