Google Ads

Budget Order Service  |  AdWords API  |  Google Developers

Mutate requests to this service are available only to whitelisted Google Ads
manager accounts that have also been setup for monthly invoicing. Get
requests are open to everyone. Contact your Google representative if you
need to be whitelisted.

The
BudgetOrderService
(BOS) enables approved manager accounts to programmatically create account-level
budgets for the client accounts they manage on
consolidated billing. This lets
client accounts charge spend to a manager’s billing account.

Using the API, managers can create and manage
BudgetOrder
objects that define account-level budgets for client accounts. Each BudgetOrder is in
turn associated with a
BillingAccount,
which represents an invoice setup onto which a client’s charges are billed. A
manager can add BudgetOrder objects from multiple client accounts onto the same
BillingAccount to group their charges on a single invoice setup.

Terminology

Here are the key terms to keep in mind when configuring billing using BOS.

Client account
A normal Google Ads account that has campaigns and ad groups, serves ads, etc.
You may also see this referred to as a “customer” or “customer account”, but
this guide uses the term “client account” to help avoid confusion with the
term “billing customer”.
Billing account
The common information needed to create related invoices over time (also
referred to as an invoice “setup”). This includes, for example, the
currency of the invoices, the entity that the invoices should be sent to and
paid by, and a display name that can be printed on the invoices for easier
reference.

  • Billing accounts can be edited in the Google Ads UI, but cannot be
    created or edited via the AdWords API.
  • Note that the word “account” in “billing account” does not
    mean it is a special sort of client account used for billing. It simply
    refers to it being an object that holds the common information used
    for related invoices.
  • They are represented as a BillingAccount in BOS.
  • They can be referenced using the id field in a BillingAccount
    and the billingAccountId field in a
    BudgetOrder.
Budget order
An authorization for a particular client account to spend up to a certain
amount of money over a certain period of time, accruing that spend onto a
particular billing account.

  • For example, a budget order could say “Google Ads account 123-456-7890 is
    authorized to spend up to $100 in August, and that spend should be
    invoiced using the information in billing account 1212-1234-3434-3434.”
  • The same billing account can be used for different budget orders across
    client accounts. In other words, you can have different client accounts
    accrue their spend onto the same invoice, i.e., a consolidated invoice,
    by setting up their budget orders to point to the same billing account.
  • Represented as a BudgetOrder in BOS.
Billing customer
A legal entity that can actually receive and pay
an invoice. This is analogous to a Legal Customer on our legacy
billing system.

  • A billing customer can be created by contacting your customer service
    representative. After at least one billing customer is created and
    associated with your manager account, you can begin managing
    BudgetOrders programmatically.
  • Can be referenced using the primaryBillingId
    field on either a BillingAccount or a
    BudgetOrder.

Manager-Client relationships

Since BOS is designed for use specifically by manager accounts, it’s important
to understand the distinction between the manager sending a request and the
client account on which it’s acting.

  • manager – The manager account belonging to the authenticated API user.
  • client – The client account whose clientCustomerId is set in a
    request’s header field.

Billing customers are associated with specific manager accounts by contacting
your customer service representative. A BudgetOrder can then be created for a
client account so long as the manager making the API request:

  • Has access to the manager account that owns a particular billing customer.
  • Has access to the client account that should use the billing customer.
  • Is whitelisted for BudgetOrderService.

For example, by authenticating as manager account A above, you’re able to
add client 123-456-7890 to BillingAccounts associated with any of the
manager accounts in the tree, since the top-level manager account can access
both manager account B, manager account C, and the client account.

For mutate calls, you must authenticate with the account that is whitelisted for
the API. When getting whitelisted, you should choose to whitelist the
highest-level manager account available to ensure you have access to the manager
and client accounts you want to manage.

Listing available BillingAccounts

You can retrieve a list of
BillingAccounts
accessible by the authenticated manager using the BudgetOrderService’s
getBillingAccounts()
operation. Each BillingAccount object represents an invoice setup linked to a
manager account of the target client account’s manager(s). These are the
BillingAccounts that can be used by BudgetOrders of the target client
account.

For example, to get a list of BillingAccounts that client 123-456-7890 could
use, you would call getBillingAccounts() by authenticating as one of its
parent manager accounts. Using Java with our client libraries, you could use the
following:

