The AdWords API is no longer supported. Use the Google Ads API instead.

Campaign Budgets

Stay organized with collections Save and categorize content based on your preferences.

Budgets are used to manage the amount of money spent for your Google Ads 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

Explicitly shared budgets appear in an account's Shared Library in the Google Ads UI, 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.v201809.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='v201809')

# 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::v201809::Budget->new({
    # Required attributes.
    name => "Interplanetary budget #" . uniqid(),
    amount =>
      Google::Ads::AdWords::v201809::Money->new({microAmount => 5000000}),
    deliveryMethod => "STANDARD"
});

my $budget_operation = Google::Ads::AdWords::v201809::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.v201809.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(DateTime.now().plusDays(1).toString("yyyyMMdd"));
campaign.setEndDate(DateTime.now().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::v201809::Campaign->new({
      name => "Interplanetary Cruise #" . uniqid(),
      # Bidding strategy (required).
      biddingStrategyConfiguration =>
        Google::Ads::AdWords::v201809::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::v201809::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::v201809::NetworkSetting->new({
          targetGoogleSearch         => 1,
          targetSearchNetwork        => 1,
          targetContentNetwork       => 1,
          targetPartnerSearchNetwork => 0
        }
      ),
      # Advertising channel type (required).
      advertisingChannelType => "SEARCH",
      # Frequency cap (non-required).
      frequencyCap => Google::Ads::AdWords::v201809::FrequencyCap->new({
          impressions => 5,
          timeUnit    => "DAY",
          level       => "ADGROUP"
        }
      ),
      settings => [
        # Advanced location targeting settings (non-required).
        Google::Ads::AdWords::v201809::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::v201809::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.