予算オーダー サービス

このサービスは AdWords クライアント センター(MCC)アカウントでご利用いただけますが、毎月の請求書発行を利用し、ホワイトリストにも入っていることが条件となります。MCC アカウントでこのサービスを利用する方法については、Google の営業担当者にお問い合わせください。

承認済みの MCC アカウントで BudgetOrderService(BOS)を使用すると、統合請求で管理しているクライアント アカウントを対象に、アカウント単位の予算をプログラムで作成できます。これにより、クライアント アカウントで発生した費用の請求を MCC アカウントの請求先アカウントに回すことができます。

クライアント アカウントのアカウント単位の予算を定義する BudgetOrder オブジェクトは API を使って作成、管理できます。各 BudgetOrder はクライアントの費用が記載される請求書の設定を表す BillingAccount に関連付けられます。MCC アカウントでは複数のクライアント アカウントの BudgetOrder オブジェクトを同じ BillingAccount に追加し、請求内容を 1 つの請求書にまとめることができます。

用語

BOS を使って請求に関する設定を行う際には、次の用語の意味にご注意ください。

クライアント アカウント
キャンペーンや広告グループを設定し、広告を配信する通常の AdWords アカウントのことです。「顧客」、「顧客アカウント」などと表記される場合もありますが、「請求先顧客」との混同を避けるため、このガイドでは「クライアント アカウント」を使用します。
請求先アカウント
同じ設定で請求書を作り続けるために必要な共通の情報です(「請求書の設定」と表記する場合もあります)。この情報には請求書の通貨、請求書の送付先で支払い義務を負う事業体、請求書に載せる表示名などが含まれます。
  • 請求先アカウントは AdWords 管理画面で編集できますが、AdWords API では作成も編集もできません。
  • なお、請求先アカウントは、「アカウント」と言っても請求用の特殊なクライアント アカウントを意味しているわけではありません。請求書の作成で使用する共通の情報を保持するオブジェクトを意味しています。
  • BOS では BillingAccount と表記します。
  • この情報は BillingAccountid フィールドや BudgetOrderbillingAccountId フィールドで参照できます。
予算オーダー
特定のクライアント アカウントが特定の期間に使える金額を定める設定です。その費用は特定の請求先アカウントを使って請求されます。
  • たとえば、「AdWords アカウント 123-456-7890 は 8 月は 100 ドルまで使用可能で、その費用は請求先アカウント 1212-1234-3434-3434 の情報を使って請求する」のような予算オーダーも考えられます。
  • クライアント アカウントの複数の予算オーダーで同じ請求先アカウントを使用することもできます。複数の予算オーダーで同じ請求先アカウントを指定すれば、複数のクライアント アカウントの費用を同じ請求書(統合請求書)に記載することが可能です。
  • BOS では BudgetOrder と表記します。
請求先顧客
実際に請求書を受け取り、支払いを行う法人のことです。従来の請求システムの「請求書払いのお客様」とほぼ同義です。
  • 請求先顧客を設定するにはカスタマー サービス担当者に連絡を取ります。少なくとも 1 つの請求先顧客が設定され、MCC アカウントに関連付けられると、「BudgetOrder」のプログラムによる管理を開始できます。
  • この情報は BillingAccountBudgetOrderprimaryBillingId フィールドを使用して参照できます。

MCC アカウントとクライアント アカウントの関係

BOS は MCC アカウント向けの仕様になっているため、リクエストを送信する MCC アカウントとその影響を受けるクライアント アカウントの違いを理解しておくことは重要です。

  • MCC アカウント - 認証済みの API ユーザーが使用するアカウントです。
  • クライアント アカウント - リクエストのヘッダー フィールドで clientCustomerId が設定されているアカウントです。

請求先顧客は、カスタマー サービス担当者への連絡によって特定の MCC アカウントに関連付けられます。クライアント アカウントでは、API リクエストを行う MCC アカウントが次の条件を満たしている場合に限り BudgetOrder が作成されます。

  • 特定の請求先顧客が設定されている MCC アカウントにアクセスできる。
  • その請求先顧客の設定を使用するクライアント アカウントにアクセスできる。
  • BudgetOrderService のホワイトリストに入っている。

たとえば上図の MCC アカウント A として認証を受ければ、図中のいずれかの MCC アカウントに関連付けられている BillingAccounts にクライアント アカウント 123-456-7890 を追加できます。最上位の MCC アカウントであれば、MCC アカウント BC とクライアント アカウントのすべてにアクセスできます。

