Account Budget

Account budgets control what an account can spend over a specific period of time by defining budget properties like spend limit, start time, and end time. They must point to one of the account's billing setups, to indicate which specific Payments account will be billed. You can create, update, and remove the AccountBudget by sending AccountBudgetProposal objects.

AccountBudget objects represent the end result of applying proposals. After a proposal is approved, its changes (subject to any adjustments) will result in the creation of a new account budget or an update to an existing one. This depends on the proposal_type specified in the request.

AccountBudgetProposalType Description
CREATE Creates a new account budget, which must be approved before use.
UPDATE Modifies an existing account budget.
END Sets an account budget's end time to the current time.
REMOVE Removes an account budget prior to its start time.

The sections below describe the behavior of each proposal type.

Creating an account budget proposal

Creating a new account budget allows you to control a customer's spending behaviour. Use the AccountBudgetProposalService to create a new AccountBudgetProposal. You should set proposal_type to CREATE to specify that a new budget should be created. Refer to the management section of this guide for other operations.

Remember to use a billing setup with a payments account where you have write access. Refer to the billing setup guide for details.

The following example demonstrates how to create a new budget proposal.

Java

private void runExample(GoogleAdsClient googleAdsClient, long customerId, long billingSetupId) {
  // Creates an AccountBudgetProposal. This will be reviewed offline by Google Ads, and if
  // approved will become an AccountBudget.
  AccountBudgetProposal proposal =
      AccountBudgetProposal.newBuilder()
          .setBillingSetup(StringValue.of(ResourceNames.billingSetup(customerId, billingSetupId)))
          .setProposalType(AccountBudgetProposalType.CREATE)
          .setProposedName(StringValue.of("Account Budget (example)"))

          // Specifies the account budget starts immediately.
          .setProposedStartTimeType(TimeType.NOW)
          // Alternatively you can specify a specific start time. Refer to the
          // AccountBudgetProposal
          // resource documentation for allowed formats.
          //
          // .setProposedStartDateTime(StringValue.of("2020-01-02 03:04:05"))

          // Specifies that the budget runs forever.
          .setProposedEndTimeType(TimeType.FOREVER)
          // Alternatively you can specify a specific end time. Allowed formats are as above.
          // .setProposedEndDateTime(StringValue.of("2021-02-03 04:05:06"))

          // Optional: sets notes for the budget. These are free text and do not effect budget
          // delivery.
          // .setProposedNotes(StringValue.of("Received prepayment of $0.01"))

          // Sets the spending limit to 0.01, measured in the Google Ads account currency.
          .setProposedSpendingLimitMicros(Int64Value.of(10_000))

          // Optional: sets PO number for record keeping. This value is at the user's
          // discretion, and has no effect on Google Billing & Payments.
          // .setProposedPurchaseOrderNumber(StringValue.of("PO number 12345"))
          .build();

  // Creates an operation which will add the new AccountBudgetProposal.
  AccountBudgetProposalOperation operation =
      AccountBudgetProposalOperation.newBuilder().setCreate(proposal).build();

  try (AccountBudgetProposalServiceClient accountBudgetProposalServiceClient =
      googleAdsClient.getLatestVersion().createAccountBudgetProposalServiceClient()) {
    // Sends the request to the Account Budget Proposal Service.
    MutateAccountBudgetProposalResponse response =
        accountBudgetProposalServiceClient.mutateAccountBudgetProposal(
            String.valueOf(customerId), operation);

    System.out.printf(
        "Account budget proposal created: %s.%n", response.getResult().getResourceName());
  }
}

C#

