Pobieranie i aktualizowanie subskrypcji

Po pobraniu subskrypcji możesz użyć informacji z odpowiedzi na żądanie, aby zmienić stan subskrypcji lub zaktualizować subskrypcję. Na tej stronie omawiamy różne sposoby pobierania i aktualizowania subskrypcji.

Pobieranie subskrypcji

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

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: identyfikator subskrypcji, który jest unikalny dla każdego klienta. Możesz pobrać tę wartość, korzystając z metody pobierania wszystkich subskrypcji sprzedawcy.

Ta operacja nie ma parametrów w ciele żądania.

Pomyślna odpowiedź zwraca kod stanu HTTP 200 oraz ustawienia subskrypcji. W tym przykładowym komunikacie odpowiedź na pytanie isInTrial to false, ale nie ma odpowiedzi na pytanie trialEndTime, co oznacza, że 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 będącego resellerem, 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 zwracanych na stronie odpowiedzi.

Ta operacja nie ma parametrów w ciele żądania.

Pomyślna odpowiedź zwraca kod stanu HTTP 200 oraz listę subskrypcji i ustawień klienta. Lista subskrypcji może zawierać produkty, którymi nie zarządza się w tej wersji interfejsu Reseller API.

Jeśli nie zarządzasz tym klientem, zwracany jest błąd 403 "Forbidden".

Pobieranie wszystkich subskrypcji możliwych do przeniesienia dla klienta

Aby pobrać wszystkie subskrypcje klienta, które można przenieść do zarządzania przez resellera, użyj tego żądania HTTP GET i dołącz token autoryzacji. Argument customerId jest wymagany i jest unikalnym identyfikatorem klienta zwracanym podczas pobierania konta klienta sprzedawcy. customerAuthToken to token przeniesienia dostarczony przez klienta, który jest powiązany z Twoim identyfikatorem sprzedawcy. Po wygenerowaniu przez klienta jest ona ważna przez 30 dni. Więcej informacji o tym, jak klienci generują token, 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 podany przez klienta, który jest powiązany z Twoim identyfikatorem sprzedawcy. Po wygenerowaniu przez klienta jest ona ważna przez 30 dni. Więcej informacji o tym, jak klienci generują token, znajdziesz w artykule Przenoszenie konta Google Workspace do sprzedawcy. Jeśli ta wartość jest nieprawidłowa lub jej ważność 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 ma parametrów w ciele żądania.

Pomyślna odpowiedź zwraca kod stanu HTTP 200 oraz listę abonamentów klienta, które można przenieść, z datą wygaśnięcia tokena przeniesienia i minimalną liczbą miejsc potrzebnych w zamówieniu 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 za pomocą operacji zbiorczej, przenieś wszystkie subskrypcje. Przenoszenie każdej subskrypcji osobno spowoduje błąd. Ponadto operacja zbiorcza przenosi tylko subskrypcje ze stanem ACTIVE. Więcej informacji znajdziesz w artykule Przenoszenie subskrypcji.

Pobieranie wszystkich subskrypcji sprzedawców

Aby pobrać wszystkie subskrypcje zamówione lub przeniesione przez resellera, użyj tego żą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 nazwiska klienta, którego subskrypcje chcesz znaleźć.
  • TOKEN: token identyfikujący konkretną stronę wyników, którą serwer powinien zwrócić.
  • MAX_NUMBER: maksymalna liczba wyników zwracanych na stronie odpowiedzi.

Ta operacja może używać zakresu dostępu OAuth tylko do odczytu. Parametry customerNamePrefix, pageToken i maxResults to opcjonalne ciągi zapytań.

W tym przykładzie pobierane są wszystkie subskrypcje sprzedawcy należące do klientów, których nazwy zaczynają 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"
}

Aktualizowanie abonamentu

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

  • Gdy tworzysz subskrypcję i klient spełnia wymagania, abonament może mieć 30-dniowy okres próbny. Zarówno abonamenty elastyczne, jak i abonamenty z rocznym zobowiązaniem mogą mieć 30-dniowy bezpłatny okres próbny. W trakcie okresu próbnego możesz zmienić abonament na elastyczny lub roczny w dowolnym momencie. Po zakończeniu okresu próbnego i aktywowaniu abonamentu aktualizacja abonamentu podlega tym samym zasadom co inne aktywne abonamenty. Aby natychmiast przejść z abonamentu próbnego na aktywny, uruchom 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.

  • Możesz zaktualizować abonament elastyczny do abonamentu rocznego.

  • Nie możesz zaktualizować abonamentu rocznego.

  • Nie wszystkie abonamenty działają z wszystkimi usługami. Więcej informacji o tym, które produkty są używane w ramach tych planów, znajdziesz w sekcji Produkty i SKU.

Aby zaktualizować subskrypcję próbną na 30 dni lub abonament elastyczny na abonament z rocznym zobowiązaniem, wyślij to żądanie 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: identyfikator subskrypcji, który jest unikalny dla każdego klienta. Możesz pobrać tę wartość, korzystając z metody pobierania wszystkich subskrypcji sprzedawcy.

W tym przykładzie subskrypcja jest aktualizowana za pomocą elementu subscriptionId o wartości 123. Wartość 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"
}

W przypadku pomyślnej odpowiedzi zwracany jest kod stanu HTTP 201 i 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"
}

