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.

In the following example that creates a new budget, the budget is shared because isExplicitlyShared is left at its default value of true.

Java

// 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(50_000_000L);
sharedBudget.setAmount(budgetAmount);
sharedBudget.setDeliveryMethod(BudgetBudgetDeliveryMethod.STANDARD);

BudgetOperation budgetOperation = new BudgetOperation();
budgetOperation.setOperand(sharedBudget);
budgetOperation.setOperator(Operator.ADD);

// Add the budget
Long budgetId =
    budgetService.mutate(new BudgetOperation[] {budgetOperation}).getValue(0).getBudgetId();

C#

using (BudgetService budgetService =
    (BudgetService) user.GetService(AdWordsService.v201806.BudgetService)) {

  // Create the campaign budget.
  Budget budget = new Budget {
    name = "Interplanetary Cruise Budget #" + ExampleUtilities.GetRandomString(),
    deliveryMethod = BudgetBudgetDeliveryMethod.STANDARD,
    amount = new Money {
      microAmount = 500000
    }
  };

  BudgetOperation budgetOperation = new BudgetOperation {
    @operator = Operator.ADD,
    operand = budget
  };

  try {
    BudgetReturnValue budgetRetval = budgetService.mutate(
        new BudgetOperation[] { budgetOperation });
    return budgetRetval.value[0];
  } catch (Exception e) {
    throw new System.ApplicationException("Failed to add shared budget.", e);
  }
}

Python

budget_service = client.GetService('BudgetService', version='v201806')

# Create a budget, which can be shared by multiple campaigns.
budget = {
    'name': 'Interplanetary budget #%s' % uuid.uuid4(),
    'amount': {
        'microAmount': '50000000'
    },
    'deliveryMethod': 'STANDARD'
}

budget_operations = [{
    'operator': 'ADD',
    'operand': budget
}]

# Add the budget.
budget_id = budget_service.mutate(budget_operations)['value'][0][
    'budgetId']

PHP

$budgetService = $adWordsServices->get($session, BudgetService::class);

// Create the shared budget (required).
$budget = new Budget();
$budget->setName('Interplanetary Cruise Budget #' . uniqid());
$money = new Money();
$money->setMicroAmount(50000000);
$budget->setAmount($money);
$budget->setDeliveryMethod(BudgetBudgetDeliveryMethod::STANDARD);

$operations = [];

// Create a budget operation.
$operation = new BudgetOperation();
$operation->setOperand($budget);
$operation->setOperator(Operator::ADD);
$operations[] = $operation;

// Create the budget on the server.
$result = $budgetService->mutate($operations);
$budget = $result->getValue()[0];

Perl

# Create a budget, which can be shared by multiple campaigns.
my $budget = Google::Ads::AdWords::v201806::Budget->new({
    # Required attributes.
    name => "Interplanetary budget #" . uniqid(),
    amount =>
      Google::Ads::AdWords::v201806::Money->new({microAmount => 5000000}),
    deliveryMethod => "STANDARD"
});

my $budget_operation = Google::Ads::AdWords::v201806::BudgetOperation->new({
    operator => "ADD",
    operand  => $budget
});

# Add budget.
my $budgetId =
  $client->BudgetService()->mutate({operations => ($budget_operation)})
  ->get_value()->get_budgetId()->get_value();

Ruby

# Create a budget, which can be shared by multiple campaigns.
budget_srv = adwords.service(:BudgetService, API_VERSION)
budget = {
  :name => 'Interplanetary budget #%d' % (Time.new.to_f * 1000).to_i,
  :amount => {:micro_amount => 50000000},
  :delivery_method => 'STANDARD'
}
budget_operation = {:operator => 'ADD', :operand => budget}

# Add budget.
return_budget = budget_srv.mutate([budget_operation])
budget_id = return_budget[:value].first[:budget_id]

VB.NET

Using budgetService As BudgetService = CType(user.GetService(
    AdWordsService.v201806.BudgetService), BudgetService)

  ' Create the campaign budget.
  Dim budget As New Budget
  budget.name = "Interplanetary Cruise Budget #" & ExampleUtilities.GetRandomString
  budget.deliveryMethod = BudgetBudgetDeliveryMethod.STANDARD
  budget.amount = New Money
  budget.amount.microAmount = 50000000

  Dim budgetOperation As New BudgetOperation
  budgetOperation.operator = [Operator].ADD
  budgetOperation.operand = budget

  Try
    Dim budgetRetval As BudgetReturnValue = budgetService.mutate(
        New BudgetOperation() {budgetOperation})
    Return budgetRetval.value(0)
  Catch e As Exception
    Throw New System.ApplicationException("Failed to add shared budget.", e)
  End Try
