Pobieranie i aktualizowanie subskrypcji

Po pobraniu subskrypcji możesz użyć informacji z udanej odpowiedzi, aby zmienić jej stan lub zaktualizować ją. Na tej stronie opisujemy różne sposoby pobierania i aktualizowania subskrypcji.

Pobieranie subskrypcji

Aby pobrać zamówioną lub przeniesioną subskrypcję, użyj tego żądania GETHTTP.

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

Zastąp następujące elementy:

  • CUSTOMER_ID: nazwa domeny podstawowej klienta lub jego unikalny identyfikator.
  • SUBSCRIPTION_ID: unikalny identyfikator subskrypcji dla każdego klienta. Możesz pobrać tę wartość za pomocą metody Pobierz wszystkie subskrypcje sprzedawcy.

Ta operacja nie zawiera parametrów w treści żądania.

Pomyślna odpowiedź zwraca kod stanu HTTP 200 i ustawienia subskrypcji. W poniższej przykładowej odpowiedzi właściwość isInTrial ma wartość false, ale brakuje właściwości trialEndTime. Oznacza to, że ten klient nigdy nie korzystał z 30-dniowego bezpłatnego okresu próbnego w ramach tego abonamentu.

{
  "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"
}

Pobieranie wszystkich subskrypcji klienta

Aby pobrać wszystkie subskrypcje konkretnego klienta sprzedawcy, które zostały zamówione lub przeniesione, użyj tego żądania HTTP GET i dołącz token autoryzacji:

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

Zastąp następujące elementy:

  • CUSTOMER_ID: nazwa domeny podstawowej klienta lub jego unikalny identyfikator.
  • START_DATE: data rozpoczęcia w formacie YYYY-MM-DD.
  • MAX_NUMBER: maksymalna liczba wyników zwróconych na stronę odpowiedzi.

Ta operacja nie zawiera parametrów w treści żądania.

Pomyślna odpowiedź zwraca kod stanu HTTP 200 oraz listę subskrypcji i ustawień klienta. Lista subskrypcji może zawierać usługi, które nie są zarządzane w tej wersji interfejsu Seller API.

Jeśli nie zarządzasz tym klientem, który nie jest zarządzany, zostanie zwrócony błąd 403 "Forbidden".

Pobieranie wszystkich subskrypcji klienta, które można przenieść

Aby pobrać wszystkie subskrypcje klienta, które mogą zostać przeniesione do systemu zarządzania sprzedawcy, użyj poniższego żądania HTTP GET i dołącz token autoryzacji. customerId jest wymagany i jest unikalnym identyfikatorem klienta zwracanym podczas pobierania konta klienta sprzedawcy. customerAuthToken to token przeniesienia udostępniony przez klienta, który jest specyficzny dla Twojego identyfikatora sprzedawcy. Wygenerowany przez klienta jest ważny przez 30 dni. Więcej informacji o generowaniu tokena przez klientów znajdziesz w artykule Przenoszenie konta Google Workspace do sprzedawcy.

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

Zastąp następujące elementy:

  • CUSTOMER_ID: nazwa domeny podstawowej klienta lub jego unikalny identyfikator.
  • AUTH_TOKEN: token przeniesienia udostępniony przez klienta, który jest powiązany z Twoim identyfikatorem sprzedawcy. Wygenerowana przez klienta jest ważna przez 30 dni. Więcej informacji o generowaniu tokena przez klientów znajdziesz w artykule Przenoszenie konta Google Workspace do sprzedawcy. Jeśli ta wartość jest nieprawidłowa lub wygasła, odpowiedź interfejsu API zwraca błąd 403 "Forbidden".
  • START_DATE: data rozpoczęcia w formacie YYYY-MM-DD.
  • MAX_NUMBER: maksymalna liczba wyników zwróconych na stronę odpowiedzi.

Ta operacja nie zawiera parametrów w treści żądania.

Pomyślna odpowiedź zwraca kod stanu HTTP 200 i listę subskrypcji klienta, które można przenieść, wraz z datą ważności tokena przeniesienia i minimalną liczbą stanowisk wymaganą w zleceniu przeniesienia. Klient może mieć dodatkowe subskrypcje, których nie można przenieść.

{
  "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"
}

Jeśli planujesz przenieść te subskrypcje przy użyciu operacji wsadowej, przenieś wszystkie subskrypcje. Przenoszenie subskrypcji pojedynczo powoduje błąd. Oprócz tego operacja wsadowa przenosi tylko subskrypcje o stanie ACTIVE. Więcej informacji znajdziesz w artykule Przenoszenie subskrypcji.

Pobieranie wszystkich subskrypcji sprzedawcy

Aby pobrać wszystkie zamówione lub przeniesione subskrypcje sprzedawcy, użyj poniższego żądania HTTP GET i dołącz token autoryzacji. 

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

