Budgetauftragsdienst

Dieser Dienst steht nur für freigeschaltete AdWords-Verwaltungskonten zur Verfügung, für die außerdem die monatliche Rechnungsstellung eingerichtet ist. Wenden Sie sich an Ihren Google-Kundenbetreuer, wenn Sie mehr Informationen zur Verwendung dieses Dienstes mit Ihrem Verwaltungskonto benötigen.

The BudgetOrderService (BOS) enables approved manager accounts to programmatically create account‒level budgets for the client accounts they manage on consolidated billing. So lassen sich von Kundenkonten dem Rechnungskonto eines Administrators Ausgaben in Rechnung stellen.

Mithilfe der API können Administratoren BudgetOrder-Objekte erstellen und verwalten, mit denen Budgets auf Kontoebene für Kundenkonten definiert werden. Jeder BudgetOrder ist wiederum mit einem BillingAccount verknüpft. Dieses steht für eine Rechnungskonfiguration, der die Gebühren eines Kunden in Rechnung gestellt werden. Ein Administrator kann BudgetOrder-Objekte von mehreren Kundenkonten demselben BillingAccount hinzufügen, um die Gebühren in einer einzelnen Rechnungskonfiguration zusammenzufassen.

Begriffe

Bei der Konfiguration der Abrechnung mit BOS spielen die folgenden Begriffe eine Rolle.

Kundenkonto
Ein normales AdWords-Konto, das Kampagnen und Anzeigengruppen enthält, Anzeigen ausliefert usw. In diesem Leitfaden wird der Begriff "Kundenkonto" verwendet, um eine Verwechslung mit "Rechnungsempfänger" zu vermeiden.
Rechnungskonto
Die üblichen zum Erstellen von Rechnungen erforderlichen Informationen. Dazu gehören zum Beispiel die Währung der Rechnungen, der Empfänger, an den die Rechnungen gesendet und von dem sie bezahlt werden, sowie ein Name, der auf die Rechnungen gedruckt werden kann, um sie leichter wiederzufinden.
  • Rechnungskonten können in der AdWords-Web-Benutzeroberfläche bearbeitet, jedoch über die AdWords API nicht erstellt oder bearbeitet werden.
  • Das Wort "Konto" in "Rechnungskonto" ist hier kein spezieller Typ eines zur Abrechnung verwendeten Kundenkontos. Es bezieht sich lediglich darauf und ist ein Objekt, das die für zugehörige Rechnungen verwendeten Informationen enthält.
  • Rechnungskonten sind in BOS als BillingAccount repräsentiert.
  • Mit dem Feld id in einem BillingAccount und dem Feld billingAccountId in einem BudgetOrder kann darauf verwiesen werden.
Budgetauftrag
Die Genehmigung für ein bestimmtes Kundenkonto, einen bestimmten Geldbetrag in einem bestimmten Zeitraum auszugeben. Diese Ausgaben laufen auf einem speziellen Rechnungskonto auf.
  • So könnte beispielsweise ein Budgetauftrag wie folgt lauten: "AdWords-Konto 123-456-7890 darf im August bis zu 100 $ ausgeben und diese Ausgaben müssen unter Verwendung der Informationen im Rechnungskonto 1212-1234-3434-3434 in Rechnung gestellt werden."
  • Dasselbe Rechnungskonto kann für verschiedene Budgetaufträge und mehrere Kundenkonten verwendet werden. Sie können also für verschiedene Kundenkonten die Ausgaben auf derselben Rechnung, d. h. einer konsolidierten Rechnung, auflaufen lassen, indem Sie ihre Budgetaufträge so einrichten, dass sie auf dasselbe Rechnungskonto verweisen.
  • Budgetaufträge sind in BOS als BudgetOrder repräsentiert.
Rechnungsempfänger
Eine juristische Person, die eine Rechnung empfangen und bezahlen kann. Dies entspricht einem "Vertragspartner" in unserem alten Abrechnungssystem.
  • Wenden Sie sich an den Kundenservice, wenn Sie einen Rechnungsempfänger erstellen möchten. Nachdem mindestens ein Rechnungsempfänger erstellt und mit Ihrem Verwaltungskonto verknüpft wurde, können Sie damit beginnen, Budgetaufträge programmatisch zu verwalten.
  • Auf Rechnungsempfänger kann mit dem Feld primaryBillingId in einem BillingAccount oder in einem BudgetOrder verwiesen werden.