End Using

Assigning a budget to a campaign

After you have created or identified a Budget with BudgetService, 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 below.

Java

// Get the CampaignService.
CampaignServiceInterface campaignService =
    adWordsServices.get(session, CampaignServiceInterface.class);

// Create campaign.
Campaign campaign = new Campaign();
campaign.setName("Interplanetary Cruise #" + System.currentTimeMillis());

// Recommendation: Set the campaign to PAUSED when creating it to prevent
// the ads from immediately serving. Set to ENABLED once you've added
// targeting and the ads are ready to serve.
campaign.setStatus(CampaignStatus.PAUSED);

BiddingStrategyConfiguration biddingStrategyConfiguration = new BiddingStrategyConfiguration();
biddingStrategyConfiguration.setBiddingStrategyType(BiddingStrategyType.MANUAL_CPC);

// You can optionally provide a bidding scheme in place of the type.
ManualCpcBiddingScheme cpcBiddingScheme = new ManualCpcBiddingScheme();
biddingStrategyConfiguration.setBiddingScheme(cpcBiddingScheme);

campaign.setBiddingStrategyConfiguration(biddingStrategyConfiguration);

// You can optionally provide these field(s).
campaign.setStartDate(new DateTime().plusDays(1).toString("yyyyMMdd"));
campaign.setEndDate(new DateTime().plusDays(30).toString("yyyyMMdd"));
campaign.setFrequencyCap(new FrequencyCap(5L, TimeUnit.DAY, Level.ADGROUP));

// Only the budgetId should be sent, all other fields will be ignored by CampaignService.
Budget budget = new Budget();
budget.setBudgetId(budgetId);
campaign.setBudget(budget);

campaign.setAdvertisingChannelType(AdvertisingChannelType.SEARCH);

// Set the campaign network options to Search and Search Network.
NetworkSetting networkSetting = new NetworkSetting();
networkSetting.setTargetGoogleSearch(true);
networkSetting.setTargetSearchNetwork(true);
networkSetting.setTargetContentNetwork(false);
networkSetting.setTargetPartnerSearchNetwork(false);
campaign.setNetworkSetting(networkSetting);

// Set options that are not required.
GeoTargetTypeSetting geoTarget = new GeoTargetTypeSetting();
geoTarget.setPositiveGeoTargetType(GeoTargetTypeSettingPositiveGeoTargetType.DONT_CARE);
campaign.setSettings(new Setting[] {geoTarget});

// You can create multiple campaigns in a single request.
Campaign campaign2 = new Campaign();
campaign2.setName("Interplanetary Cruise banner #" + System.currentTimeMillis());
campaign2.setStatus(CampaignStatus.PAUSED);
BiddingStrategyConfiguration biddingStrategyConfiguration2 = new BiddingStrategyConfiguration();
biddingStrategyConfiguration2.setBiddingStrategyType(BiddingStrategyType.MANUAL_CPC);
campaign2.setBiddingStrategyConfiguration(biddingStrategyConfiguration2);

Budget budget2 = new Budget();
budget2.setBudgetId(budgetId);
campaign2.setBudget(budget2);

campaign2.setAdvertisingChannelType(AdvertisingChannelType.DISPLAY);

// Create operations.
CampaignOperation operation = new CampaignOperation();
operation.setOperand(campaign);
operation.setOperator(Operator.ADD);
CampaignOperation operation2 = new CampaignOperation();
operation2.setOperand(campaign2);
operation2.setOperator(Operator.ADD);

CampaignOperation[] operations = new CampaignOperation[] {operation, operation2};

// Add campaigns.
CampaignReturnValue result = campaignService.mutate(operations);

// Display campaigns.
for (Campaign campaignResult : result.getValue()) {
  System.out.printf("Campaign with name '%s' and ID %d was added.%n", campaignResult.getName(),
      campaignResult.getId());
}

C#

List<CampaignOperation> operations = new List<CampaignOperation>();