public void Run(GoogleAdsClient client, long customerId, long billingSetupId)
{
    // Get the AccountBudgetProposalServiceClient.
    AccountBudgetProposalServiceClient proposalService =
        client.GetService(Services.V5.AccountBudgetProposalService);

    // Create an AccountBudgetProposal.
    // The proposal will be reviewed offline by Google Ads, and if approved will
    // become an AccountBudget.
    AccountBudgetProposal proposal = new AccountBudgetProposal()
    {
        BillingSetup = ResourceNames.BillingSetup(customerId, billingSetupId),
        ProposalType = AccountBudgetProposalType.Create,
        ProposedName = "Account Budget (example)",

        // Specify the account budget starts immediately
        ProposedStartTimeType = TimeType.Now,
        // Alternatively, you can specify a specific start time. Refer to the
        // AccountBudgetProposal resource documentation for allowed formats.
        //
        //ProposedStartDateTime = "2020-01-02 03:04:05",

        // Specify that the budget runs forever.
        ProposedEndTimeType = TimeType.Forever,
        // Alternatively you can specify a specific end time. Allowed formats are as above.
        //ProposedEndDateTime = "2021-02-03 04:05:06",

        // Optional: set notes for the budget. These are free text and do not effect budget
        // delivery.
        //ProposedNotes = "Received prepayment of $0.01",

        // Set the spending limit to 0.01, measured in the Google Ads account currency.
        ProposedSpendingLimitMicros = 10_000

        // Optional: set PO number for record keeping. This value is at the user's
        // discretion, and has no effect on Google Billing & Payments.
        //ProposedPurchaseOrderNumber = "PO number 12345"
    };

    // Create an operation which will add the new AccountBudgetProposal
    AccountBudgetProposalOperation operation = new AccountBudgetProposalOperation()
    {
        Create = proposal
    };

    try
    {
        // Send the request to the Account Budget Proposal Service.
        MutateAccountBudgetProposalResponse response = proposalService.
            MutateAccountBudgetProposal(customerId.ToString(), operation);

        // Display the results.
        Console.WriteLine($"Account budget proposal '{response.Result.ResourceName}' " +
            "was created.");
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }

}

PHP

public static function runExample(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    int $billingSetupId
) {
    // Constructs an account budget proposal.
    $accountBudgetProposal = new AccountBudgetProposal([
        'billing_setup' => new StringValue(
            ['value' => ResourceNames::forBillingSetup($customerId, $billingSetupId)]
        ),
        'proposal_type' => AccountBudgetProposalType::CREATE,
        'proposed_name' => new StringValue(['value' => 'Account Budget (example)']),
        // Specifies the account budget starts immediately.
        'proposed_start_time_type' => TimeType::NOW,
        // Alternatively you can specify a specific start time. Refer to the
        // AccountBudgetProposal class for allowed formats.
        //
        // 'proposed_start_date_time' => new StringValue(['value' => '2020-01-02 03:04:05']),

        // Specify that the budget runs forever.
        'proposed_end_time_type' => TimeType::FOREVER,
        // Alternatively you can specify a specific end time. Allowed formats are as above.
        // 'proposed_end_date_time' => new StringValue(['value' => '2021-02-03 04:05:06']),

        // Optional: set notes for the budget. These are free text and do not effect budget
        // delivery.
        // 'proposed_notes' => new StringValue(['value' => 'Received prepayment of $0.01']),

        // Optional: set PO number for record keeping. This value is at the user's
        // discretion, and has no effect on Google Billing & Payments.
        // 'proposed_purchase_order_number' => new StringValue(['value' => 'PO number 12345']),

        // Set the spending limit to 0.01, measured in the Google Ads account currency.
        'proposed_spending_limit_micros' => new Int64Value(['value' => 10000])
    ]);

    $accountBudgetProposalOperation = new AccountBudgetProposalOperation();
    $accountBudgetProposalOperation->setCreate($accountBudgetProposal);

    // Issues a mutate request to add the account budget proposal.
    $accountBudgetProposalServiceClient =
        $googleAdsClient->getAccountBudgetProposalServiceClient();
    $response = $accountBudgetProposalServiceClient->mutateAccountBudgetProposal(
        $customerId,
        $accountBudgetProposalOperation
    );

    printf(
        "Added an account budget proposal with resource name '%s'.%s",
        $response->getResult()->getResourceName(),
        PHP_EOL
    );
}

Python

