Pobieranie i aktualizowanie subskrypcji

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

Pobieranie subskrypcji

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

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 unikalny identyfikator klienta.
  • SUBSCRIPTION_ID: unikalny identyfikator subskrypcji dla każdego klienta. Aby pobrać tę wartość, użyj 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 nie ma usługi 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 unikalny identyfikator klienta.
  • START_DATE: data rozpoczęcia w formacie YYYY-MM-DD.
  • MAX_NUMBER: maksymalna liczba wyników zwracanych na stronie 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".

Pobierz wszystkie subskrypcje klienta, które można przenieść

Aby pobrać wszystkie subskrypcje klienta, które mogą być przeniesione do systemu zarządzania sprzedawcy, użyj poniższego żądania HTTP GET i dołącz token autoryzacji. Parametr customerId jest wymagany. Jest to unikalny identyfikator klienta zwracany podczas pobierania konta klienta sprzedawcy. customerAuthToken to udostępniony przez klienta token przeniesienia, który jest powiązany z Twoim identyfikatorem 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 unikalny identyfikator klienta.
  • AUTH_TOKEN: udostępniony przez klienta token przeniesienia, który jest powiązany z Twoim identyfikatorem sprzedawcy. Po wygenerowaniu przez klienta jest ona 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 zwracanych na stronie 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 zamówieniu transferu. 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 zamierzasz przenieść te subskrypcje przy użyciu operacji zbiorczej, przenieś wszystkie subskrypcje. Przenoszenie subskrypcji pojedynczo kończy się błędem. Oprócz tego operacja wsadowa przenosi tylko subskrypcje o stanie ACTIVE. Więcej informacji znajdziesz w artykule Przenoszenie subskrypcji.

Pobierz wszystkie subskrypcje sprzedawcy

Aby pobrać wszystkie subskrypcje zamówione lub przeniesione przez sprzedawcę, 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 konkretną stronę wyników, którą powinien zwrócić serwer.
  • MAX_NUMBER: maksymalna liczba wyników zwracanych na stronie odpowiedzi.

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

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

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

Aktualizowanie abonamentu

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

  • Jeśli utworzysz subskrypcję, a klient spełni odpowiednie warunki, subskrypcja może być dostępna w 30-dniowym okresie próbnym. Zarówno abonament elastyczny, jak i roczny, mogą obejmować 30-dniowe bezpłatne okresy próbne. W trakcie okresu próbnego możesz w dowolnej chwili zmienić abonament na elastyczny lub roczny. Jednak po zakończeniu okresu próbnego, gdy abonament stanie się aktywny, aktualizowanie abonamentu 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 reguł kwalifikacji klientów znajdziesz w Centrum pomocy dla administratorów.

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

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

  • Nie wszystkie abonamenty są obsługiwane we wszystkich usługach. Więcej informacji o usługach używanych w tych abonamentach znajdziesz w artykule Produkty i kody SKU.

Aby zaktualizować 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 unikalny identyfikator klienta.
  • SUBSCRIPTION_ID: unikalny identyfikator subskrypcji dla każdego klienta. Aby pobrać tę wartość, użyj metody Pobierz wszystkie subskrypcje sprzedawcy.

Ten 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

Aktualizowanie abonamentu z rocznym zobowiązaniem korzysta z 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 unikalny identyfikator klienta.
  • SUBSCRIPTION_ID: unikalny identyfikator subskrypcji dla każdego klienta. Aby pobrać tę wartość, użyj metody Pobierz wszystkie subskrypcje sprzedawcy.

Ten przykład aktualizuje subskrypcję przy użyciu polecenia subscriptionId 123. customerId to C0123456. Treść prośby różni się w zależności od typu abonamentu:

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

Subskrypcja abonamentu rocznego Google Workspace wykorzystuje tę treść żą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 i złożono zamówienie na 5 nowych licencji, łączna liczba licencji na numberOfSeats w treści żądania wynosi 15, jak widać w tym przykładzie:

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

Aktualizowanie stanowisk w abonamencie elastycznym

Abonament elastyczny Google Workspace wykorzystuje treść żą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"
}

Zaktualizuj ustawienia 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 unikalny identyfikator klienta.
  • SUBSCRIPTION_ID: unikalny identyfikator subskrypcji dla każdego klienta. Aby pobrać tę wartość, użyj 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 zobowiązania z rocznym zobowiązaniem możesz automatycznie odnowić abonament jako ANNUAL_YEARLY_PAY z takim samym abonamentem 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 trwania abonamentu z rocznym zobowiązaniem odnów abonament jako ANNUAL_YEARLY_PAY, ale wykorzystaj łączną liczbę aktywnych licencji użytkowników. Jest to domyślne ustawienie w przypadku aktywnych abonamentów z rocznym zobowiązaniem (płatnych co rok).
  • RENEW_CURRENT_USERS_MONTHLY_PAY: po zakończeniu okresu trwania abonamentu z rocznym zobowiązaniem odnów abonament jako ANNUAL_MONTHLY_PAY, ale wykorzystaj łączną liczbę aktywnych licencji użytkowników. Jest to domyślne ustawienie w przypadku aktywnych abonamentów z rocznym zobowiązaniem (płatnych co miesiąc).
  • RENEW_ON_PROPOSED_OFFER: pod koniec okresu trwania bieżącego abonamentu zobowiązania odnów zgodnie z najnowszą propozycją odnowienia z liczbą aktywnych licencji użytkowników (numberOfSeats) lub proponowanym zobowiązaniem oferty (w zależności od tego, która liczba jest większa).
  • SWITCH_TO_PAY_AS_YOU_GO: po zakończeniu okresu obowiązywania abonamentu rocznego zmień abonament z rocznym na abonament elastyczny.
  • CANCEL: z końcem okresu trwania abonamentu rocznego subskrypcja jest zawieszana. Informacje o tym, jak cofnąć zawieszenie konta, 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 płatnej usługi od bezpłatnego okresu próbnego

Aby natychmiast przenieść 30-dniową bezpłatną subskrypcję próbną na subskrypcję usługi płatnej, jeśli dla subskrypcji próbnej został już skonfigurowany abonament, 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 unikalny identyfikator klienta.
  • SUBSCRIPTION_ID: unikalny identyfikator subskrypcji dla każdego klienta. Aby pobrać tę wartość, użyj metody Pobierz wszystkie subskrypcje sprzedawcy.

W tym przykładzie podano C0123456 jako customerId i wartość 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 niższą wersję abonamentu rocznego w trakcie okresu zobowiązania ani zaplanować przejścia na niższą wersję w ustawieniach odnawiania. Zalecamy zmianę ustawień odnawiania na FLEXIBLE, a po zakończeniu odnowienia – zmianę na starszą wersję.

Aby przejść na wyższą lub niższą wersję subskrypcji, utwórz nową subskrypcję z usługą 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 unikalny identyfikator klienta.

To połączenie zakończy poprzednią subskrypcję i utworzy nową.

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