Zmiana liczby stanowisk w ramach subskrypcji

Aktualizacja subskrypcji abonamentu rocznego wymaga użycia innych właściwości subskrypcji niż aktualizacja subskrypcji abonamentu elastycznego Google Workspace.

Aktualizowanie liczby miejsc w przypadku subskrypcji rocznej

Aby zaktualizować ustawienia licencji użytkownika w subskrypcji rocznej, wyślij to POSTżądanie HTTP:

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: identyfikator subskrypcji, który jest unikalny dla każdego klienta. Możesz pobrać tę wartość, korzystając z metody Pobieranie wszystkich subskrypcji sprzedawcy.

W tym przykładzie subskrypcja jest aktualizowana za pomocą wartości 123 subscriptionId. Wartość parametru 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 abonamentu rocznego Google Workspace używa tego tekstu żądania do aktualizowania liczby licencji użytkownika. Wartość numberOfSeats to łączna suma. Jeśli na przykład wcześniej miałeś 10 licencji na użytkownika, a klient zamówił 5 nowych licencji, łączna liczba licencji w ciele żądania numberOfSeats wyniesie 15, jak pokazano w tym przykładzie:

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

Zmiana liczby stanowisk w przypadku subskrypcji abonamentu elastycznego

Subskrypcja abonamentu elastycznego Google Workspace używa treści żądania do aktualizowania licencji użytkowników. Wartość maximumNumberOfSeats to łączna liczba istniejących i nowych licencji. To maksymalna liczba licencji użytkownika, które można przypisać do konta.

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

W odpowiedzi na pomyślne wywołanie zwracany jest kod stanu HTTP 201 oraz zaktualizowane ustawienia licencji subskrypcji:

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

Zmiana ustawień odnawiania subskrypcji

Aby zaktualizować ustawienia odnowienia subskrypcji z rocznym zobowiązaniem, użyj tego POST żądania HTTP:

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: identyfikator subskrypcji, który jest unikalny dla każdego klienta. Możesz pobrać tę wartość, używając metody Pobieranie wszystkich subskrypcji sprzedawcy.

Poniżej znajdziesz przykładową treść żądania:

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

Wartość właściwości renewalType może być dowolna:

  • AUTO_RENEW_YEARLY_PAY: na koniec okresu abonamentu rocznego automatycznie odnowi subskrypcję jako ANNUAL_YEARLY_PAY z tą samą numberOfSeats.
  • AUTO_RENEW_MONTHLY_PAY: pod koniec okresu obowiązywania rocznego abonamentu automatycznie odnawiaj abonamenty jako ANNUAL_MONTHLY_PAY z tymi samymi numberOfSeats.
  • RENEW_CURRENT_USERS_YEARLY_PAY: na koniec okresu rocznego zobowiązania odnów abonament jako ANNUAL_YEARLY_PAY, ale użyj łącznej liczby aktywnych licencji użytkowników. Jest to domyślne ustawienie aktywnego abonamentu rocznego (płatnego co roku).
  • RENEW_CURRENT_USERS_MONTHLY_PAY: na koniec okresu rocznego zobowiązania odnów abonament jako ANNUAL_MONTHLY_PAY, ale użyj łącznej liczby aktywnych licencji użytkowników. Jest to domyślne ustawienie dla aktywnych abonamentów rocznych (płatnych co miesiąc).
  • RENEW_ON_PROPOSED_OFFER: pod koniec okresu obowiązywania bieżącego planu zobowiązań odnów go na podstawie najnowszej oferty odnowienia, w której liczba miejsc odpowiada liczbie aktywnych licencji użytkowników lub proponowanego zobowiązania oferty, zależnie od tego, która z tych wartości jest większa.
  • SWITCH_TO_PAY_AS_YOU_GO: na koniec okresu obowiązywania abonamentu rocznego z zobowiązaniem zmień abonament roczny z zobowiązaniem na abonament elastyczny.
  • CANCEL: po zakończeniu okresu zobowiązania subskrypcja zostaje zawieszona. Informacje o tym, jak cofnąć zawieszenie, znajdziesz w Centrum pomocy.

W odpowiedzi na pomyślne wywołanie zwracany jest kod stanu HTTP 201 oraz 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 z bezpłatnej subskrypcji próbnej

Aby natychmiast przejść z 30-dniowego bezpłatnego okresu próbnego na płatną subskrypcję, jeśli abonament próbny jest 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: identyfikator subskrypcji, który jest unikalny dla każdego klienta. Możesz pobrać tę wartość, korzystając z metody pobierania wszystkich subskrypcji sprzedawcy.

W tym przykładzie customerId ma wartość C0123456, a wartość subscriptionId to 123:

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

Ta operacja nie ma parametrów w ciele żądania.

W odpowiedzi na pomyślne działanie zwracany jest 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 jego trwania ani zaplanować przejścia na niższą wersję, korzystając z ustawień odnowienia. Zalecamy ustawienie opcji odnowienia na przełączenie na FLEXIBLE, a potem na obniżenie jakości po upływie czasu odnowienia.

Aby przejść na wyższą lub niższą wersję subskrypcji, utwórz nową subskrypcję z skuId, do której 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 kończy poprzednią subskrypcję i tworzy nową.

Więcej informacji o uaktualnieniach i obniżeniach poziomu znajdziesz na stronie Produkty i SKU.