管理対象の MCC アカウントやクライアント アカウントへのアクセス権を確保するには、最上位の MCC アカウントで認証を受ける必要があります。

アクセス可能な BillingAccount のリストを取得する

認証を受けた MCC アカウントからアクセスできる BillingAccounts のリストは BudgetOrderService の getBillingAccounts() オペレーションで取得できます。BillingAccount オブジェクトは、対象のクライアント アカウントを管理する MCC アカウントに関連付けられた請求書の設定を表します。それら BillingAccount は対象のクライアント アカウントの BudgetOrders で使用できるオブジェクトです。

たとえばクライアント アカウント 123-456-7890 から使用できる BillingAccounts のリストを取得するには、親 MCC アカウントの 1 つとして認証を受けて getBillingAccounts() を呼び出します。Java とクライアント ライブラリを使用した場合は、次のようなコードになります。

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

どの MCC アカウントで認証を受けるかにより、getBillingAccounts() の呼び出しからどの BillingAccounts が返されるかが決まります。このオペレーションは特定のクライアント アカウントのすべての MCC アカウントを対象に、関連付けられている BillingAccounts を返します。ただし、認証を受けた MCC アカウントまでしか階層を上ることができません。

たとえば上図の MCC アカウント AC には有効な BillingAccounts がありますが、clientCustomerId 123-456-7890 を対象に A として getBillingAccounts() を呼び出した場合は A と C の BillingAccount が返されます。ただし C として呼び出しを行った場合は、CBillingAccounts しか表示されません。

BillingAccount オブジェクトには ID フィールドと primaryBillingId フィールドがあります。IDBillingAccount を一意に識別するフィールドで、他のオブジェクトでは billingAccountId と表記されます。primaryBillingId は請求書の金額を支払う請求先顧客を示します。

primaryBillingId は AdWords 管理画面でも確認可能で、[料金] > [課金設定] を選択すると [請求先] という項目が表示されます。

新しい BudgetOrder を作成する

アクセス可能な BillingAccounts の 1 つにクライアント アカウントを追加するには、BudgetOrder を作成してアカウント単位の予算を設定します。これにはクライアント アカウントの開始時刻、終了時刻、費用の上限などの情報も含まれます。

利用可能な BillingAccounts を取得した後は、たとえば前の例で最初に返された BillingAccount を使用するアカウント単位の予算を新たに作成できます。この例は 8 月が対象で、費用の上限を 100 ドルとしています。

BillingAccount acct = accts[0];
BudgetOrder order = new BudgetOrder();
order.setBillingAccountId(acct.getId());
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});

mutate オペレーションで返された BudgetOrderReturnValue には、新しい BudgetOrder の ID が含まれています。BudgetOrder には、リクエストのステータス情報を含む lastRequest というフィールドがあります。新たに送信した BudgetOrder のステータスは、承認されて有効になるまで UNDER_REVIEW となります。

新しい BudgetOrders は有効になるまで少し時間がかかるため(通常は 1 時間以内)、startDateTime ぎりぎりではなく余裕を持って作成することをおすすめします。BudgetOrder はクライアント アカウントごと一度に 1 つしか有効にできませんが、将来的に使用する予算はいつでも作成してキューに入れることができます。たとえば 8 月の BudgetOrder に続いて、clientCustomerId 123-456-7890 の 9 月と 10 月の BudgetOrder を作成することも可能です。

BudgetOrder は一度に 1 つしか有効にできないので、新しい BudgetOrderstartDateTime フィールドと endDateTime フィールドは、使用中または保留中を含めて既存の BudgetOrder の期間と重ならないようにしてください。startDateTimeendDateTime は閉区間を定義するもので、BudgetOrder の期間には startDateTimeendDateTime が含まれます。上の例の endDateTime20140831 235959 America/New_York であるため、startDateTime20140901 000000 America/New_York である 9 月の BudgetOrder と期間は重なりません。同じアカウントの別の BudgetOrder と期間が重なる BudgetOrder を作成しようとすると、INVALID_BUDGET_DATE_RANGE エラーになります。

上の例にあるように startDateTimeendDateTime は秒単位で指定します。タイムゾーンは通常、顧客の dateTimeZone に合わせます。

BudgetOrder を編集する

既存の BudgetOrder は mutate オペレーションの ID を参照して更新できます。特定の BillingAccount を使用できる BudgetOrder の数には上限があるため、BudgetOrder は新規に作成するより既存のものを更新した方が得策です。