Zastąp następujące elementy:

  • PREFIX: początek nazwy klienta, którego subskrypcji szukasz.
  • TOKEN: token identyfikujący określoną stronę z wynikami, który powinien zwracać serwer.
  • MAX_NUMBER: maksymalna liczba wyników zwróconych na stronę odpowiedzi.

W tej operacji można użyć zakresu dostępu OAuth tylko do odczytu. customerNamePrefix, pageToken i maxResults to opcjonalne ciągi zapytania.

Ten przykład umożliwia pobranie wszystkich subskrypcji sprzedawcy należących do klientów, których nazwa zaczyna się od „exam”:

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"
}

Aktualizacja abonamentu

Aktualizacja abonamentów Google Workspace różni się w zależności od abonamentu. Zanim zaktualizujesz plan, weź pod uwagę te kwestie:

  • Gdy utworzysz subskrypcję, a klient spełni odpowiednie warunki, subskrypcja może skorzystać z 30-dniowego okresu próbnego. Zarówno abonament elastyczny, jak i abonament roczny mogą obejmować 30-dniowe bezpłatne okresy próbne. W okresie próbnym możesz dowolnie często zmieniać abonament na elastyczny lub roczny. Gdy jednak okres próbny dobiegnie końca i abonament stanie się aktywny, zaktualizowanie go będzie odbywać się zgodnie z tymi samymi regułami co w przypadku innych aktywnych abonamentów. Aby natychmiast przenieść subskrypcję próbną na aktywny abonament, rozpocznij płatną usługę z 30-dniowego bezpłatnego okresu próbnego. Więcej informacji o 30-dniowym okresie próbnym i zasadach kwalifikacji klientów znajdziesz w Centrum pomocy dla administratorów.

  • Abonament elastyczny możesz zmienić na abonament z rocznym zobowiązaniem.

  • Nie możesz zaktualizować abonamentu z rocznym zobowiązaniem.

  • Nie wszystkie abonamenty działają ze wszystkimi usługami. Więcej informacji o usługach używanych w tych abonamentach znajdziesz w artykule Usługi i kody SKU.

Aby zmienić plan 30-dniowego okresu próbnego lub abonamentu elastycznego na abonament roczny, użyj tego żądania HTTP POST:

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

Zastąp następujące elementy:

  • CUSTOMER_ID: nazwa domeny podstawowej klienta lub jego unikalny identyfikator.
  • SUBSCRIPTION_ID: unikalny identyfikator subskrypcji dla każdego klienta. Możesz pobrać tę wartość za pomocą metody Pobierz wszystkie subskrypcje sprzedawcy.

Poniższy przykład aktualizuje subskrypcję za pomocą subscriptionId o wartości 123. customerId to C0123456.

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

Treść żądania zawiera:

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

Pomyślna odpowiedź zwraca kod stanu HTTP 201 i zwraca zaktualizowane ustawienia abonamentu:

{
  "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"
}

Aktualizowanie stanowisk w subskrypcji

Aktualizacja abonamentu z rocznym zobowiązaniem wymaga innych właściwości subskrypcji niż w przypadku abonamentu elastycznego Google Workspace.

Aktualizowanie stanowisk w abonamencie rocznym

Aby zaktualizować ustawienia licencji użytkownika abonamentu rocznego, użyj tego żądania HTTP POST:

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

Zastąp następujące elementy:

  • CUSTOMER_ID: nazwa domeny podstawowej klienta lub jego unikalny identyfikator.
  • SUBSCRIPTION_ID: unikalny identyfikator subskrypcji dla każdego klienta. Możesz pobrać tę wartość za pomocą metody Pobierz wszystkie subskrypcje sprzedawcy.

Poniższy przykład aktualizuje subskrypcję przy użyciu 123 subscriptionId. customerId to C0123456. Treść żądania różni się w zależności od typu abonamentu:

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

Subskrypcja Google Workspace z rocznym zobowiązaniem używa tej treści żądania do aktualizowania liczby licencji użytkowników. Wartość numberOfSeats jest sumą. Jeśli na przykład wcześniej było 10 licencji użytkowników, a masz zamówienie klienta na 5 nowych licencji, łączna liczba w treści żądania na numberOfSeats wynosi 15, jak w tym przykładzie:

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

Aktualizowanie stanowisk w abonamencie elastycznym

Abonament elastyczny Google Workspace używa treści żądania do aktualizowania licencji użytkowników. Wartość maximumNumberOfSeats to łączna liczba istniejących i nowych licencji. Jest to maksymalna liczba licencji użytkowników, które może obsłużyć to konto.

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

Pomyślna odpowiedź zwraca kod stanu HTTP 201 i zaktualizowane ustawienia licencji na subskrypcję:

{
  "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"
}

