Abo abrufen und aktualisieren

Nachdem Sie ein Abo abgerufen haben, können Sie anhand der Informationen aus der erfolgreichen Antwort den Status des Abos ändern oder das Abo aktualisieren. Auf dieser Seite werden die verschiedenen Möglichkeiten erläutert, wie Sie ein Abo abrufen und aktualisieren können.

Abo abrufen

Verwenden Sie die folgende GET-HTTP-Anfrage, um ein erfolgreich bestelltes oder übertragenes Abo abzurufen.

GET https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID

Dabei gilt:

  • CUSTOMER_ID: Entweder der Name der primären Domain des Kunden oder die eindeutige ID des Kunden.
  • SUBSCRIPTION_ID: Die Abo-ID, die für jeden Kunden eindeutig ist. Sie können diesen Wert mit der Methode Alle Reseller-Abos abrufen abrufen.

Dieser Vorgang hat keine Parameter im Anfragetext.

Eine erfolgreiche Antwort gibt den HTTP-Statuscode 200 und die Einstellungen des Abos zurück. In der folgenden Beispielantwort ist das Attribut isInTrial false, aber es gibt kein trialEndTime-Attribut. Das bedeutet, dass dieser Kunde noch nie eine kostenlose 30-tägige Testversion mit diesem Tarif hat.

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "billingMethod": "ONLINE",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "RENEW_CURRENT_USERS_MONTHLY_PAY"
  },
  "purchaseOrderId": "example.com_annual_1",
  "status": "ACTIVE",
  "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
  "skuName": "Google Workspace Business Standard"
}

Alle Abos für einen Kunden abrufen

Wenn Sie alle Abos eines bestimmten Reseller-Kunden abrufen möchten, die erfolgreich bestellt oder übertragen wurden, verwenden Sie die folgende GET-HTTP-Anfrage und fügen Sie das Autorisierungstoken ein:

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=CUSTOMER_ID value&pageToken=START_DATE&maxResults=MAX_NUMBER

Dabei gilt:

  • CUSTOMER_ID: Entweder der Name der primären Domain des Kunden oder die eindeutige ID des Kunden.
  • START_DATE: Das Startdatum im Format YYYY-MM-DD.
  • MAX_NUMBER: Die maximale Anzahl von Ergebnissen, die auf einer Antwortseite zurückgegeben werden.

Dieser Vorgang hat keine Parameter im Anfragetext.

Eine erfolgreiche Antwort gibt den HTTP-Statuscode 200 und eine Liste der Abos und Einstellungen des Kunden zurück. Die Liste der Abos kann Produkte enthalten, die in dieser Version der Reseller API nicht verwaltet werden.

Wenn Sie diesen Kunden nicht verwalten, wird der Fehler 403 "Forbidden" zurückgegeben.

Alle übertragbaren Abos eines Kunden abrufen

Verwenden Sie die folgende GET-HTTP-Anfrage und fügen Sie das Autorisierungstoken ein, um alle Abos eines Kunden abzurufen, die möglicherweise an die Verwaltung des Resellers übertragen werden können. Die customerId ist erforderlich und ist die eindeutige Kennung des Kunden, die beim Abrufen des Kontos eines Reseller-Kunden zurückgegeben wird. customerAuthToken ist ein von Ihrem Kunden bereitgestelltes Übertragungstoken, das für Ihre Reseller-ID spezifisch ist. Nach der Erstellung durch den Kunden ist es 14 Tage lang gültig. Weitere Informationen dazu, wie Kunden das Token generieren, finden Sie unter Google Workspace-Konto an einen Reseller übertragen.

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=CUSTOMER_ID&customerAuthToken=AUTH_TOKEN&pageToken=START_DATE&maxResults=MAX_NUMBER

Dabei gilt:

  • CUSTOMER_ID: Entweder der Name der primären Domain des Kunden oder die eindeutige ID des Kunden.
  • AUTH_TOKEN: Ein von Ihrem Kunden bereitgestelltes Übertragungstoken, das für Ihre Reseller-ID spezifisch ist. Nachdem der Kunde sie generiert hat, ist sie 14 Tage lang gültig. Weitere Informationen dazu, wie Kunden das Token generieren, finden Sie unter Google Workspace-Konto an einen Reseller übertragen. Wenn dieser Wert ungültig oder abgelaufen ist, gibt die API-Antwort den Fehler 403 "Forbidden" zurück.
  • START_DATE: Das Startdatum im Format YYYY-MM-DD.
  • MAX_NUMBER: Die maximale Anzahl von Ergebnissen, die auf einer Antwortseite zurückgegeben werden.

Dieser Vorgang hat keine Parameter im Anfragetext.