session.setClientCustomerId("123-456-7890");
BudgetOrderServiceInterface bos = services.get(session, BudgetOrderServiceInterface.class);
BillingAccount[] accts = bos.getBillingAccounts();

Whichever manager you authenticate as can influence which BillingAccounts are
returned by a call to getBillingAccounts(). The operation will return
BillingAccounts associated with all managers of a particular client. However,
it will only traverse as far up the hierarchy as the authenticated manager.

For example, if both manager accounts A and C above have active
BillingAccounts, calling getBillingAccounts() as A for
clientCustomerId 123-456-7890 will return both sets. However, if the call
was made as C, only the BillingAccounts for C would be visible.

Each BillingAccount object has both an ID and a primaryBillingId. The ID
uniquely identifies the BillingAccount and is referred to as the
billingAccountId in other objects. The primaryBillingId identifies the
billing customer who pays for the charges on the invoice.

The primaryBillingId can also be found in the Google Ads UI,
labeled as “Who pays”, under Billing > Billing settings.

Creating a new BudgetOrder

To add a client to one of the accessible BillingAccounts, create a
BudgetOrder to establish their account-level budget. This
includes details like the start time, end time, and spending limit for the
client.

After retrieving the available BillingAccounts above, you could create a
new account-level budget for the month of August, with a spending limit of
$100, that uses the first BillingAccount returned in the previous example:

BillingAccount acct = accts[0];
BudgetOrder order = new BudgetOrder();
order.setBillingAccountId(acct.getId());
order.setPrimaryBillingId(acct.getPrimaryBillingId());
order.setStartDateTime("20140801 000000 America/New_York");
order.setEndDateTime("20140831 235959 America/New_York");
Money amt = new Money();
amt.setMicroAmount(100000000L);  // $100 in micros
order.setSpendingLimit(amt);

BudgetOrderOperation op = new BudgetOrderOperation();
op.setOperator(Operator.ADD);
op.setOperand(order);
BudgetOrderReturnValue response = bos.mutate(new BudgetOrderOperation[] {op});

The
BudgetOrderReturnValue
returned from the mutate operation will contain the ID of the new BudgetOrder.
The BudgetOrder will contain a
lastRequest
field that includes information about the status of the request. Newly submitted
BudgetOrders have a status of UNDER_REVIEW until they are approved and
become active.

New BudgetOrders can take some time (typically less than an hour) to become
active, so it’s best to create them well in advance of their intended
startDateTime. Although only one BudgetOrder can be active for a client at a
time, future budgets can be created and queued at any time. For example, you
could have created BudgetOrders for September and October for
clientCustomerId 123-456-7890 immediately following the August BudgetOrder
created above.

There can only be one BudgetOrder in
effect at any moment in time, so make sure the startDateTime and
endDateTime fields of a new BudgetOrder do not fall within the duration of
any other existing BudgetOrder (active or pending in the future). Note that
startDateTime and endDateTime define a closed interval: The BudgetOrder‘s
duration includes the startDateTime and endDateTime. In the above example,
the endDateTime is 20140831 235959 America/New_York so that it does not
overlap with a future potential BudgetOrder for September with a
startDateTime of 20140901 000000 America/New_York. If you attempt to create
a BudgetOrder whose duration overlaps with another BudgetOrder for the same
account, you’ll receive an INVALID_BUDGET_DATE_RANGE error.

As illustrated in the above example, the
startDateTime
and
endDateTime
are specified down to the second. For most use cases the time
zone should be the
dateTimeZone
of the customer.

Editing a BudgetOrder

You can update an existing BudgetOrder by referencing its ID in a mutate
operation. It’s always preferable to update an existing BudgetOrder instead of
creating a new one, since there is a limit on the number of BudgetOrders that
can use a given BillingAccount.

You can increase the spending limit and duration of the account-level budget
created in the previous section by updating the existing BudgetOrder object
with new spendingLimit and endDateTime values:

Long existingId = response.getValue()[0].getId();
BudgetOrder existingOrder = new BudgetOrder();
existingOrder.setId(existingId);
Money newAmt = new Money();
newAmt.setMicroAmount(200000000L);
existingOrder.setSpendingLimit(newAmt);
existingOrder.setEndDateTime("20140930 235959 America/New_York");