Beziehungen zwischen Administratoren und Kunden

Da BOS speziell zur Verwendung durch Verwaltungskonten konzipiert ist, sollten Sie den Unterschied zwischen dem Senden einer Anfrage durch den Administrator und dem Kundenkonto kennen, das davon betroffen ist.

  • Administrator: das Verwaltungskonto, das zum authentifizierten API-Nutzer gehört
  • Kunde: das Kundenkonto, dessen clientCustomerId im Header-Feld einer Anfrage angegeben ist

Wenden Sie sich an den Kundenservice, um Rechnungsempfänger mit Verwaltungskonten verknüpfen zu lassen. Im Anschluss kann dann ein BudgetOrder für ein Kundenkonto erstellt werden, falls der Administrator, der die API-Anfrage ausführt, folgende Voraussetzungen erfüllt:

  • Er hat Zugriff auf das Verwaltungskonto, das zu einem bestimmten Rechnungsempfänger gehört.
  • Er hat Zugriff auf das Kundenkonto, das den Rechnungsempfänger verwenden soll.
  • Er ist für BudgetOrderService freigeschaltet.

Wenn Sie beispielsweise als Verwaltungskonto A von oben authentifiziert sind, können Sie Kunde 123-456-7890 zu BillingAccounts hinzufügen, die mit einem beliebigen Verwaltungskonto im Baum verknüpft sind, da das Verwaltungskonto auf der obersten Ebene sowohl auf Verwaltungskonto B, Verwaltungskonto C, als auch auf das Kundenkonto zugreifen kann.

Sie müssen sich mit dem Verwaltungskonto auf der höchsten Ebene authentifizieren, um sicherzustellen, dass Sie Zugriff auf die Verwaltungs- und Kundenkonten haben, die Sie verwalten möchten.

Liste der verfügbaren Rechnungskonten

Mithilfe des getBillingAccounts()-Vorgangs von BudgetOrderService können Sie eine Liste der BillingAccounts (Rechnungskonten) abrufen, auf die der authentifizierte Administrator zugreifen kann. Jedes BillingAccount-Objekt steht für eine Rechnungskonfiguration, die mit einem Verwaltungskonto der Administratoren des Zielkundenkontos verknüpft ist. Dies sind die BillingAccount (Rechnungsempfänger), die von BudgetOrders des Zielkundenkontos verwendet werden können.

Um beispielsweise eine Liste der BillingAccounts abzurufen, die Kunde 123-456-7890 verwenden könnte, würden Sie getBillingAccounts() aufrufen, indem Sie sich als eines seiner übergeordneten Verwaltungskonten authentifizieren. Bei Verwendung von Java mit unseren Clientbibliotheken sieht das dann wie folgt aus:

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

Je nachdem, als welcher Administrator Sie sich authentifizieren, werden von einem Aufruf von getBillingAccounts() andere BillingAccounts zurückgegeben. Der Vorgang gibt BillingAccounts zurück, die mit allen Administratoren eines bestimmten Kunden verknüpft sind. Er durchläuft jedoch die Hierarchie nur bis maximal zur Ebene des authentifizierten Administrators.

Wenn beispielsweise die beiden Verwaltungskonten A und C von oben aktive BillingAccounts haben, gibt ein Aufruf von getBillingAccounts() als A für clientCustomerId 123-456-7890 beide Sätze zurück. Wenn der Aufruf jedoch als C erfolgt, sind nur die BillingAccounts für C sichtbar.

Jedes BillingAccount-Objekt hat sowohl eine ID als auch eine primaryBillingId. Die ID kennzeichnet das BillingAccount eindeutig. In anderen Objekten wird darauf als billingAccountId verwiesen. Die primaryBillingId kennzeichnet den Rechnungsempfänger, der die Gebühren auf der Rechnung bezahlt.

Die primaryBillingId findet sich auch in der AdWords-Benutzeroberfläche unter Abrechnung > Abrechnungseinstellungen neben "Rechnungszahler".

Neuen Budgetauftrag erstellen

Um einen Kunden einem der BillingAccounts hinzuzufügen, auf die Sie Zugriff haben, erstellen Sie einen BudgetOrder (Budgetauftrag). Damit wird sein Budget auf Kontoebene festgelegt. Die Angaben umfassen beispielsweise Beginn, Ende und Ausgabengrenze für den Kunden.