for (int i = 0; i < NUM_ITEMS; i++) {
  // Create the campaign.
  Campaign campaign = new Campaign {
    name = "Interplanetary Cruise #" + ExampleUtilities.GetRandomString(),
    advertisingChannelType = AdvertisingChannelType.SEARCH,

    // Recommendation: Set the campaign to PAUSED when creating it to prevent
    // the ads from immediately serving. Set to ENABLED once you've added
    // targeting and the ads are ready to serve.
    status = CampaignStatus.PAUSED
  };

  BiddingStrategyConfiguration biddingConfig = new BiddingStrategyConfiguration {
    biddingStrategyType = BiddingStrategyType.MANUAL_CPC
  };
  campaign.biddingStrategyConfiguration = biddingConfig;

  campaign.budget = new Budget {
    budgetId = budget.budgetId
  };

  // Set the campaign network options.
  campaign.networkSetting = new NetworkSetting {
    targetGoogleSearch = true,
    targetSearchNetwork = true,
    targetContentNetwork = false,
    targetPartnerSearchNetwork = false
  };

  // Set the campaign settings for Advanced location options.
  GeoTargetTypeSetting geoSetting = new GeoTargetTypeSetting {
    positiveGeoTargetType = GeoTargetTypeSettingPositiveGeoTargetType.DONT_CARE,
    negativeGeoTargetType = GeoTargetTypeSettingNegativeGeoTargetType.DONT_CARE
  };

  campaign.settings = new Setting[] { geoSetting };

  // Optional: Set the start date.
  campaign.startDate = DateTime.Now.AddDays(1).ToString("yyyyMMdd");

  // Optional: Set the end date.
  campaign.endDate = DateTime.Now.AddYears(1).ToString("yyyyMMdd");

  // Optional: Set the frequency cap.
  FrequencyCap frequencyCap = new FrequencyCap {
    impressions = 5,
    level = Level.ADGROUP,
    timeUnit = TimeUnit.DAY
  };
  campaign.frequencyCap = frequencyCap;

  // Create the operation.
  CampaignOperation operation = new CampaignOperation {
    @operator = Operator.ADD,
    operand = campaign
  };

  operations.Add(operation);
}

try {
  // Add the campaign.
  CampaignReturnValue retVal = campaignService.mutate(operations.ToArray());

  // Display the results.
  if (retVal != null && retVal.value != null && retVal.value.Length > 0) {
    foreach (Campaign newCampaign in retVal.value) {
      Console.WriteLine("Campaign with name = '{0}' and id = '{1}' was added.",
          newCampaign.name, newCampaign.id);
    }
  } else {
    Console.WriteLine("No campaigns were added.");
  }
} catch (Exception e) {
  throw new System.ApplicationException("Failed to add campaigns.", e);
}

Python

operations = [{
    'operator': 'ADD',
    'operand': {
        'name': 'Interplanetary Cruise #%s' % uuid.uuid4(),
        # Recommendation: Set the campaign to PAUSED when creating it to
        # stop the ads from immediately serving. Set to ENABLED once you've
        # added targeting and the ads are ready to serve.
        'status': 'PAUSED',
        'advertisingChannelType': 'SEARCH',
        'biddingStrategyConfiguration': {
            'biddingStrategyType': 'MANUAL_CPC',
        },
        'endDate': (datetime.datetime.now() +
                    datetime.timedelta(365)).strftime('%Y%m%d'),
        # Note that only the budgetId is required
        'budget': {
            'budgetId': budget_id
        },
        'networkSetting': {
            'targetGoogleSearch': 'true',
            'targetSearchNetwork': 'true',
            'targetContentNetwork': 'false',
            'targetPartnerSearchNetwork': 'false'
        },
        # Optional fields
        'startDate': (datetime.datetime.now() +
                      datetime.timedelta(1)).strftime('%Y%m%d'),
        'frequencyCap': {
            'impressions': '5',
            'timeUnit': 'DAY',
            'level': 'ADGROUP'
        },
        'settings': [
            {
                'xsi_type': 'GeoTargetTypeSetting',
                'positiveGeoTargetType': 'DONT_CARE',
                'negativeGeoTargetType': 'DONT_CARE'
            }
        ]
    }
}, {
    'operator': 'ADD',
    'operand': {
        'name': 'Interplanetary Cruise banner #%s' % uuid.uuid4(),
        'status': 'PAUSED',
        'biddingStrategyConfiguration': {
            'biddingStrategyType': 'MANUAL_CPC'
        },
        'endDate': (datetime.datetime.now() +
                    datetime.timedelta(365)).strftime('%Y%m%d'),
        # Note that only the budgetId is required
        'budget': {
            'budgetId': budget_id
        },
        'advertisingChannelType': 'DISPLAY'
    }
}]
campaigns = campaign_service.mutate(operations)