BudgetOrderOperation op = new BudgetOrderOperation();
op.setOperator(Operator.SET);
op.setOperand(existingOrder);
bos.mutate(new BudgetOrderOperation[] {op});

It’s also possible to decrease the spending limit of a BudgetOrder, however,
you cannot set it lower than the amount that’s already been spent by the order.

Spending limits and adjustments

When mutating the spending limit of a BudgetOrder, it’s important to keep
adjustments
in mind as well. Adjustments are credits applied to the budget
order which allow you to spend beyond your normal spending limit, but at no
cost.

On mutate() requests, the spending limit does not take any adjustments into
account. Whatever value you send is how much you are willing to spend before
adjustments. However, on get() requests, spendingLimit includes any
adjustments made to your BudgetOrder. If you’re trying to set your spending
limit relative to a prior submitted spending limit, make sure to take
adjustments into account. You can do this by subtracting totalAdjustments
from the retrieved spendingLimit to find the base spending limit you set
previously.

Removing a BudgetOrder

A BudgetOrder can end either by reaching the end of its spend period or by
being actively cancelled. Once a BudgetOrder has ended, a new one will need to
be created to re-enable spend for a client account.

You can cancel an active BudgetOrder by sending a request to REMOVE it via
the API. This will effectively set its endDateTime to the current time,
thereby ending the budget period and preventing further spend.

BudgetOrder o = new BudgetOrder();
o.setId(budgetOrderId);
BudgetOrderOperation op = new BudgetOrderOperation();
op.setOperator(Operator.REMOVE);
op.setOperand(o);
bos.mutate(new BudgetOrderOperation[] {op});

Changing the billing customer

You can change the underlying billing customer that pays for a client account’s
spend by creating a BudgetOrder that points to one of the new billing customer’s
BillingAccounts. However, only one such Change of Bill-To (CBT) operation can be
pending for any given client account.

For example, to change who pays for client 123-456-7890 after the August
BudgetOrder expires, you could add a new BudgetOrder for September that uses a
BillingAccount tied to a new billing customer; however, all subsequent
BudgetOrders must then use that new billing customer since only one CBT
operation can be scheduled for the client account.

Limitations

Description Value Error Notes
BudgetOrder objects per BillingAccount 75,000 BudgetOrderError.GENERIC_BILLING_ERROR,
trigger: TOO_MANY_ORDER_LINES_NEW_BILLING_ACCOUNT_REQUIRED

There’s a maximum of 75,000 BudgetOrders per BillingAccount.

If you’ve reached that limit, create a new invoice setup in the Google Ads UI
and add future BudgetOrders to the new BillingAccount.

Operations per mutate request 1 BudgetOrderError.MORE_THAN_ONE_OPERATIONS Multiple operations need be sent in separate requests.
Requests per second 1 RateExceededError.RATE_EXCEEDED

The rate limit for this service is 1 qps.

Make sure requests are throttled to no more than 1 per second and avoid
sending concurrent requests.

Common errors

Error Notes and Workarounds
BudgetOrderError.INVALID_BUDGET_DATE_RANGE, trigger: Overlapping budget
found

Cannot create overlapping BudgetOrder objects.

Change the startDateTime or endDateTime for the BudgetOrder so it doesn’t
overlap with another active or pending budget.

If you attempted to create a new budget order via the Google Ads UI, it’s
possible this process did not complete and is holding a pending budget order
open. Either finish creating the order in the UI or contact the AdWords API
support team for assistance.

BudgetOrderError.INVALID_BUDGET_ALREADY_SPENT

Cannot set spending limit below what has already been spent in a given
period.

Set the spendingLimit for the BudgetOrder to a value greater than what has already
been spent between the startDateTime and endDateTime for the BudgetOrder.

BudgetOrderError.CUSTOMER_NOT_WHITELISTED_FOR_NEW_BILLING

The manager account is not enabled for consolidated billing.

Contact your Google representative to enable consolidated billing for
your account.

NotWhitelistedError.CUSTOMER_NOT_WHITELISTED_FOR_API

The manager account is not whitelisted to use the BudgetOrderService API.

Contact your Google representative for access to the API service.

Leave a Reply

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

Back to top button
Close