def main(client, customer_id, billing_setup_id):
    account_budget_proposal_service = client.get_service(
        "AccountBudgetProposalService"
    )
    billing_setup_service = client.get_service(
        "BillingSetupService", version="v5"
    )

    account_budget_proposal_operation = client.get_type(
        "AccountBudgetProposalOperation"
    )
    proposal = account_budget_proposal_operation.create

    proposal.proposal_type = client.get_type(
        "AccountBudgetProposalTypeEnum"
    ).CREATE
    proposal.billing_setup.value = billing_setup_service.billing_setup_path(
        customer_id, billing_setup_id
    )
    proposal.proposed_name.value = "Account Budget Proposal (example)"

    # Specify the account budget starts immediately
    proposal.proposed_start_time_type = client.get_type(
        "TimeTypeEnum", version="v5"
    ).NOW
    # Alternatively you can specify a specific start time. Refer to the
    # AccountBudgetProposal resource documentation for allowed formats.
    #
    # proposal.proposed_start_date_time = '2020-01-02 03:04:05'

    # Specify that the budget runs forever
    proposal.proposed_end_time_type = client.get_type(
        "TimeTypeEnum", version="v5"
    ).FOREVER
    # Alternatively you can specify a specific end time. Allowed formats are as
    # above.
    #
    # proposal.proposed_end_date_time = '2021-01-02 03:04:05'

    # Optional: set notes for the budget. These are free text and do not effect
    # budget delivery.
    #
    # proposal.proposed_notes = client.wrapper
    #     .string('Received prepayment of $0.01')
    proposal.proposed_spending_limit_micros.value = 10000

    try:
        account_budget_proposal_response = account_budget_proposal_service.mutate_account_budget_proposal(
            customer_id, account_budget_proposal_operation
        )
    except google.ads.google_ads.errors.GoogleAdsException as ex:
        print(
            'Request with ID "%s" failed with status "%s" and includes the '
            "following errors:" % (ex.request_id, ex.error.code().name)
        )
        for error in ex.failure.errors:
            print('\tError with message "%s".' % error.message)
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print("\t\tOn field: %s" % field_path_element.field_name)
        sys.exit(1)

    print(
        'Created account budget proposal "%s".'
        % account_budget_proposal_response.result.resource_name
    )

Ruby