# Display results.
for campaign in campaigns['value']:
  print ('Campaign with name "%s" and id "%s" was added.'
         % (campaign['name'], campaign['id']))

PHP

$campaignService = $adWordsServices->get($session, CampaignService::class);

$operations = [];

// Create a campaign with required and optional settings.
$campaign = new Campaign();
$campaign->setName('Interplanetary Cruise #' . uniqid());
$campaign->setAdvertisingChannelType(AdvertisingChannelType::SEARCH);

// Set shared budget (required).
$campaign->setBudget(new Budget());
$campaign->getBudget()->setBudgetId($budget->getBudgetId());

// Set bidding strategy (required).
$biddingStrategyConfiguration = new BiddingStrategyConfiguration();
$biddingStrategyConfiguration->setBiddingStrategyType(
    BiddingStrategyType::MANUAL_CPC
);

// You can optionally provide a bidding scheme in place of the type.
$biddingScheme = new ManualCpcBiddingScheme();
$biddingStrategyConfiguration->setBiddingScheme($biddingScheme);

$campaign->setBiddingStrategyConfiguration($biddingStrategyConfiguration);

// Set network targeting (optional).
$networkSetting = new NetworkSetting();
$networkSetting->setTargetGoogleSearch(true);
$networkSetting->setTargetSearchNetwork(true);
$networkSetting->setTargetContentNetwork(true);
$campaign->setNetworkSetting($networkSetting);

// Set additional settings (optional).
// Recommendation: Set the campaign to PAUSED when creating it to stop
// the ads from immediately serving. Set to ENABLED once you've added
// targeting and the ads are ready to serve.
$campaign->setStatus(CampaignStatus::PAUSED);
$campaign->setStartDate(date('Ymd', strtotime('+1 day')));
$campaign->setEndDate(date('Ymd', strtotime('+1 month')));

// Set frequency cap (optional).
$frequencyCap = new FrequencyCap();
$frequencyCap->setImpressions(5);
$frequencyCap->setTimeUnit(TimeUnit::DAY);
$frequencyCap->setLevel(Level::ADGROUP);
$campaign->setFrequencyCap($frequencyCap);

// Set advanced location targeting settings (optional).
$geoTargetTypeSetting = new GeoTargetTypeSetting();
$geoTargetTypeSetting->setPositiveGeoTargetType(
    GeoTargetTypeSettingPositiveGeoTargetType::DONT_CARE
);
$geoTargetTypeSetting->setNegativeGeoTargetType(
    GeoTargetTypeSettingNegativeGeoTargetType::DONT_CARE
);
$campaign->setSettings([$geoTargetTypeSetting]);

// Create a campaign operation and add it to the operations list.
$operation = new CampaignOperation();
$operation->setOperand($campaign);
$operation->setOperator(Operator::ADD);
$operations[] = $operation;

// Create a campaign with only required settings.
$campaign = new Campaign();
$campaign->setName('Interplanetary Cruise #' . uniqid());
$campaign->setAdvertisingChannelType(AdvertisingChannelType::DISPLAY);

// Set shared budget (required).
$campaign->setBudget(new Budget());
$campaign->getBudget()->setBudgetId($budget->getBudgetId());

// Set bidding strategy (required).
$biddingStrategyConfiguration = new BiddingStrategyConfiguration();
$biddingStrategyConfiguration->setBiddingStrategyType(
    BiddingStrategyType::MANUAL_CPC
);
$campaign->setBiddingStrategyConfiguration($biddingStrategyConfiguration);

$campaign->setStatus(CampaignStatus::PAUSED);

// Create a campaign operation and add it to the operations list.
$operation = new CampaignOperation();
$operation->setOperand($campaign);
$operation->setOperator(Operator::ADD);
$operations[] = $operation;

// Create the campaigns on the server and print out some information for
// each created campaign.
$result = $campaignService->mutate($operations);
foreach ($result->getValue() as $campaign) {
    printf(
        "Campaign with name '%s' and ID %d was added.\n",
        $campaign->getName(),
        $campaign->getId()
    );
}

Perl