Nachdem Sie wie oben die verfügbaren BillingAccounts abgerufen haben, können Sie ein neues Budget auf Kontoebene für August mit einer Ausgabengrenze von 100 $ festlegen. Dafür wird das im vorherigen Beispiel zurückgegebene BillingAccount verwendet:

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});

Der vom mutate-Vorgang zurückgegebene BudgetOrderReturnValue enthält die ID des neuen BudgetOrder. Der BudgetOrder enthält das Feld lastRequest mit Informationen zum Status der Anfrage. Neu gesendete BudgetOrders haben den Status UNDER_REVIEW bis sie genehmigt sind und aktiviert werden.

Es kann etwas dauern (normalerweise weniger als eine Stunde), bis neue BudgetOrders aktiv werden. Sie sollten daher möglichst lange vor der gewünschten startDateTime erstellt werden. Zwar kann immer nur ein BudgetOrder für einen Kunden aktiv sein, doch lassen sich zukünftige Budgets jederzeit erstellen und in die Warteschlange setzen. So könnten Sie beispielsweise für clientCustomerId 123-456-7890 für September und Oktober BudgetOrders sofort nach dem Erstellen des BudgetOrder für August erstellen.

Wie oben erwähnt, darf immer nur ein BudgetOrder aktiv sein. Stellen Sie daher sicher, dass die Felder startDateTime und endDateTime eines neuen BudgetOrder nicht in den Zeitraum eines anderen BudgetOrder (aktiv oder zukünftig) fallen. Von startDateTime und endDateTime wird ein abgeschlossenes Intervall definiert: Der Zeitraum des BudgetOrder beinhaltet die startDateTime und die endDateTime. Im Beispiel oben ist endDateTime = 20140831 235959 America/New_York. Dieser Zeitraum überschneidet sich nicht mit einem zukünftigen möglichen BudgetOrder für September mit startDateTime = 20140901 000000 America/New_York. Wenn Sie versuchen, einen BudgetOrder zu erstellen, dessen Zeitraum sich mit einem anderen BudgetOrder für dasselbe Konto überschneidet, wird der Fehler INVALID_BUDGET_DATE_RANGE gemeldet.

Wie Sie im Beispiel oben sehen, werden startDateTime und endDateTime sekundengenau angegeben. In den meisten Anwendungsfällen sollte die Zeitzone die dateTimeZone des Kunden sein.

Budgetauftrag bearbeiten

Sie können einen bestehenden BudgetOrder aktualisieren, indem Sie in einem mutate-Vorgang auf seine ID verweisen. Es ist immer besser, einen bestehenden BudgetOrder zu aktualisieren statt einen neuen zu erstellen, da die Anzahl der BudgetOrders, die ein bestimmtes BillingAccount verwenden können, begrenzt ist.

Sie können die Ausgabengrenze und den Zeitraum des im vorherigen Abschnitt erstellten Budgets auf Kontoebene erhöhen bzw. verlängern, indem Sie das bestehende BudgetOrder-Objekt mit neuen Werten für spendingLimit und endDateTime aktualisieren:

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});

Sie können auch die Ausgabengrenze eines BudgetOrder senken. Sie darf jedoch nicht niedriger als der Betrag sein, der bereits für den Auftrag ausgegeben wurde.

Ausgabengrenzen und Anpassungen

Wenn Sie die Ausgabengrenze eines BudgetOrder ändern, müssen auch Anpassungen berücksichtigt werden. Anpassungen sind für den Budgetauftrag verwendete Guthaben, mit denen Sie ohne zusätzliche Kosten mehr als durch die Ausgabengrenze festgelegt ausgeben können.

Bei mutate()-Anfragen werden für die Ausgabengrenze keine Anpassungen berücksichtigt. Der gesendete Wert entspricht immer dem Betrag, den Sie ausgeben möchten, bevor Anpassungen angewendet werden. Bei get()-Anfragen schließt spendingLimit jedoch alle Anpassungen an Ihrem BudgetOrder ein. Wenn Sie die Ausgabengrenze relativ zu einer bereits gesendeten Ausgabengrenze festlegen möchten, müssen Sie Anpassungen berücksichtigen.

Budgetauftrag entfernen

Ein BudgetOrder endet, wenn das Ende seines Ausgabenzeitraums erreicht ist oder er aktiv storniert wird. Sobald ein BudgetOrder beendet ist, muss ein neuer erstellt werden, um wieder Ausgaben für ein Kundenkonto zu ermöglichen.