前のセクションで作成したアカウント単位の予算の費用の上限を引き上げ、期間を延ばすには、既存の BudgetOrder オブジェクトの spendingLimitendDateTime を更新します。

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(order);
bos.mutate(new BudgetOrderOperation[] {op});

BudgetOrder の費用の上限を引き下げることもできますが、費用としてすでに発生している金額を下回る設定はできません。

費用の上限と調整額

BudgetOrder の費用の上限を変更する際には、調整額を考慮することも重要です。調整額とは予算オーダーに適用されるクレジットのことで、新たに料金が発生することなく通常の費用の上限を超えた金額を使用することができます。

mutate() リクエストを使用する際、費用の上限で調整額のことは一切考慮しません。送信する値は費用として使用したいと考えている調整前の金額です。ただし get() リクエストの spendingLimit には BudgetOrder に適用される調整額が含まれます。前に送信した費用の上限を勘案し、それとの比較で費用の上限を再設定する場合は調整額を必ず考慮に入れるようにしてください。

BudgetOrder を削除する

BudgetOrder は設定した期間が終了するか、意図的にキャンセルすることで無効になります。BudgetOrder が無効になった場合は、新しいものを作成しないと、クライアント アカウントで費用を再び有効にすることができません。

有効な BudgetOrder をキャンセルするには、API を通じて REMOVE リクエストを送信します。これで endDateTime が現在の時刻に設定されて予算の期間が終了し、それ以降の費用の発生を防ぐことができます。

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

請求先顧客を変更する

クライアント アカウントの費用を支払う請求先顧客を変更するには、新しい請求先顧客の BillingAccounts を指し示す BudgetOrder を作成します。ただしそうした請求先の変更(CBT)オペレーションは、クライアント アカウントごとに 1 つしか保留状態にできません。

たとえば 8 月の BudgetOrder が期限切れになった後、クライアント アカウント 123-456-7890 の費用を支払う顧客を変更するには、新しい請求先顧客に関連付けられた BillingAccount を使用する 9 月分の BudgetOrder を追加します。ただし、クライアント アカウントでは 1 つの CBT オペレーションしか予約できないため、それ以降の BudgetOrders はすべてこの新しい請求先顧客を使用することになります。

制限事項

説明 エラー 補足
BillingAccount あたりの BudgetOrder 75,000 BudgetOrderError.GENERIC_BILLING_ERROR, trigger: TOO_MANY_ORDER_LINES_NEW_BILLING_ACCOUNT_REQUIRED

BillingAccount あたりの BudgetOrders 数は最大 75,000 個です。

その上限に達した場合は、AdWords 管理画面で新しい請求書の設定を作成し、将来的な BudgetOrders を新しい BillingAccount に追加します。

mutate リクエストあたりのオペレーション数 1 BudgetOrderError.MORE_THAN_ONE_OPERATIONS オペレーションはそれぞれ別個のリクエストで送信する必要があります。
1 秒あたりのリクエスト数 1 RateExceededError.RATE_EXCEEDED

このサービスのレート制限は 1 qps です。

リクエストは 1 秒あたり 1 回を超えないように制限してください。複数のリクエストを同時に送信しないことも重要です。

一般的なエラー

エラー 内容と対策
BudgetOrderError.INVALID_BUDGET_DATE_RANGE, trigger: Overlapping budget found

期間が重なる BudgetOrder オブジェクトは作成できません。

使用中または保留中の別の予算と期間が重ならないように、BudgetOrderstartDateTime または endDateTime を変更してください。

AdWords 管理画面で新しい予算オーダーを作成しようとすると、プロセスが完了せずに保留状態になることがあります。管理画面で予算オーダーを最後まで作成するか、AdWords API のサポートチームに対応を依頼してください。

BudgetOrderError.INVALID_BUDGET_ALREADY_SPENT

費用の上限は、該当する期間にすでに発生してしまっている費用を下回る金額には設定できません。

BudgetOrderstartDateTime から endDateTime までの期間にすでに発生している費用を確認し、それを超える金額を BudgetOrderspendingLimit に設定してください。

BudgetOrderError.CUSTOMER_NOT_WHITELISTED_FOR_NEW_BILLING

MCC アカウントが統合請求を使用できる状態になっていません。

Google の担当者に連絡して、そのアカウントで統合請求を有効にしてください。

NotWhitelistedError.CUSTOMER_NOT_WHITELISTED_FOR_API

MCC アカウントが BudgetOrderService API を使用できるホワイトリストに入っていません。

Google の担当者に連絡して、API サービスへのアクセス権を取得してください。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。