# Create campaigns.
my $num_campaigns = 2;
my @operations    = ();
for (my $i = 0 ; $i < $num_campaigns ; $i++) {
  my (undef, undef, undef, $mday, $mon, $year) = localtime(time);
  my $today = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday);
  (undef, undef, undef, $mday, $mon, $year) = localtime(time + 60 * 60 * 24);
  my $tomorrow = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday);
  my $campaign = Google::Ads::AdWords::v201806::Campaign->new({
      name => "Interplanetary Cruise #" . uniqid(),
      # Bidding strategy (required).
      biddingStrategyConfiguration =>
        Google::Ads::AdWords::v201806::BiddingStrategyConfiguration->new({
          biddingStrategyType => "MANUAL_CPC",
          # You can optionally provide a bidding scheme in place of the type.
        }
        ),
      # Budget (required) - note only the budgetId is required.
      budget =>
        Google::Ads::AdWords::v201806::Budget->new({budgetId => $budgetId}),
      # Create a Search Network with Display Select campaign.
      # To create a Display Only campaign, omit networkSetting and use the
      # DISPLAY advertisingChannelType.
      # NetworkSetting (optional).
      networkSetting => Google::Ads::AdWords::v201806::NetworkSetting->new({
          targetGoogleSearch         => 1,
          targetSearchNetwork        => 1,
          targetContentNetwork       => 1,
          targetPartnerSearchNetwork => 0
        }
      ),
      # Advertising channel type (required).
      advertisingChannelType => "SEARCH",
      # Frequency cap (non-required).
      frequencyCap => Google::Ads::AdWords::v201806::FrequencyCap->new({
          impressions => 5,
          timeUnit    => "DAY",
          level       => "ADGROUP"
        }
      ),
      settings => [
        # Advanced location targeting settings (non-required).
        Google::Ads::AdWords::v201806::GeoTargetTypeSetting->new({
            positiveGeoTargetType => "DONT_CARE",
            negativeGeoTargetType => "DONT_CARE"
          }
        ),
      ],
      # Additional properties (non-required).
      startDate                   => $today,
      endDate                     => $tomorrow,
      # Recommendation: Set the campaign to PAUSED when creating it to stop
      # the ads from immediately serving. Set to ENABLED once you've added
      # targeting and the ads are ready to serve.
      status                      => "PAUSED"
    });

  # Create operation.
  my $campaign_operation =
    Google::Ads::AdWords::v201806::CampaignOperation->new({
      operator => "ADD",
      operand  => $campaign
    });
  push @operations, $campaign_operation;
}

# Add campaigns.
my $result = $client->CampaignService()->mutate({operations => \@operations});

# Display campaigns.
foreach my $campaign (@{$result->get_value()}) {
  printf "Campaign with name \"%s\" and id \"%s\" was added.\n",
    $campaign->get_name(), $campaign->get_id();
}

Ruby

campaign_srv = adwords.service(:CampaignService, API_VERSION)

# Create campaigns.
campaigns = [
  {
    :name => "Interplanetary Cruise #%d" % (Time.new.to_f * 1000).to_i,
    # Recommendation: Set the campaign to PAUSED when creating it to stop the
    # ads from immediately serving. Set to ENABLED once you've added
    # targeting and the ads are ready to serve.
    :status => 'PAUSED',
    :bidding_strategy_configuration => {
      :bidding_strategy_type => 'MANUAL_CPC'
    },
    # Budget (required) - note only the budget ID is required.
    :budget => {:budget_id => budget_id},
    :advertising_channel_type => 'SEARCH',
    # Optional fields:
    :start_date =>
        DateTime.parse((Date.today + 1).to_s).strftime('%Y%m%d'),
    :network_setting => {
      :target_google_search => true,
      :target_search_network => true,
      :target_content_network => true
    },
    :settings => [
      {
        :xsi_type => 'GeoTargetTypeSetting',
        :positive_geo_target_type => 'DONT_CARE',
        :negative_geo_target_type => 'DONT_CARE'
      }
    ],
    :frequency_cap => {
      :impressions => '5',
      :time_unit => 'DAY',
      :level => 'ADGROUP'
    }
  },
  {
    :name => "Interplanetary Cruise banner #%d" % (Time.new.to_f * 1000).to_i,
    :status => 'PAUSED',
    :bidding_strategy_configuration => {
      :bidding_strategy_type => 'MANUAL_CPC'
    },
    :budget => {:budget_id => budget_id},
    :advertising_channel_type => 'DISPLAY'
  }
]

# Prepare for adding campaign.
operations = campaigns.map do |campaign|
  {:operator => 'ADD', :operand => campaign}
end