Eine erfolgreiche Antwort gibt den HTTP-Statuscode 200 und eine Liste der übertragbaren Abos des Kunden mit dem Ablaufdatum des Übertragungstokens und der Mindestanzahl der Lizenzen zurück, die im Übertragungsauftrag erforderlich sind. Ein Kunde hat möglicherweise weitere Abos, die nicht übertragbar sind.

{
  "kind": "reseller#subscriptions",
  "subscriptions": [
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-6543",
      "subscriptionId": "432",
      "skuId": "1010020028",
      "billingMethod": "ONLINE",
      "creationTime": "1331647980142",
      "plan": {
        "planName": "ANNUAL",
        "isCommitmentPlan": true,
        "commitmentInterval": {
          "startTime": "1331647980142",
          "endTime": "1363183980142"
        }
      },
      "seats": {
        "kind": "subscriptions#seats",
        "numberOfSeats": 10,
        "maximumNumberOfSeats": 500,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "transferInfo": {
        "transferabilityExpirationTime": "1333183980142",
        "minimumTransferableSeats": "20"
      },
      "purchaseOrderId": "PO_890",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-6543",
      "subscriptionId": "140",
      "skuId": "1010020028",
      "creationTime": "1329389322728",
      "plan": {
        "planName": "FLEXIBLE",
        "isCommitmentPlan": false
      },
      "seats": {
        "kind": "subscriptions#seats",
        "maximumNumberOfSeats": 50
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false,
        "trialEndTime": "1331877480016"
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "transferInfo": {
        "transferabilityExpirationTime": "1333183780159",
        "minimumTransferableSeats": "10"
      },
      "purchaseOrderId": "",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
  ],
  "nextPageToken": "token"
}

Wenn Sie diese Abos mithilfe des Batchvorgangs übertragen möchten, übertragen Sie alle Abos. Bei der Übertragung jedes Abos einzeln wird ein Fehler ausgegeben. Darüber hinaus überträgt der Batchvorgang nur Abos mit dem Status ACTIVE. Weitere Informationen finden Sie unter Abo übertragen.

Alle Reseller-Abos abrufen

Verwenden Sie die folgende GET-HTTP-Anfrage und fügen Sie das Autorisierungstoken ein, um alle erfolgreich bestellten oder übertragenen Abos eines Resellers abzurufen. 

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=PREFIX &pageToken=TOKEN&maxResults=MAX_NUMBER

Dabei gilt:

  • PREFIX: Der Anfang des Namens des Kunden, dessen Abos Sie suchen.
  • TOKEN: Ein Token, das eine bestimmte Ergebnisseite angibt, die der Server zurückgeben soll.
  • MAX_NUMBER: Die maximale Anzahl von Ergebnissen, die auf einer Antwortseite zurückgegeben werden.

Dieser Vorgang kann den OAuth-Lesezugriffsbereich verwenden. customerNamePrefix, pageToken und maxResults sind optionale Abfragestrings.

Im folgenden Beispiel werden alle Abos eines Resellers abgerufen, die Kunden gehören, deren Name mit „exam“ beginnt:

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=exam

{
  "kind": "reseller#subscriptions",
  "subscriptions": [
    {
      "kind": "subscriptions#subscription",
      "customerId": "C0123456",
      "subscriptionId": "123",
      "skuId": "1010020028",
      "creationTime": "1331647980142",
      "billingMethod": "ONLINE",
      "plan": {
        "planName": "ANNUAL",
        "isCommitmentPlan": true,
        "commitmentInterval": {
          "startTime": "1331647980142",
          "endTime": "1363183980142"
        }
      },
      "seats": {
        "kind": "subscriptions#seats",
        "numberOfSeats": 10,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "purchaseOrderId": "PO_135",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-5678",
      "subscriptionId": "1404686",
      "skuId": "1010020028",
      "billingMethod": "ONLINE",
      "creationTime": "1329389322728",
      "plan": {
        "planName": "FLEXIBLE",
        "isCommitmentPlan": false
      },
      "seats": {
        "kind": "subscriptions#seats",
        "maximumNumberOfSeats": 50,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false,
        "trialEndTime": "1331877480016"
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "AUTO_RENEW"
      },
      "purchaseOrderId": "",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
  ],
  "nextPageToken": "token"
}

Abo aktualisieren

Die Aktualisierung von Google Workspace-Abos ist je nach Abo unterschiedlich. Bevor Sie einen Plan aktualisieren, sollten Sie Folgendes berücksichtigen:

  • Wenn Sie ein Abo erstellen und der Kunde dafür infrage kommt, können Sie das Abo als 30-tägiges Probeabo anbieten. Sowohl beim flexiblen Preismodell als auch beim Jahrestarif können Sie einen kostenlosen 30-tägigen Testzeitraum nutzen. Während des Testzeitraums können Sie das Preismodell des Abos so oft wie nötig in flexible oder jährliche Zusicherungstarife ändern. Nach dem Ende des Testzeitraums und wenn der Tarif aktiv wird, gelten für das Aktualisieren derselben dieselben Regeln wie für die anderen Abos. Wenn Sie ein Probeabo sofort in ein aktives Abo verschieben möchten, starten Sie einen kostenpflichtigen Dienst aus einem 30-tägigen kostenlosen Testzeitraum. Weitere Informationen zu 30-tägigem Testzeitraum und Regeln für die Kundenqualifikation finden Sie in der Hilfe für Administratoren.

  • Sie können einen flexiblen Tarif auf einen Jahrestarif umstellen.

  • Sie können einen Jahrestarif nicht aktualisieren.

  • Nicht alle Abos sind mit allen Produkten kompatibel. Weitere Informationen dazu, welche Produkte von diesen Tarifen verwendet werden, finden Sie unter Produkte und SKUs.

Verwenden Sie die folgende POST-HTTP-Anfrage, um einen Plan für ein 30-tägiges Probeabo oder ein Abo mit flexiblem Tarif auf einen Jahrestarif zu aktualisieren:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changePlan

Dabei gilt:

  • CUSTOMER_ID: Entweder der Name der primären Domain des Kunden oder die eindeutige ID des Kunden.
  • SUBSCRIPTION_ID: Die Abo-ID, die für jeden Kunden eindeutig ist. Sie können diesen Wert mit der Methode Alle Reseller-Abos abrufen abrufen.

Im folgenden Beispiel wird das Abo mit subscriptionId auf den Wert 123 aktualisiert. customerId lautet C0123456.

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/changePlan

Der Anfragetext hat Folgendes:

{
  "kind": "reseller#changePlanRequest",
  "planName": "ANNUAL_MONTHLY_PAY",
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10
  },
  "purchaseOrderId": "123_March2012"
}

Eine erfolgreiche Antwort gibt den HTTP-Statuscode 201 und die aktualisierten Einstellungen für den Aboplan zurück:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "purchaseOrderId": "123_March2012",
  "status": "ACTIVE",
  "skuName": "Google Workspace Business Standard"
}

Nutzerlizenzen eines Abos aktualisieren

Beim Aktualisieren eines Abos für einen Jahrestarif gilt eine andere Abo-Property als beim Abo eines flexiblen Google Workspace-Abos.

Lizenzen für ein Jahresabo aktualisieren

Verwenden Sie die folgende POST-HTTP-Anfrage, um die Nutzerlizenzeinstellungen eines Jahresabos zu aktualisieren:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changeSeats

Dabei gilt:

  • CUSTOMER_ID: Entweder der Name der primären Domain des Kunden oder die eindeutige ID des Kunden.
  • SUBSCRIPTION_ID: Die Abo-ID, die für jeden Kunden eindeutig ist. Sie können diesen Wert mit der Methode Alle Reseller-Abos abrufen abrufen.

Im folgenden Beispiel wird das Abo mit 123 subscriptionId aktualisiert. customerId lautet C0123456. Der Text der Anfrage variiert je nach Art des Tarifs:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/changeSeats

Das Abo eines Jahrestarifs für Google Workspace verwendet diesen Anfragetext, um die Anzahl der Nutzerlizenzen zu aktualisieren. Der Wert numberOfSeats ist eine Summe. Wenn Sie beispielsweise 10 Nutzerlizenzen hatten und eine Kundenbestellung für 5 neue Lizenzen haben, beträgt die Gesamtzahl im Text von numberOfSeats 15, wie im folgenden Beispiel gezeigt:

{
    "kind": "subscriptions#seats",
    "numberOfSeats": 15
}

Lizenzen für das Abo eines flexiblen Tarifs aktualisieren

Das Abo eines flexiblen Google Workspace-Abos verwendet den Anfragetext, um die Nutzerlizenzen zu aktualisieren. Der Wert maximumNumberOfSeats ist die Gesamtzahl der vorhandenen Lizenzen und der neuen Lizenzen. Dies ist die maximale Anzahl von Nutzerlizenzen, die für das Konto bereitgestellt werden können.

{
  "kind": "subscriptions#seats",
  "maximumNumberOfSeats": 15
}

Eine erfolgreiche Antwort gibt den HTTP-Statuscode 201 und die aktualisierten Einstellungen für die Abolizenz zurück:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "FLEXIBLE",
    "isCommitmentPlan": false
  },
  "seats": {
    "kind": "subscriptions#seats",
    "maximumNumberOfSeats": 15,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "skuName": "Google Workspace Business Standard"
}

Verlängerungseinstellungen für Abos aktualisieren

Verwenden Sie die folgende POST-HTTP-Anfrage, um die Verlängerungseinstellungen eines Jahresabos zu aktualisieren:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changeRenewalSettings

Dabei gilt:

  • CUSTOMER_ID: Entweder der Name der primären Domain des Kunden oder die eindeutige ID des Kunden.
  • SUBSCRIPTION_ID: Die Abo-ID, die für jeden Kunden eindeutig ist. Sie können diesen Wert mit der Methode Alle Reseller-Abos abrufen abrufen.

Hier ein Beispiel für einen Anfragetext:

{
  "kind": "subscriptions#renewalSettings",
  "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
}

Der Wert des Attributs renewalType kann einer der folgenden Werte sein:

  • AUTO_RENEW_YEARLY_PAY: Am Ende des Intervalls eines Jahrestarifs verlängern Sie das Abo automatisch als ANNUAL_YEARLY_PAY mit derselben numberOfSeats.
  • AUTO_RENEW_MONTHLY_PAY: Am Ende des Intervalls eines Jahrestarifs wird der Aboplan automatisch als ANNUAL_MONTHLY_PAY mit demselben numberOfSeats verlängert.
  • RENEW_CURRENT_USERS_YEARLY_PAY: Am Ende des Intervalls eines Jahrestarifs verlängern Sie das Abo als ANNUAL_YEARLY_PAY, verwenden aber die Gesamtzahl der aktuell aktiven Nutzerlizenzen. Dies ist die Standardeinstellung für aktive jährliche Zusicherungstarife (jährliche Zahlungen).
  • RENEW_CURRENT_USERS_MONTHLY_PAY: Am Ende des Intervalls eines Jahrestarifs verlängern Sie das Abo als ANNUAL_MONTHLY_PAY, verwenden aber die Gesamtzahl der aktuell aktiven Nutzerlizenzen. Dies ist die Standardeinstellung für aktive jährliche Zusicherungstarife (monatliche Zahlung).
  • SWITCH_TO_PAY_AS_YOU_GO: Am Ende des Intervalls eines Jahrestarifs ändern Sie den Jahrestarif in einen flexiblen Tarif.
  • CANCEL: Am Ende des Jahrestarifs ist das Abo gesperrt. Informationen zum Aufheben einer Sperrung finden Sie in der Hilfe für Administratoren.

Eine erfolgreiche Antwort gibt den HTTP-Statuscode 201 und die aktualisierten Einstellungen für die Aboverlängerung zurück:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 15,
    "licensedNumberOfSeats": 15
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "skuName": "Google Workspace Business Standard"
}

