https://developers.google.com/adwords/api/docs/guides/budget-order

 

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

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

Note: Budget adjustments may not be applied to BudgetOrder items immediately after the budget's creation. It is necessary to re-read the spendingLimit and 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
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.