google ads api —— budget2

https://developers.google.com/google-ads/api/docs/billing/account-budgets

 

Billing

The Google Ads API lets you programmatically manage end-to-end billing workflows, from initial billing setup and account-level budget management, to customer invoice reconciliation.

Each of the following entities encapsulates a distinct functional portion of the billing lifecycle.

Billing setup

A billing setup is an association between a Payments account and a specific Google Ads account. It effectively determines who pays for an advertiser's account.

Use BillingSetup resources to get and manage account-wide billing configuration.

Account budget

An account budget defines account-level budget properties, such as start time, end time, and spending limit. All changes to account budgets are done by submitting separate account budget proposals, which, after being reviewed and approved, become account budgets.

Use AccountBudgetProposal resources to create new AccountBudgets or update existing ones.

Invoice

An invoice is issued monthly when enabled by the advertiser. Invoices contain details such as adjustments, regulatory costs, taxes and account budgets, and can be downloaded as PDF files. Google Ads managers typically use them to automatically reconcile their own customer invoices.

Retrieve Invoice resources for invoice data.

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.

Key Point: AccountBudgetProposal objects are reviewed by Google prior to being applied. Reviews are typically completed in less than one hour, however you should ensure that budgets are approved well in advance of their requested start time.

The sections below describe the behavior of each proposal type.

Creating an account budget proposal

Creating a new account budget lets you 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.

JavaC#PHPPythonRubyPerl

 

public void Run(GoogleAdsClient client, long customerId, long billingSetupId)
{
    // Get the AccountBudgetProposalServiceClient.
    AccountBudgetProposalServiceClient proposalService =
        client.GetService(Services.V8.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;
    }
}

Note: Only one active account budget is allowed per customer. Creating a new account budget will cause any existing account budget to have its end date updated to coincide with the new budget's start date.

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.

JavaC#PHPPythonRubyPerl

 

AccountBudgetProposalOperation operation = new AccountBudgetProposalOperation()
{
    Remove = ResourceNames.AccountBudgetProposal(customerId, accountBudgetProposalId)
};

// 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:

JavaC#PHPPythonRubyPerl

Get account budgets

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.

JavaC#PHPPythonRubyPerl

 

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).

Account budget chaining

As an alternative to updating the existing budget, Google Ads lets you 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.

JavaC#PHPPythonRubyPerl

 

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).

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.

JavaC#PHPPythonRubyPerl

 

AccountBudgetProposal proposal = new AccountBudgetProposal()
{
  ProposalType = AccountBudgetProposalType.End,
  AccountBudget = accountBudget.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.

JavaC#PHPPythonRubyPerl

 

AccountBudgetProposal proposal = new AccountBudgetProposal()
{
  ProposalType = AccountBudgetProposalType.Remove,
  AccountBudget = accountBudget.ResourceName
};

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