# Add campaign.
response = campaign_srv.mutate(operations)
if response and response[:value]
  response[:value].each do |campaign|
    puts "Campaign with name '%s' and ID %d was added." %
        [campaign[:name], campaign[:id]]
  end
else
  raise new StandardError, 'No campaigns were added.'
end

VB.NET

  Dim operations As New List(Of CampaignOperation)

  For i As Integer = 1 To NUM_ITEMS
    ' Create the campaign.
    Dim campaign As New Campaign
    campaign.name = "Interplanetary Cruise #" & ExampleUtilities.GetRandomString
    campaign.advertisingChannelType = AdvertisingChannelType.SEARCH

    ' Recommendation: Set the campaign to PAUSED when creating it to prevent
    ' the ads from immediately serving. Set to ENABLED once you've added
    ' targeting and the ads are ready to serve.
    campaign.status = CampaignStatus.PAUSED

    Dim biddingConfig As New BiddingStrategyConfiguration()
    biddingConfig.biddingStrategyType = BiddingStrategyType.MANUAL_CPC
    campaign.biddingStrategyConfiguration = biddingConfig

    ' Set the campaign budget.
    campaign.budget = New Budget
    campaign.budget.budgetId = budget.budgetId

    ' Set the campaign network options.
    campaign.networkSetting = New NetworkSetting
    campaign.networkSetting.targetGoogleSearch = True
    campaign.networkSetting.targetSearchNetwork = True
    campaign.networkSetting.targetContentNetwork = False
    campaign.networkSetting.targetPartnerSearchNetwork = False

    ' Set the campaign geo target and keyword match settings.
    Dim geoSetting As New GeoTargetTypeSetting
    geoSetting.positiveGeoTargetType = GeoTargetTypeSettingPositiveGeoTargetType.DONT_CARE
    geoSetting.negativeGeoTargetType = GeoTargetTypeSettingNegativeGeoTargetType.DONT_CARE

    campaign.settings = New Setting() {geoSetting}

    ' Optional: Set the start date.
    campaign.startDate = DateTime.Now.AddDays(1).ToString("yyyyMMdd")

    ' Optional: Set the end date.
    campaign.endDate = DateTime.Now.AddYears(1).ToString("yyyyMMdd")

    ' Optional: Set the frequency cap.
    Dim frequencyCap As New FrequencyCap
    frequencyCap.impressions = 5
    frequencyCap.level = Level.ADGROUP
    frequencyCap.timeUnit = TimeUnit.DAY
    campaign.frequencyCap = frequencyCap

    ' Create the operation.
    Dim operation As New CampaignOperation
    operation.operator = [Operator].ADD
    operation.operand = campaign
    operations.Add(operation)
  Next

  Try
    ' Add the campaign.
    Dim retVal As CampaignReturnValue = campaignService.mutate(operations.ToArray())

    ' Display the results.
    If ((Not retVal Is Nothing) AndAlso (Not retVal.value Is Nothing) AndAlso
      (retVal.value.Length > 0)) Then
      For Each newCampaign As Campaign In retVal.value
        Console.WriteLine("Campaign with name = '{0}' and id = '{1}' was added.",
            newCampaign.name, newCampaign.id)
      Next
    Else
      Console.WriteLine("No campaigns were added.")
    End If
  Catch e As Exception
    Throw New System.ApplicationException("Failed to add campaigns.", e)
  End Try
End Using

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 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, a budget cannot be completely deleted—you can only set its status to REMOVED.

Before removing a budget, ensure that no ENABLED or PAUSED campaigns are using it by checking its referenceCount. If this field is greater than 0, there are ENABLED or PAUSED campaigns still using the budget. You can retrieve the budget's referenceCount via a BudgetService.get() operation, or the referenceCount field from a CampaignService.get() operation.

Once you determine that a Budget is no longer used, send a BudgetOperation to BudgetService.mutate() with:

• operator = SET
• operand set to a Budget with:
  • budgetId set to the ID of the budget
  • status set to REMOVED

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. The following AWQL query to CampaignService will return all campaigns for the specified budget ID:

SELECT Id WHERE BudgetId = <YOUR_BUDGET_ID>

Alternatively, you can use this AWQL statement to get the same information from the Campaign Performance Report:

SELECT CampaignId, BudgetId, IsBudgetExplicitlyShared, Impressions
FROM CAMPAIGN_PERFORMANCE_REPORT
WHERE BudgetId = <YOUR_BUDGET_ID>

Tracking performance

You can retrieve the budget performance stats for your campaigns using the 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.