def add_account_budget_proposal(customer_id, billing_setup_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new


  operation = client.operation.create_resource.account_budget_proposal do |proposal|
    proposal.billing_setup = client.path.billing_setup(customer_id, billing_setup_id)
    proposal.proposal_type = :CREATE
    proposal.proposed_name = 'Account Budget (example)'

    # Specify the account budget starts immediately
    proposal.proposed_start_time_type = :NOW
    # Alternatively you can specify a specific start time. Refer to the
    # AccountBudgetProposal resource documentation for allowed formats.
    #
    # proposal.proposed_start_date_time = '2020-01-02 03:04:05'

    # Specify that the budget runs forever.
    proposal.proposed_end_time_type = :FOREVER
    # Alternatively you can specify a specific end time. Allowed formats are as
    # above.
    #
    # proposal.proposed_end_date_time = '2021-01-02 03:04:05'

    # Optional: set notes for the budget. These are free text and do not affect
    # budget delivery.
    #
    # proposal.proposed_notes = 'Received prepayment of $0.01'

    # Set the spending limit to 0.01, measured in the Google Ads account currency.
    proposal.proposed_spending_limit_micros = 10_000
  end

  account_budget_proposal_service = client.service.account_budget_proposal
  # Add budget proposal.
  response = account_budget_proposal_service.mutate_account_budget_proposal(
    customer_id: customer_id,
    operation: operation,
  )

  puts sprintf("Created budget proposal %s.",
      response.results.first.resource_name)
end

Perl

sub add_account_budget_proposal {
  my ($api_client, $customer_id, $billing_setup_id) = @_;

  # Create an account budget proposal.
  my $account_budget_proposal =
    Google::Ads::GoogleAds::V5::Resources::AccountBudgetProposal->new({
      billingSetup =>
        Google::Ads::GoogleAds::V5::Utils::ResourceNames::billing_setup(
        $customer_id, $billing_setup_id
        ),
      proposalType => CREATE,
      proposedName => "Account Budget (example)",
      # Specify that the account budget starts immediately.
      proposedStartTimeType => NOW,
      # Alternatively you can specify a specific start time. Refer to the
      # AccountBudgetProposal class for allowed formats.
      #
      # proposedStartDateTime => "2020-01-02 03:04:05",

      # Specify that the account budget runs forever.
      proposedEndDateTime => FOREVER,
      # Alternatively you can specify a specific end time. Allowed formats are as below.
      # proposedEndDateTime => "2021-02-03 04:05:06",

      # Optional: set notes for the budget. These are free text and do not effect budget
      # delivery.
      # proposedNotes => "Received prepayment of $0.01",

      # Optional: set PO number for record keeping. This value is at the user's
      # discretion, and has no effect on Google Billing & Payments.
      # proposedPurchaseOrderNumber => "PO number 12345",

      # Set the spending limit to 0.01, measured in the Google Ads account currency.
      proposedSpendingLimitMicros => 10000
    });

  # Create an account budget proposal operation.
  my $account_budget_proposal_operation =
    Google::Ads::GoogleAds::V5::Services::AccountBudgetProposalService::AccountBudgetProposalOperation
    ->new({
      create => $account_budget_proposal
    });

  # Add the account budget proposal.
  my $account_budget_proposal_response =
    $api_client->AccountBudgetProposalService()->mutate({
      customerId => $customer_id,
      operation  => $account_budget_proposal_operation
    });

  printf "Created account budget proposal '%s'.\n",
    $account_budget_proposal_response->{result}{resourceName};

  return 1;
}

In account budget proposal requests, proposed_start_date_time and proposed_end_date_time are always in the customer's account timezone; you cannot specify a timezone. The proposed spending limit is always measured in the account's currency; specify this using "micro" units, so $1.00 = 1,000,000 micros.

Optionally, you can include a Purchase Order number which will show next to these charges on the invoice. This does not have any effect on budget delivery.

Removing a pending account budget proposal

You can remove an entire pending budget proposal by sending an AccountBudgetProposalOperation Remove request with an account budget proposal resource name. However, note that budget proposals are usually applied within minutes.

Java
AccountBudgetProposalOperation operation = AccountBudgetProposalOperation.newBuilder()
  .setRemove(StringValue.of(ResourceNames.accountBudgetProposal(customerId, accountBudgetProposalId)))
  .build();

// Send request to Google Ads API (not shown).
C#
AccountBudgetProposalOperation operation = new AccountBudgetProposalOperation()
{
    Remove = ResourceNames.AccountBudgetProposal(customerId, accountBudgetProposalId)
};

// Send request to Google Ads API (not shown).
PHP
$accountBudgetProposalOperation = new AccountBudgetProposalOperation();
$accountBudgetProposalOperation->setRemove(ResourceNames::forAccountBudgetProposal($customerId, $accountBudgetProposalId));

// Send request to Google Ads API (not shown).
Python
account_budget_proposal_service = client.get_service('AccountBudgetProposalService')
account_budget_proposal_operation = client.get_type('AccountBudgetProposalOperation')
proposal = account_budget_proposal_operation.remove
proposal.resource_name = account_budget_proposal_service.account_budget_proposal_path(customer_id, account_budget_proposal_id):

# Send request to Google Ads API (not shown).
Ruby
operation = client.operation.remove_resource.account_budget_proposal(client.path.account_budget_proposal(customer_id, account_budget_proposal_id))

# Send request to Google Ads API (not shown).
Perl
my $account_budget_proposal_operation =
  Google::Ads::GoogleAds::V5::Services::AccountBudgetProposalService::AccountBudgetProposalOperation
    ->new({
      remove => Google::Ads::GoogleAds::V5::Utils::ResourceNames::billing_setup(
          $customer_id, $account_budget_proposal_id
        )
    });

# Send request to Google Ads API (not shown).

If you made a mistake with the original proposal, you can resubmit the proposal as an UPDATE operation. Refer to the Managing existing account budgets section below for more information.

Retrieving existing account budgets

The following GAQL query fetches all of the existing account budgets in an account:

SELECT
  account_budget.status,
  account_budget.billing_setup,
  account_budget.approved_spending_limit_micros,
  account_budget.approved_spending_limit_type,
  account_budget.proposed_spending_limit_micros,
  account_budget.proposed_spending_limit_type,
  account_budget.adjusted_spending_limit_micros,
  account_budget.adjusted_spending_limit_type,
  account_budget.approved_start_date_time,
  account_budget.proposed_start_date_time,
  account_budget.approved_end_date_time,
  account_budget.approved_end_time_type,
  account_budget.proposed_end_date_time,
  account_budget.proposed_end_time_type
FROM
  account_budget

Note that fields encapsulating the account budget's start time, end time, and spending limit have multiple variants with prefixes such as proposed and approved that allow for comparing the values that were initially proposed with those that were approved. The spending limit has additional fields with the adjusted prefix to indicate the current spending limit in effect after any adjustments were applied to the approved amount.

An account budget's approved spending limit can be adjusted over time to reflect various credits for things like budget overdelivery, invalid click activity, and promotional coupons. More information about account budgets and account credits and adjustments can be found in the Google Ads Help Center.

Any new account budgets pending approval, along with any existing account budgets that have updates pending, will also contain an pending_proposal field that can be selected. It will contain the resource ID of the associated AccountBudgetProposal object.

Code examples

The Billing folder of each client library contains a code example that shows a full request:

Managing existing account budgets

After creating an account budget for a customer, you can use the AccountBudgetProposalService to manage the budget parameters. The most common management operations are to update the spending_limit and end_date_time fields. For a complete list of the mutable fields, refer to the AccountBudgetProposal document.

You have the option of updating an existing account budget or creating a entirely new budget, both are shown here.

Update an existing account budget

You can update the existing account budget fields by sending AccountBudgetProposal objects with AccountBudgetProposalType set to UPDATE. Note that you must also indicate the fields being updated in the operation's UpdateMask argument.

The following snippet demonstrates how to update the proposed spending limit for an existing account budget.

Java
AccountBudgetProposal proposal = AccountBudgetProposal.newBuilder()
  .setProposalType(AccountBudgetProposalType.UPDATE)
  .setAccountBudget(accountBudget.getResourceName())
  .setProposedSpendingLimitMicros(Int64Value.of(
    accountBudget.getProposedSpendingLimitMicros().getValue() + increaseAmount))
  .build();

AccountBudgetProposalOperation operation = AccountBudgetProposalOperation.newBuilder()
  .setCreate(proposal)
  .setUpdateMask(
      FieldMask.newBuilder().addAllPaths(Arrays.asList("proposed_spending_limit")).build())
  .build();

// Send request to Google Ads API (not shown).
C#
AccountBudgetProposal proposal = new AccountBudgetProposal()
{
  ProposalType = AccountBudgetProposalType.Update,
  AccountBudget = accountBudget.ResourceName,
  ProposedSpendingLimitMicros = accountBudget.ProposedSpendingLimitMicros + increaseAmount
};

AccountBudgetProposalOperation operation = new AccountBudgetProposalOperation()
{
  Create = proposal,
  UpdateMask = new FieldMask()
  {
    Paths = { "proposed_spending_limit" }
  }
};

// Send request to Google Ads API (not shown).
PHP
$accountBudgetProposal = new AccountBudgetProposal([
  'proposal_type' => AccountBudgetProposalType::UPDATE,
  'account_budget' => $accountBudget->getResourceName(),
  'proposed_spending_limit_micros' => new Int64Value(['value' =>
    $accountBudget->getProposedSpendingLimitMicrosUnwrapped() + $increaseAmount])

$accountBudgetProposalOperation = new AccountBudgetProposalOperation();
$accountBudgetProposalOperation->setCreate($accountBudgetProposal);
$accountBudgetProposalOperation->setUpdateMask(
  FieldMasks::allSetFieldsOf($accountBudgetProposal)
);

// Send request to Google Ads API (not shown).
Python
account_budget_proposal_operation = client.get_type('AccountBudgetProposalOperation')

proposal = account_budget_proposal_operation.create
proposal.proposal_type = client.get_type('AccountBudgetProposalTypeEnum').UPDATE
proposal.account_budget = account_budget
proposal.proposed_spending_limit_micros.value = account_budget.proposed_spending_limit_micros.value + increase_amount

field_mask = protobuf_helpers.field_mask(None, proposal)
account_budget_proposal_operation.update_mask.CopyFrom(field_mask)

# Send request to Google Ads API (not shown).
Ruby
proposal = client.resource.account_budget_proposal
proposal.proposal_type = :UPDATE

mask = client.field_mask.with proposal do
  proposal.account_budget = account_budget.resource_name
  proposal.proposed_spending_limit_micros = account_budget.proposed_spending_limit_micros.value + increase_amount

operation = client.operation.create_resource.account_budget_proposal do |op|
  op.create = proposal
  op.update_mask = mask

# Send request to Google Ads API (not shown).
Perl
my $account_budget_proposal =
  Google::Ads::GoogleAds::V5::Resources::AccountBudgetProposal->new({
    proposalType => UPDATE,
    accountBudget => $account_budget->{resourceName},
    proposedSpendingLimitMicros => $account_budget->{proposedSpendingLimitMicros} + $increaseAmount});

my $account_budget_proposal_operation =
  Google::Ads::GoogleAds::V5::Services::AccountBudgetProposalService::AccountBudgetProposalOperation
    ->new({
      create => $account_budget_proposal,
      updateMask => all_set_fields_of($account_budget_proposal)});

# Send request to Google Ads API (not shown).

Account budget chaining

As an alternative to updating the existing budget, Google Ads allows you to chain multiple account budgets to run in succession. In the following example, a customer has different spending limits each month.

This can be achieved by creating three AccountBudgetProposal objects and sending them to the AccountBudgetProposalService.

The snippet below demonstrates the creation of such a chain using an existing billing setup.

Java
AccountBudgetProposal proposalMay = AccountBudgetProposal.newBuilder()
  .setBillingSetup(StringValue.of(ResourceNames.billingSetup(customerId, billingSetupId)))
  .setProposalType(AccountBudgetProposalType.CREATE)
  .setProposedName(StringValue.of("May budget"))
  .setProposedStartDateTime(StringValue.of("2018-05-01"))
  .setProposedEndDateTime(StringValue.of("2018-06-01"))
  .setProposedSpendingLimitMicros(Int64Value.of(1_000_000_000L))
  .build();

AccountBudgetProposal proposalJune = AccountBudgetProposal.newBuilder()
  .setBillingSetup(StringValue.of(ResourceNames.billingSetup(customerId, billingSetupId)))
  .setProposalType(AccountBudgetProposalType.CREATE)
  .setProposedName(StringValue.of("June budget"))
  .setProposedStartDateTime(StringValue.of("2018-06-01"))
  .setProposedEndDateTime(StringValue.of("2018-07-01"))
  .setProposedSpendingLimitMicros(Int64Value.of(5_000_000_000L))
  .build();

AccountBudgetProposal proposalJuly = AccountBudgetProposal.newBuilder()
  .setBillingSetup(StringValue.of(ResourceNames.billingSetup(customerId, billingSetupId)))
  .setProposalType(AccountBudgetProposalType.CREATE)
  .setProposedName(StringValue.of("July budget"))
  .setProposedStartDateTime(StringValue.of("2018-07-01"))
  .setProposedEndDateTime(StringValue.of("2018-08-01"))
  .setProposedSpendingLimitMicros(Int64Value.of(1_000_000_000L))
  .build();

// Send request to Google Ads API (not shown).
C#
AccountBudgetProposal proposalMay = new AccountBudgetProposal()
{
  BillingSetup = ResourceNames.BillingSetup(customerId, billingSetupId),
  ProposalType = AccountBudgetProposalType.Create,
  ProposedName = "May budget",
  ProposedStartDateTime = "2018-05-01",
  ProposedEndDateTime = "2018-06-01",
  ProposedSpendingLimitMicros = 1_000_000_000
}

AccountBudgetProposal proposalJune = new AccountBudgetProposal()
{
  BillingSetup = ResourceNames.BillingSetup(customerId, billingSetupId),
  ProposalType = AccountBudgetProposalType.Create,
  ProposedName = "June budget",
  ProposedStartDateTime = "2018-06-01",
  ProposedEndDateTime = "2018-07-01",
  ProposedSpendingLimitMicros = 5_000_000_000
}

AccountBudgetProposal proposalJuly = new AccountBudgetProposal()
{
  BillingSetup = ResourceNames.BillingSetup(customerId, billingSetupId),
  ProposalType = AccountBudgetProposalType.Create,
  ProposedName = "July budget",
  ProposedStartDateTime = "2018-07-01",
  ProposedEndDateTime = "2018-08-01",
  ProposedSpendingLimitMicros = 1_000_000_000
}

// Send request to Google Ads API (not shown).
PHP
$proposalMay = new AccountBudgetProposal([
  'billing_setup' => new StringValue(
      ['value' => ResourceNames::forBillingSetup($customerId, $billingSetupId)]
  ),
  'proposal_type' => AccountBudgetProposalType::CREATE,
  'proposed_name' => new StringValue(['value' => 'May budget']),
  'proposed_start_date_time' => new StringValue(['value' => '2018-05-01']),
  'proposed_end_date_time' => new StringValue(['value' => '2018-06-01']),
  'proposed_spending_limit_micros' => new Int64Value(['value' => 1000000000])
]);

$proposalJune = new AccountBudgetProposal([
  'billing_setup' => new StringValue(
      ['value' => ResourceNames::forBillingSetup($customerId, $billingSetupId)]
  ),
  'proposal_type' => AccountBudgetProposalType::CREATE,
  'proposed_name' => new StringValue(['value' => 'June budget']),
  'proposed_start_date_time' => new StringValue(['value' => '2018-06-01']),
  'proposed_end_date_time' => new StringValue(['value' => '2018-07-01']),
  'proposed_spending_limit_micros' => new Int64Value(['value' => 5000000000])
]);

$proposalJuly = new AccountBudgetProposal([
  'billing_setup' => new StringValue(
      ['value' => ResourceNames::forBillingSetup($customerId, $billingSetupId)]
  ),
  'proposal_type' => AccountBudgetProposalType::CREATE,
  'proposed_name' => new StringValue(['value' => 'July budget']),
  'proposed_start_date_time' => new StringValue(['value' => '2018-07-01']),
  'proposed_end_date_time' => new StringValue(['value' => '2018-08-01']),
  'proposed_spending_limit_micros' => new Int64Value(['value' => 1000000000])
]);

// Send request to Google Ads API (not shown).
Python
may_account_budget_proposal_operation = client.get_type('AccountBudgetProposalOperation')
proposalMay = may_account_budget_proposal_operation.create
proposalMay.proposal_type = client.get_type('AccountBudgetProposalTypeEnum').CREATE
proposalMay.billing_setup.value = billing_setup_service.billing_setup_path(customer_id, billing_setup_id)
proposalMay.proposed_name.value = 'May budget'
proposalMay.proposed_start_date_time = '2018-05-01'
proposalMay.proposed_end_date_time = '2018-06-01'
proposalMay.proposed_spending_limit_micros.value = 1000000000

june_account_budget_proposal_operation = client.get_type('AccountBudgetProposalOperation')
proposalJune = may_account_budget_proposal_operation.create
proposalJune.proposal_type = client.get_type('AccountBudgetProposalTypeEnum').CREATE
proposalJune.billing_setup.value = billing_setup_service.billing_setup_path(customer_id, billing_setup_id)
proposalJune.proposed_name.value = 'June budget'
proposalJune.proposed_start_date_time = '2018-06-01'
proposalJune.proposed_end_date_time = '2018-07-01'
proposalJune.proposed_spending_limit_micros.value = 5000000000

july_account_budget_proposal_operation = client.get_type('AccountBudgetProposalOperation')
proposalJuly = may_account_budget_proposal_operation.create
proposalJuly.proposal_type = client.get_type('AccountBudgetProposalTypeEnum').CREATE
proposalJuly.billing_setup.value = billing_setup_service.billing_setup_path(customer_id, billing_setup_id)
proposalJuly.proposed_name.value = 'July budget'
proposalJuly.proposed_start_date_time = '2018-07-01'
proposalJuly.proposed_end_date_time = '2018-08-01'
proposalJuly.proposed_spending_limit_micros.value = 1000000000

# Send request to Google Ads API (not shown).
Ruby
proposal_may = client.operation.create_resource.account_budget_proposal do |proposal|
  proposal.billing_setup = client.path.billing_setup(customer_id, billing_setup_id)
  proposal.proposal_type = :CREATE
  proposal.proposed_name = 'May budget'
  proposal.proposed_start_date_time = '2018-05-01'
  proposal.proposed_end_date_time = '2018-06-01'
  proposal.proposed_spending_limit_micros = 1_000_000_000
end

proposal_june = client.operation.create_resource.account_budget_proposal do |proposal|
  proposal.billing_setup = client.path.billing_setup(customer_id, billing_setup_id)
  proposal.proposal_type = :CREATE
  proposal.proposed_name = 'June budget'
  proposal.proposed_start_date_time = '2018-06-01'
  proposal.proposed_end_date_time = '2018-07-01'
  proposal.proposed_spending_limit_micros = 5_000_000_000
end

proposal_july = client.operation.create_resource.account_budget_proposal do |proposal|
  proposal.billing_setup = client.path.billing_setup(customer_id, billing_setup_id)
  proposal.proposal_type = :CREATE
  proposal.proposed_name = 'July budget'
  proposal.proposed_start_date_time = '2018-07-01'
  proposal.proposed_end_date_time = '2018-08-01'
  proposal.proposed_spending_limit_micros = 1_000_000_000
end

# Send request to Google Ads API (not shown).
Perl
my $may_proposal =
  Google::Ads::GoogleAds::V5::Resources::AccountBudgetProposal->new({
    billingSetup =>
      Google::Ads::GoogleAds::V5::Utils::ResourceNames::billing_setup(
      $customer_id, $billing_setup_id
      ),
    proposalType => CREATE,
    proposedName => "May budget",
    proposedStartDateTime => "2018-05-01",
    proposedEndDateTime => "2018-06-01",
    proposedSpendingLimitMicros => 1000000000
  });

my $june_proposal =
  Google::Ads::GoogleAds::V5::Resources::AccountBudgetProposal->new({
    billingSetup =>
      Google::Ads::GoogleAds::V5::Utils::ResourceNames::billing_setup(
      $customer_id, $billing_setup_id
      ),
    proposalType => CREATE,
    proposedName => "June budget",
    proposedStartDateTime => "2018-06-01",
    proposedEndDateTime => "2018-07-01",
    proposedSpendingLimitMicros => 5000000000
  });

my $july_proposal =
  Google::Ads::GoogleAds::V5::Resources::AccountBudgetProposal->new({
    billingSetup =>
      Google::Ads::GoogleAds::V5::Utils::ResourceNames::billing_setup(
      $customer_id, $billing_setup_id
      ),
    proposalType => CREATE,
    proposedName => "July budget",
    proposedStartDateTime => "2018-07-01",
    proposedEndDateTime => "2018-08-01",
    proposedSpendingLimitMicros => 1000000000
  });

# Send request to Google Ads API (not shown).

Note the use of AccountBudgetProposalType.CREATE on each proposal. This will create three distinct budgets, rather than updating the same budget three times.

Terminating account budgets

Account budgets can be ended while active, and removed entirely prior to starting or while pending approval.

Ending the active account budget

The active account budget cannot be removed. However, you can set the end time to the current time. The simplest way to achieve this is to send a proposal with AccountBudgetProposalType.END.

The following snippet demonstrates how to end an existing account budget.

Java
AccountBudgetProposal.newBuilder()
  .setProposalType(AccountBudgetProposalType.END)
  .setAccountBudget(accountBudget.getResourceName())
  .build();

// Send request to Google Ads API (not shown).
C#
AccountBudgetProposal proposal = new AccountBudgetProposal()
{
  ProposalType = AccountBudgetProposalType.End,
  AccountBudget = accountBudget.ResourceName,
  ProposedSpendingLimitMicros = accountBudget.ProposedSpendingLimitMicros + increaseAmount
};

// Send request to Google Ads API (not shown).
PHP
$accountBudgetProposal = new AccountBudgetProposal([
  'proposal_type' => AccountBudgetProposalType::END,
  'account_budget' => $accountBudget->getResourceName(),
  'proposed_spending_limit_micros' => new Int64Value(['value' =>
    $accountBudget->getProposedSpendingLimitMicrosUnwrapped() + $increaseAmount])

// Send request to Google Ads API (not shown).
Python
account_budget_proposal_operation = client.get_type('AccountBudgetProposalOperation')
proposal = account_budget_proposal_operation.create
proposal.proposal_type = client.get_type('AccountBudgetProposalTypeEnum').END
proposal.account_budget = account_budget

# Send request to Google Ads API (not shown).
Ruby
proposal = client.resource.account_budget_proposal
proposal.proposal_type = :END
proposal.account_budget = account_budget.resource_name

# Send request to Google Ads API (not shown).
Perl
my $account_budget_proposal =
  Google::Ads::GoogleAds::V5::Resources::AccountBudgetProposal->new({
    proposalType => END,
    accountBudget => $account_budget->{resourceName});

# Send request to Google Ads API (not shown).

This is equivalent to setting the updating an account budget by setting the end date time to TimeType.NOW.

Removing an approved account budget before its start time

If you proposed an account budget to start in future, you can remove this entirely prior to the start time by sending a AccountBudgetProposalType.REMOVE proposal type.

The following snippet demonstrates the removal of an existing future account budget.

Java
AccountBudgetProposal.newBuilder()
  .setProposalType(AccountBudgetProposalType.REMOVE)
  .setAccountBudget(accountBudget.getResourceName())
  .build();

// Send request to Google Ads API (not shown).
C#
AccountBudgetProposal proposal = new AccountBudgetProposal()
{
  ProposalType = AccountBudgetProposalType.Remove,
  AccountBudget = accountBudget.ResourceName,
  ProposedSpendingLimitMicros = accountBudget.ProposedSpendingLimitMicros + increaseAmount
};

// Send request to Google Ads API (not shown).
PHP
$accountBudgetProposal = new AccountBudgetProposal([
  'proposal_type' => AccountBudgetProposalType::REMOVE,
  'account_budget' => $accountBudget->getResourceName(),
  'proposed_spending_limit_micros' => new Int64Value(['value' =>
    $accountBudget->getProposedSpendingLimitMicrosUnwrapped() + $increaseAmount])

// Send request to Google Ads API (not shown).
Python
account_budget_proposal_operation = client.get_type('AccountBudgetProposalOperation')
proposal = account_budget_proposal_operation.create
proposal.proposal_type = client.get_type('AccountBudgetProposalTypeEnum').REMOVE
proposal.account_budget = account_budget

# Send request to Google Ads API (not shown).
Ruby
proposal = client.resource.account_budget_proposal
proposal.proposal_type = :REMOVE
proposal.account_budget = account_budget.resource_name

# Send request to Google Ads API (not shown).
Perl
my $account_budget_proposal =
  Google::Ads::GoogleAds::V5::Resources::AccountBudgetProposal->new({
    proposalType => REMOVE,
    accountBudget => $account_budget->{resourceName});

# Send request to Google Ads API (not shown).