擷取訂閱項目後,您可以使用成功回應中的資訊來變更訂閱狀態或更新訂閱項目。本頁說明各種擷取及更新訂閱項目的方式。
擷取訂閱
如要擷取訂購或轉移成功的訂閱項目,請使用下列 GET
HTTP 要求。
GET https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID
更改下列內容:
CUSTOMER_ID
:客戶的主網域名稱或客戶的專屬 ID。SUBSCRIPTION_ID
:每個客戶的訂閱 ID。您可以使用擷取所有經銷商訂閱方法來擷取這個值。
這項作業的要求主體中沒有任何參數。
成功的回應會傳回 HTTP 200
狀態碼和訂閱設定。在以下範例回應中,isInTrial
屬性為 false
,但不含 trialEndTime
屬性,表示此客戶從未使用此方案進行 30 天免費試用期。
{
"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"
}
擷取客戶的所有訂閱
如要擷取成功訂購或轉移的特定經銷商客戶訂閱,請使用下列 GET
HTTP 要求並加入授權權杖:
GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=CUSTOMER_ID value&pageToken=START_DATE&maxResults=MAX_NUMBER
更改下列內容:
CUSTOMER_ID
:客戶的主網域名稱或客戶的專屬 ID。START_DATE
:開始日期,格式為YYYY-MM-DD
。MAX_NUMBER
:回應頁面上傳回的結果數量上限。
這項作業的要求主體中沒有任何參數。
成功的回應會傳回 HTTP 200
狀態碼,以及客戶的訂閱和設定清單。訂閱項目清單可能包含未在此版經銷商 API 中管理的產品。
如果您並未管理這位客戶,系統會傳回 403 "Forbidden"
錯誤。
擷取客戶可轉移的所有訂閱
如要擷取客戶可能轉移至經銷商管理的所有訂閱項目,請使用下列 GET
HTTP 要求,並加入授權權杖。customerId
是必要項,也是擷取經銷商客戶帳戶時傳回的客戶專屬 ID。customerAuthToken
是客戶提供的轉移憑證,專屬於您的經銷商 ID。客戶產生後,有效期限為 30 天。如要進一步瞭解客戶如何產生權杖,請參閱「將 Google Workspace 帳戶轉移給經銷商」。
GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=CUSTOMER_ID&customerAuthToken=AUTH_TOKEN&pageToken=START_DATE&maxResults=MAX_NUMBER
更改下列內容:
CUSTOMER_ID
:客戶的主網域名稱或客戶的專屬 ID。AUTH_TOKEN
:客戶提供的經銷商 ID 專屬轉移憑證。客戶產生後,有效期限為 30 天。如要進一步瞭解客戶如何產生權杖,請參閱「將 Google Workspace 帳戶轉移給經銷商」一文。如果這個值無效或已過期,API 回應會傳回403 "Forbidden"
錯誤。START_DATE
:開始日期,格式為YYYY-MM-DD
。MAX_NUMBER
:回應頁面上傳回的結果數量上限。
這項作業的要求主體中沒有任何參數。
成功的回應會傳回 HTTP 200
狀態碼,以及客戶可轉移的訂閱項目清單,其中包含轉移權杖的到期日,以及轉移訂單中所需的最低帳戶名額。客戶可能擁有無法轉移的其他訂閱。
{
"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"
}
如果打算利用批次作業來轉移這些訂閱項目,請轉移所有訂閱項目。逐一轉移各個訂閱項目會導致錯誤。此外,批次作業只會轉移狀態為 ACTIVE
的訂閱項目。詳情請參閱「轉移訂閱項目」一文。
擷取所有經銷商訂閱
如要擷取經銷商成功訂購或轉移的所有訂閱項目,請使用下列 GET
HTTP 要求並加入授權權杖。
GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=PREFIX &pageToken=TOKEN&maxResults=MAX_NUMBER
更改下列內容:
PREFIX
:所需訂閱項目的客戶名稱開頭。TOKEN
:識別伺服器應傳回特定結果頁面的符記。MAX_NUMBER
:回應頁面上傳回的結果數量上限。
這項作業可以使用 OAuth 唯讀存取權範圍。customerNamePrefix
、pageToken
和 maxResults
是選用查詢字串。
以下範例會擷取名稱開頭為「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"
}
更新訂閱方案
Google Workspace 方案的更新方式因方案而異。更新方案之前,請考量以下事項:
當您建立訂閱項目且客戶符合資格時,訂閱方案可以試用 30 天。彈性和年約付款方案都可以提供 30 天的免費試用期。在試用期間,您可以視需要將訂閱項目的付款方案變更為彈性或年約方案。不過在試用期結束且方案生效後,請按照與其他訂閱項目有效方案相同的規則更新方案。如要立即將試用訂閱項目移至使用中的方案,請從 30 天免費試用的訂閱方案開始啟用付費服務。如要進一步瞭解 30 天試用資訊和客戶資格規則,請參閱管理說明中心。
您可以將彈性方案更新為年約方案。
您無法更新年約方案。
並非所有方案都支援所有產品。如要進一步瞭解這些方案使用的產品,請參閱產品與 SKU。
如要將 30 天試用方案或彈性方案訂閱方案更新為年約方案,請使用下列 POST
HTTP 要求:
POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changePlan
更改下列內容:
CUSTOMER_ID
:客戶的主網域名稱或客戶的專屬 ID。SUBSCRIPTION_ID
:每個客戶的訂閱 ID。您可以使用擷取所有經銷商訂閱方法來擷取這個值。
以下範例將訂閱 subscriptionId
的值更新為 123。customerId
為 C0123456。
POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/changePlan
要求主體包含下列內容:
{
"kind": "reseller#changePlanRequest",
"planName": "ANNUAL_MONTHLY_PAY",
"seats": {
"kind": "subscriptions#seats",
"numberOfSeats": 10
},
"purchaseOrderId": "123_March2012"
}
成功的回應會傳回 HTTP 201
狀態碼,並傳回更新後的訂閱方案設定:
{
"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"
}
更新訂閱項目的座位
更新年約方案訂閱項目所用的訂閱屬性,與更新 Google Workspace 彈性方案訂閱項目不同。
更新年約方案訂閱方案的帳戶名額
如要更新年約方案訂閱項目的使用者授權設定,請使用下列 POST
HTTP 要求:
POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changeSeats
更改下列內容:
CUSTOMER_ID
:客戶的主網域名稱或客戶的專屬 ID。SUBSCRIPTION_ID
:每個客戶的訂閱 ID。您可以使用擷取所有經銷商訂閱方法來擷取這個值。
以下範例將訂閱項目更新為 123 subscriptionId
。customerId
為 C0123456。要求的主體會因方案類型而不同:
POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/changeSeats
Google Workspace 年約方案的訂閱項目會使用此要求主體來更新使用者授權數量。numberOfSeats
值為總計。例如,假設您先前有 10 個使用者授權,且客戶訂單包含 5 個新授權,則 numberOfSeats
的要求主體中的總數為 15 個,如以下範例所示:
{
"kind": "subscriptions#seats",
"numberOfSeats": 15
}
為彈性方案訂閱項目更新帳戶名額
Google Workspace 彈性方案的訂閱項目會使用要求主體更新使用者授權。maximumNumberOfSeats
值是現有授權與新授權的總數。這是帳戶可佈建的使用者授權數量上限。
{
"kind": "subscriptions#seats",
"maximumNumberOfSeats": 15
}
成功的回應會傳回 HTTP 201
狀態碼,以及更新後的訂閱授權設定:
{
"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"
}
更新訂閱項目的續約設定
如要更新年約訂閱項目的續訂設定,請使用下列 POST
HTTP 要求:
POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changeRenewalSettings
更改下列內容:
CUSTOMER_ID
:客戶的主網域名稱或客戶的專屬 ID。SUBSCRIPTION_ID
:每個客戶的訂閱 ID。您可以使用擷取所有經銷商訂閱方法來擷取這個值。
以下是要求主體的範例:
{
"kind": "subscriptions#renewalSettings",
"renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
}
renewalType
屬性的值可以是下列任一值:
AUTO_RENEW_YEARLY_PAY
:合約方案的間隔時間結束時,會以相同的numberOfSeats
自動以ANNUAL_YEARLY_PAY
的形式續訂訂閱項目的方案。AUTO_RENEW_MONTHLY_PAY
:年約方案間隔結束時,會以相同的numberOfSeats
自動以ANNUAL_MONTHLY_PAY
的形式續訂訂閱的方案。RENEW_CURRENT_USERS_YEARLY_PAY
:在年約方案的間隔結束後,請以ANNUAL_YEARLY_PAY
的形式續訂訂閱項目的方案,但使用目前活躍使用者授權總數。這是有效年約方案的預設設定 (按年付款)。RENEW_CURRENT_USERS_MONTHLY_PAY
:在年約方案的間隔結束後,請以ANNUAL_MONTHLY_PAY
的形式續訂訂閱項目的方案,但使用目前活躍使用者授權總數。這是有效年約方案的預設設定 (按月付款)。RENEW_ON_PROPOSED_OFFER
:在目前合約方案的間隔時間結束時,按照目前的有效使用者授權數或提議的優惠合約數量 (以較高者為準) 依據最新的續約提案進行續約。SWITCH_TO_PAY_AS_YOU_GO
:在年約方案的間隔時間結束時,將年約方案變更為彈性方案。CANCEL
:年約方案間隔結束時,訂閱項目會遭到停權。如要瞭解如何解除停權狀態,請參閱管理說明中心。
成功的回應會傳回 HTTP 201
狀態碼,以及更新後的訂閱項目續訂設定:
{
"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"
}
從免費試用訂閱方案開始使用付費服務
如果已為試用訂閱項目設定付款方案,如要立即將 30 天免費試用訂閱項目轉移至付費服務訂閱項目,請使用下列 POST
HTTP 要求。
POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/startPaidService
更改下列內容:
CUSTOMER_ID
:客戶的主網域名稱或客戶的專屬 ID。SUBSCRIPTION_ID
:每個客戶的訂閱 ID。您可以使用擷取所有經銷商訂閱方法來擷取這個值。
以下範例將 C0123456 做為 customerId
,subscriptionId
值為 123:
POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/startPaidService
這項作業的要求主體中沒有任何參數。
成功的回應會傳回 HTTP 201
狀態碼和更新後的訂閱設定:
{
"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"
}
將訂閱項目升級或降級
您無法在約期中開始降級,也不能使用續約設定安排降級時間。建議您將續約設定調整為 FLEXIBLE
,然後在續約後降級。
如要升級或降級訂閱項目,請使用您要升級或降級的 skuId
建立新訂閱項目。
POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions
更改下列內容:
CUSTOMER_ID
:客戶的主網域名稱或客戶的專屬 ID。
這項呼叫會終止先前的訂閱項目,並建立新訂閱項目。
如要進一步瞭解升級與降級,請前往「Product & SKU」頁面。