Google Ads

Campaign Budgets  |  AdWords API  |  Google Developers

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(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 operations = new List();

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 = 

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 = 

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.

Leave a Reply

Your email address will not be published. Required fields are marked *

Back to top button
Close