Kostenpflichtigen Dienst über ein kostenloses Probeabo starten

Verwenden Sie die folgende POST-HTTP-Anfrage, um ein 30-tägiges kostenloses Probeabo sofort in ein kostenpflichtiges Abo zu verschieben. 

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/startPaidService

Dabei gilt:

  • CUSTOMER_ID: Entweder der Name der primären Domain des Kunden oder die eindeutige ID des Kunden.
  • SUBSCRIPTION_ID: Die Abo-ID, die für jeden Kunden eindeutig ist. Sie können diesen Wert mit der Methode Alle Reseller-Abos abrufen abrufen.

Im folgenden Beispiel wird C0123456 als customerId und der Wert subscriptionId von 123 verwendet:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/startPaidService

Dieser Vorgang hat keine Parameter im Anfragetext.

Eine erfolgreiche Antwort gibt den HTTP-Statuscode 201 und die aktualisierten Aboeinstellungen zurück:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 15,
    "licensedNumberOfSeats": 15
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "skuName": "Google Workspace Business Standard"
}

Abo upgraden oder downgraden

Sie können kein Downgrade für Jahrespläne in der Mitte der Laufzeit ausführen und kein Downgrade über die Verlängerungseinstellungen planen. Wir empfehlen, die Verlängerungseinstellungen auf FLEXIBLE festzulegen und dann nach der Verlängerung ein Downgrade auszuführen.

Wenn Sie ein Abo upgraden oder downgraden möchten, erstellen Sie ein neues Abo mit der skuId, die Sie upgraden oder downgraden möchten.

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions

Dabei gilt:

  • CUSTOMER_ID: Entweder der Name der primären Domain des Kunden oder die eindeutige ID des Kunden.

Durch diesen Anruf wird das vorherige Abo beendet und ein neues erstellt.

Weitere Informationen zu Upgrades und Downgrades finden Sie auf der Seite „Produkte und SKUs“.