Budget Order Service
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
BudgetOrder
BillingAccount
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
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.
Note: The authenticated user must be whitelisted for BudgetOrderService. Otherwise, your requests will fail with a NotWhitelistedError.
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
BillingAccount
s 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 microsorder.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
BudgetOrder
will contain a lastRequest field that includes information about the status of the request. Newly submitted
BudgetOrder
s 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
BudgetOrder
s 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
endDateTime
define a closed interval: The
BudgetOrder
's duration includes the
startDateTime
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
BudgetOrder
s 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
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.
Note: Budget adjustments may not be applied to
BudgetOrder
items immediately after the budget's creation. It is necessary to re-read the
spendingLimit
totalAdjustments
when calculating updated budget for delivery management purposes as they may have changed.
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
Warning: Wait at least 12 hours between budget order changes to the same account. Making calls before 12 hours have elapsed may result in unrecoverable failures which can only be resolved by your Google Ads account representative.
| Description | Value | Error | Notes |
| 75,000 | | There's a maximum of 75,000 |
| Operations per mutate request | 1 | | Multiple operations need be sent in separate requests. |
| Requests per second | | 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
| Notes and Workarounds | |
| Cannot create overlapping objects. Change the 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. |
| Cannot set spending limit below what has already been spent in a given period. Set the |
| The manager account is not enabled for consolidated billing. Contact your Google representative to enable consolidated billing for your account. |
| The manager account is not whitelisted to use the BudgetOrderService API. Contact your Google representative for access to the API service. |