變更使用者訂閱的帳單狀態

  • 發行項

在 Microsoft Store 中使用此方法購買 API 來變更特定使用者的訂用帳戶附加元件計費狀態。 您可以取消、延長、退款或停用訂用帳戶的自動更新。

注意

這個方法只能由 Microsoft 佈建的開發人員帳戶使用，才能為通用 Windows 平台 (UWP) 應用程式建立訂用帳戶附加元件。 訂用帳戶附加元件目前不提供大多數開發人員帳戶使用。

Microsoft.StoreServices 程式庫透過 StoreServicesClient.RecurrenceChangeAysnc API 提供此方法的功能。

必要條件

若要使用此方法，您將需要：

  • Azure AD 存取權杖，具有對象 URI 值 https://onestore.microsoft.com。
  • Microsoft Store 識別碼金鑰，代表具有您想要變更之訂用帳戶權利的使用者身分識別。

如需詳細資訊，請參閱從服務管理產品權利。

要求

要求語法

方法 要求 URI
POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change

要求標頭

標題 類型 描述
授權 字串 必要。 持有人<權杖>形式的 Azure AD 存取權杖。
Host 字串 必須設定為值 purchase.mp.microsoft.com。
Content-Length 值 要求本文的長度。
內容-類型 字串 指定要求和回應類型。 目前唯一支援的值是 application/json。

要求參數

名稱 類型​​ 描述 必要
recurrenceId 字串 要變更的訂用帳戶識別碼。 若要取得此識別碼，請呼叫取得使用者訂用帳戶方法，識別代表您要變更之訂用帳戶附加元件的回應本文項目，並使用項目的 id 功能變數的值。 是

要求本文

功能變數 類型 描述 必要
b2bKey 字串 Microsoft Store 識別碼金鑰，代表您要變更其訂用帳戶的使用者身分識別。 是
changeType 字串 下列其中一個字串，可識別您想要進行的變更類型：
  • Cancel：取消訂閱。
  • Extend：延長訂用帳戶。 如果您指定此值，必須同時包含 extensionTimeInDays 參數。
  • Refund：提供訂用帳戶退款給客戶。
  • ToggleAutoRenew：停用訂用帳戶的自動更新。 如果訂用帳戶目前停用自動更新，則此值不會執行任何動作。
 是
extensionTimeInDays 字串 如果 changeType 參數具有 Extend 值，此參數會指定延長訂閱的天數。 是，如果 changeType 具有 Extend 值，否則為否。

要求範例

下列範例示範如何使用此方法將訂用帳戶期間延長 5 天。 將 b2bKey 值取代為代表您要變更其訂用帳戶之使用者身分識別的 Microsoft Store 識別碼金鑰。

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac/change HTTP/1.1
Authorization: Bearer <your access token>
Content-Type: application/json
Host: https://purchase.mp.microsoft.com

{
  "b2bKey":  "eyJ0eXAiOiJ...",
  "changeType": "Extend",
  "extensionTimeInDays": "5"
}

回應

這個方法會傳回 JSON 回應本文，其中包含已修改之訂用帳戶附加元件的相關資訊，包括任何已修改的功能變數。 下列範例示範此方法的回應本文。

{
  "items": [
    {
      "autoRenew":true,
      "beneficiary":"pub:gFVuEBiZHPXonkYvtdOi+tLE2h4g2Ss0ZId0RQOwzDg=",
      "expirationTime":"2017-06-16T03:07:49.2552941+00:00",
      "id":"mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac",
      "lastModified":"2017-01-10T21:08:13.1459644+00:00",
      "market":"US",
      "productId":"9NBLGGH52Q8X",
      "skuId":"0024",
      "startTime":"2017-01-10T21:07:49.2552941+00:00",
      "recurrenceState":"Active"
    }
  ]
}

回應本文

此回應本文包含下列資料。

值 類型 描述
autoRenew 布林值 指出訂用帳戶是否設定為在目前訂用帳戶期間結束時自動更新。
beneficiary 字串 與此訂用帳戶相關聯之權利受益者的識別碼。
expirationTime 字串 訂用帳戶到期的日期和時間，格式為 ISO 8601。 只有在訂用帳戶處於特定狀態時，才能使用此欄位。 到期時間通常表示目前狀態何時到期。 例如，對於作用中的訂用帳戶，到期日會指出下一次自動更新會在何時發生。
expirationTimeWithGrace 字串 訂用帳戶到期的日期和時間，包括 ISO 8601 格式的寬限期。 這個值表示使用者在訂用帳戶無法自動更新之後，何時會失去訂用帳戶的存取權。
id 字串 訂用帳戶的識別碼。 使用此值來指出當您呼叫變更使用者的訂用帳戶計費狀態方法時，想要修改的訂用帳戶。
isTrial 布林值 指出訂用帳戶是否為試用版。
lastModified 字串 上次修改訂閱的日期和時間，格式為 ISO 8601。
market 字串 使用者取得訂用帳戶的國家/地區代碼 (兩個字母的 ISO 3166-1 alpha-2 格式)。
productId 字串 代表 Microsoft Store 目錄中訂用帳戶附加元件之產品的 Store ID。 產品的範例 Store ID 為 9NBLGGH42CFD。
skuId 字串 代表 Microsoft Store 目錄中訂用帳戶附加元件之 SKU 的 Store ID。 SKU 的範例 Store ID 為 0010。
startTime 字串 訂閱的開始日期和時間，格式為 ISO 8601。
recurrenceState 字串 下列其中一個值：
  • None：這表示永久訂用帳戶。
  • Active：訂用帳戶為作用中，且使用者有權使用服務。
  • Inactive：訂用帳戶已超過到期日，且使用者已關閉訂用帳戶的自動更新選項。
  • Canceled：訂用帳戶在到期日之前在有無退款下特意終止。
  • InDunning：訂用帳戶處於「催繳」狀態 (也就是訂用帳戶即將到期，而 Microsoft 正嘗試取得資金以自動更新訂用帳戶)。
  • Failed：催繳期間已結束，訂用帳戶在多次嘗試之後無法續約。

注意：

  • Inactive/Canceled/Failed 是末期狀態。 當訂用帳戶進入其中一個狀態時，使用者必須重新購買訂用帳戶，才能再次啟用訂閱。 使用者在這些狀態下無權使用服務。
  • 當訂用帳戶為 Canceled 時，expirationTime 會以取消的日期和時間進行更新。
  • 訂用帳戶的識別碼在整個存留期內會維持不變。 如果自動更新選項已開啟或關閉，則不會變更。 如果使用者在達到末期狀態之後重新購買訂用帳戶，將會建立新的訂用帳戶識別碼。
  • 應將訂用帳戶的識別碼用在個別訂用帳戶上執行任何作業。
  • 當使用者在取消或停止之後重新購買訂用帳戶時，如果您查詢使用者的結果，您會收到兩個項目：一個是處於末期狀態的舊訂用帳戶識別碼，另一個是處於作用中狀態的新訂用帳戶識別碼。
  • 檢查 recurrenceState 和 expirationTime 向來是個不錯的做法，因為 recurrenceState 可能會延遲幾分鐘 (或偶爾數小時) 更新。
cancellationDate 字串 取消使用者的訂閱日期和時間 (ISO 8601 格式)。