Aktualizowanie ustawień odnawiania subskrypcji

Aby zaktualizować ustawienia odnawiania subskrypcji zobowiązania rocznego, użyj tego żądania HTTP POST:

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

Zastąp następujące elementy:

  • CUSTOMER_ID: nazwa domeny podstawowej klienta lub jego unikalny identyfikator.
  • SUBSCRIPTION_ID: unikalny identyfikator subskrypcji dla każdego klienta. Możesz pobrać tę wartość za pomocą metody Pobierz wszystkie subskrypcje sprzedawcy.

Oto przykładowa treść żądania:

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

Właściwość renewalType może mieć dowolną z tych wartości:

  • AUTO_RENEW_YEARLY_PAY: Na koniec okresu subskrypcji z rocznym zobowiązaniem możesz automatycznie odnowić abonament jako ANNUAL_YEARLY_PAY przy użyciu tego samego numberOfSeats.
  • AUTO_RENEW_MONTHLY_PAY: po zakończeniu okresu trwania abonamentu z rocznym zobowiązaniem automatycznie odnów abonament jako ANNUAL_MONTHLY_PAY z tą samą wartością numberOfSeats.
  • RENEW_CURRENT_USERS_YEARLY_PAY: po zakończeniu okresu obowiązywania abonamentu z rocznym zobowiązaniem odnów abonament jako ANNUAL_YEARLY_PAY, ale wykorzystaj łączną liczbę aktywnych licencji użytkowników aktualnie używanych. Jest to ustawienie domyślne w przypadku aktywnych abonamentów z rocznym zobowiązaniem (płatnych co rok).
  • RENEW_CURRENT_USERS_MONTHLY_PAY: po zakończeniu okresu obowiązywania abonamentu z rocznym zobowiązaniem odnów abonament jako ANNUAL_MONTHLY_PAY, ale wykorzystaj łączną liczbę aktywnych licencji użytkowników aktualnie używanych. Jest to ustawienie domyślne w przypadku aktywnych abonamentów z rocznym zobowiązaniem (płatnych co miesiąc).
  • RENEW_ON_PROPOSED_OFFER: na koniec okresu ważności bieżącego abonamentu odnów odnowienie zgodnie z najnowszą propozycją odnowienia z liczbą aktywnych licencji użytkowników lub proponowanego zobowiązania oferty (w zależności od tego, która wartość jest większa).
  • SWITCH_TO_PAY_AS_YOU_GO: po zakończeniu okresu obowiązywania abonamentu z rocznym zobowiązaniem zmień abonament z rocznym zobowiązaniem na abonament elastyczny.
  • CANCEL: z końcem okresu abonamentu z rocznym zobowiązaniem subskrypcja jest zawieszana. Informacje o tym, jak cofnąć zawieszenie, znajdziesz w Centrum pomocy dla administratorów.

Pomyślna odpowiedź zwraca kod stanu HTTP 201 i zaktualizowane ustawienia odnawiania subskrypcji:

{
  "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"
}

Rozpoczynanie bezpłatnej usługi podczas bezpłatnego okresu próbnego

Aby natychmiast przenieść 30-dniowy bezpłatny okres próbny na subskrypcję płatnej usługi, jeśli abonament próbny został już skonfigurowany, użyj tego żądania HTTP POST. 

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

Zastąp następujące elementy:

  • CUSTOMER_ID: nazwa domeny podstawowej klienta lub jego unikalny identyfikator.
  • SUBSCRIPTION_ID: unikalny identyfikator subskrypcji dla każdego klienta. Możesz pobrać tę wartość za pomocą metody Pobierz wszystkie subskrypcje sprzedawcy.

W tym przykładzie customerId jest wartością C0123456, a subscriptionId – 123:

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

Ta operacja nie zawiera parametrów w treści żądania.

Pomyślna odpowiedź zwraca kod stanu HTTP 201 i zaktualizowane ustawienia subskrypcji:

{
  "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"
}

Przechodzenie na wyższą lub niższą wersję subskrypcji

Nie możesz przejść na mniejszy pakiet roczny w trakcie okresu obowiązywania ani zaplanować zmiany na niższą za pomocą ustawień odnawiania. Zalecamy zmianę ustawień odnowienia na FLEXIBLE, a następnie zmianę na niższą wersję po odnowieniu.

Aby przejść na wyższą lub niższą wersję subskrypcji, utwórz nową subskrypcję z skuId, na którą chcesz przejść.

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

Zastąp następujące elementy:

  • CUSTOMER_ID: nazwa domeny podstawowej klienta lub jego unikalny identyfikator.

To wywołanie zakończy poprzednią subskrypcję i utworzy nową.

Więcej informacji o przechodzeniu na wyższą lub niższą wersję usługi znajdziesz na stronie Usługi i kody SKU.