Sie können einen aktiven BudgetOrder stornieren, indem Sie über die API eine REMOVE-Anfrage senden. Dadurch wird endDateTime auf die aktuelle Uhrzeit gesetzt und der Budgetzeitraum wird abgeschlossen. Weitere Ausgaben werden so verhindert.

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

Rechnungsempfänger ändern

Sie können den Rechnungsempfänger, der für die Ausgaben eines Kundenkontos bezahlt, ändern, indem Sie einen BudgetOrder erstellen, der auf eines der BillingAccounts des neuen Rechnungsempfängers verweist. Allerdings darf für ein bestimmtes Kundenkonto nur ein einziger Vorgang zum Ändern des Rechnungsempfängers ausstehend sein.

Um beispielsweise zu ändern, wer für den Kunden 123-456-7890 bezahlt, nachdem der BudgetOrder für August abläuft, könnten Sie einen neuen BudgetOrder für September hinzufügen, der ein BillingAccount verwendet, das mit einem neuen Rechnungsempfänger verknüpft ist. Allerdings müssen dann alle nachfolgenden BudgetOrders diesen neuen Rechnungsempfänger verwenden, da für das Kundenkonto nur eine Änderung des Rechnungsempfängers geplant werden darf.

Einschränkungen

Beschreibung Wert Fehler Hinweise
BudgetOrder-Objekte pro BillingAccount 75.000 BudgetOrderError.GENERIC_BILLING_ERROR, trigger: TOO_MANY_ORDER_LINES_NEW_BILLING_ACCOUNT_REQUIRED

Es sind maximal 75.000 BudgetOrders pro BillingAccount möglich.

Wenn Sie die Obergrenze erreicht haben, erstellen Sie eine neue Rechnungskonfiguration in der AdWords-Benutzeroberfläche und fügen Sie zukünftige BudgetOrders dem neuen BillingAccount hinzu.

Vorgänge pro mutate-Anfrage 1 BudgetOrderError.MORE_THAN_ONE_OPERATIONS Mehrere Vorgänge müssen in separaten Anfragen gesendet werden.
Anfragen pro Sekunde 1 RateExceededError.RATE_EXCEEDED

Die Ratenbegrenzung für diesen Dienst ist eine Anfrage pro Sekunde.

Stellen Sie sicher, dass Anfragen auf maximal eine pro Sekunde gedrosselt werden. Vermeiden Sie außerdem das Senden gleichzeitiger Anfragen.

Häufige Fehler

Fehler Anmerkungen und Behelfslösungen
BudgetOrderError.INVALID_BUDGET_DATE_RANGE, trigger: Overlapping budget found

Sich überschneidende BudgetOrder-Objekte können nicht erstellt werden.

Ändern Sie startDateTime oder endDateTime für den BudgetOrder, sodass er sich nicht mit einem anderen aktiven oder ausstehenden Budgetauftrag überschneidet.

Wenn Sie versucht haben, einen neuen Budgetauftrag über die AdWords-Benutzeroberfläche zu erstellen, wurde dieser Vorgang möglicherweise nicht abgeschlossen, sodass noch ein ausstehender Budgetauftrag offen ist. Schließen Sie in diesem Fall die Auftragserstellung in der Benutzeroberfläche ab oder wenden Sie sich an das AdWords API-Supportteam.

BudgetOrderError.INVALID_BUDGET_ALREADY_SPENT

Eine Ausgabengrenze kann nicht unter den Betrag gesenkt werden, der bereits in einem bestimmten Zeitraum ausgegeben wurde.

Legen Sie die spendingLimit für den BudgetOrder auf einen Wert fest, der größer als der Betrag ist, der für den BudgetOrder zwischen dem startDateTime und dem endDateTime ausgegeben wurde.

BudgetOrderError.CUSTOMER_NOT_WHITELISTED_FOR_NEW_BILLING

Das Verwaltungskonto ist nicht für die konsolidierte Abrechnung aktiviert.

Wenden Sie sich an den Google-Kundenservice, um die konsolidierte Abrechnung für Ihr Konto zu aktivieren.

NotWhitelistedError.CUSTOMER_NOT_WHITELISTED_FOR_API

Das Verwaltungskonto ist nicht zur Verwendung der BudgetOrderService API freigeschaltet.

Wenden Sie sich an den Google-Kundenservice, um Zugriff auf den API-Dienst zu erhalten.

Feedback geben zu...