變更使用者訂閱的帳單狀態Change the billing state of a subscription for a user

在 Microsoft Store 購買 API 中使用此方法,變更特定使用者訂閱附加元件的帳單狀態。Use this method in the Microsoft Store purchase API to change the billing state of a subscription add-on for a given user. 您可以取消、延長、退款或停用訂閱的自動續約。You can cancel, extend, refund, or disable automatic renewal for a subscription.

注意

Microsoft 佈建的開發人員帳戶才可以使用此方法,建立通用 Windows 平台 (UWP) 應用程式的訂閱附加元件。This method can only be used by developer accounts that have been provisioned by Microsoft to be able to create subscription add-ons for Universal Windows Platform (UWP) apps. 訂閱附加元件目前並未提供給大部分開發人員帳戶使用。Subscription add-ons are currently not available to most developer accounts.

必要條件Prerequisites

若要使用這個方法,您將需要:To use this method, you will need:

  • 一個具有對象 URI 值 https://onestore.microsoft.com 的 Azure AD 存取權杖。An Azure AD access token that has the audience URI value https://onestore.microsoft.com.
  • Microsoft Store 識別碼金鑰,表示使用者的身分識別,他有您想要變更之訂閱的權利。A Microsoft Store ID key that represents the identity of the user who has an entitlement to the subscription you want to change.

如需詳細資訊,請查看管理服務的產品權利For more information, see Manage product entitlements from a service.

要求Request

要求的語法Request syntax

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

要求的標頭Request header

標頭Header 類型Type 描述Description
AuthorizationAuthorization 字串string 必要。Required. 在表單中的 Azure AD 存取權杖持有人 <語彙基元>。The Azure AD access token in the form Bearer <token>.
主機Host 字串string 其值必須設定為 purchase.mp.microsoft.comMust be set to the value purchase.mp.microsoft.com.
Content-LengthContent-Length 數字number 要求主體的長度。The length of the request body.
Content-TypeContent-Type 字串string 指定要求及回應類型。Specifies the request and response type. 目前唯一支援的值為 application/jsonCurrently, the only supported value is application/json.

要求參數Request parameters

名稱Name 類型Type 描述Description 必要Required
recurrenceIdrecurrenceId 字串string 您想要變更之訂閱的識別碼。The ID of the subscription you want to change. 若要取得這個識別碼,請呼叫取得使用者的訂用帳戶方法中,找出代表您想要變更的訂用帳戶附加元件的回應內文項目,並使用值識別碼欄位的項目。To get this ID, call the get subscriptions for a user method, identify the response body entry that represents the subscription add-on you want to change, and use the value of the id field for the entry. Yes

要求本文Request body

欄位Field 類型Type 描述Description 必要Required
b2bKeyb2bKey 字串string Microsoft Store 識別碼金鑰,代表您要變更其訂閱的使用者身分識別。The Microsoft Store ID key that represents the identity of the user whose subscription you want to change. Yes
changeTypechangeType 字串string 下列其中一個字串,辨識您想要進行的變更類型:One of the following strings that identifies the type of change you want to make:
  • 取消:取消訂用帳戶。Cancel: Cancels the subscription.
  • 擴充:擴充的訂用帳戶。Extend: Extends the subscription. 如果您指定這個值,必須也包含 extensionTimeInDays 參數。If you specify this value, you must also include the extensionTimeInDays parameter.
  • 退還:退款給客戶的訂用帳戶。Refund: Refunds the subscription to the customer.
  • ToggleAutoRenew:停用自動續約訂用帳戶。ToggleAutoRenew: Disables automatic renewal for the subscription. 如果訂閱目前已停用自動續約,這個值不會執行任何動作。If automatic renewal is currently disabled for the subscription, this value does nothing.
Yes
extensionTimeInDaysextensionTimeInDays 字串string 如果 changeType 參數有值 Extend,此參數指定延長訂閱的天數。If the changeType parameter has the value Extend, this parameter specifies the number of days to extend the subscription. 如果 changeType 有值 Extend 則為「是」,否則為「否」。Yes, if changeType has the value Extend; otherwise, no.

要求範例Request example

以下範例示範如何使用此方法,將訂閱期間延長 5 天。The following example demonstrates how to use this method to extend the subscription period by 5 days. 使用值 Microsoft Store 識別碼金鑰 (代表您要變更其訂閱的使用者身分識別) 取代 b2bKeyReplace the b2bKey value with the Microsoft Store ID key that represents the identity of the user whose subscription you want to change.

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

回應Response

這個方法會傳回 JSON 回應主體,包含已修改訂閱附加元件的相關資訊,包括任何已修改的欄位。This method returns a JSON response body that contains information about the subscription add-on that was modified, including any fields that were modified. 以下範例示範這個方法的回應主體。The following example demonstrates a response body for this method.

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

回應主體Response body

回應主體包含下列資料。The response body contains the following data.

Value 類型Type 描述Description
autoRenewautoRenew 布林值Boolean 指出訂閱是否設定為訂閱期間結束時自動續約。Indicates whether the subscription is configured to automatically renew at the end of the current subscription period.
beneficiarybeneficiary 字串string 這個訂閱相關聯的權利的受益人識別碼。The ID of the beneficiary of the entitlement that is associated with this subscription.
expirationTimeexpirationTime 字串string 訂閱將結束的日期和時間 (ISO 8601 格式)。The date and time the subscription will expire, in ISO 8601 format. 訂閱處於特定狀態時,才可以使用這個欄位。This field is only available when the subscription is in certain states. 到期時間通常表示目前狀態到期的時間。The expiration time usually indicates when the current state expires. 例如,對於使用中的訂閱,到期日表示將會發生下一個自動續約的時間。For example, for an active subscription, the expiration date indicates when the next automatic renewal will occur.
expirationTimeWithGraceexpirationTimeWithGrace 字串string 日期和時間的訂用帳戶逾期時間包括寬限期,採用 ISO 8601 格式。The date and time the subscription will expire including the grace period, in ISO 8601 format. 這個值表示當使用者將無法再存取訂用帳戶之後的訂用帳戶無法自動更新。This value indicates when the user will lose access to the subscription after the subscription has failed to automatically renew.
idid 字串string 訂閱的識別碼。The ID of the subscription. 當您呼叫變更使用者訂閱的帳單狀態方法,使用這個值,指出您想要修改的訂閱。Use this value to indicate which subscription you want to modify when you call the change the billing state of a subscription for a user method.
isTrialisTrial 布林值Boolean 表示訂閱是否試用。Indicates whether the subscription is a trial.
lastModifiedlastModified 字串string 上次修改訂閱的日期和時間 (ISO 8601 格式)。The date and time the subscription was last modified, in ISO 8601 format.
marketmarket 字串string 使用者取得訂閱所在的國家/地區代碼(兩個字母 ISO 3166-1 alpha-2 格式)。The country code (in two-letter ISO 3166-1 alpha-2 format) in which the user acquired the subscription.
productIdproductId 字串string 產品 Store 識別碼,代表 Microsoft Store 型錄中訂閱附加元件。The Store ID for the product that represents the subscription add-on in the Microsoft Store catalog. 例如,產品的 Store 識別碼是 9NBLGGH42CFD。An example Store ID for a product is 9NBLGGH42CFD.
skuIdskuId 字串string SKU Store 識別碼,代表 Microsoft Store 型錄中訂閱附加元件。The Store ID for the SKU that represents the subscription add-on the Microsoft Store catalog. 例如,SKU 的 Store 識別碼是 0010。An example Store ID for a SKU is 0010.
startTimestartTime 字串string 訂閱的開始日期和時間,格式為 ISO 8601。The start date and time for the subscription, in ISO 8601 format.
recurrenceStaterecurrenceState 字串string 下列其中一個值:One of the following values:
  • None:  這表示永久訂閱。None:  This indicates a perpetual subscription.
  • Active:  訂閱作用中,並且使用者有資格使用服務。Active:  The subscription is active and the user is entitled to use the services.
  • Inactive:  訂閱到期日已過,而且使用者關閉訂閱自動續約的選項。Inactive:  The subscription is past the expiration date, and the user turned off the automatic renew option for the subscription.
  • Canceled:  訂閱在到期日之前刻意終止,可能有退款或無退款。Canceled:  The subscription has been purposefully terminated before the expiration date, with or without a refund.
  • InDunning:  訂閱處於催款(也就是訂閱即將到期,而 Microsoft 嘗試擷取到自動續約訂閱款項)。InDunning:  The subscription is in dunning (that is, the subscription is nearing expiration, and Microsoft is trying to acquire funds to automatically renew the subscription).
  • Failed:  催款期間已結束,在數次嘗試之後訂閱無法續約。Failed:  The dunning period is over and the subscription failed to renew after several attempts.

注意:Note:

  • Inactive/Canceled/Failed 是終止狀態。Inactive/Canceled/Failed are terminal states. 當訂閱進入這些狀態時,使用者必須重新購買訂閱以再次啟動訂閱。When a subscription enters one of these states, the user must repurchase the subscription to activate it again. 使用者無權使用這些狀態的服務。The user is not entitled to use the services in these states.
  • 當訂閱為 Canceled,expirationTime 會以取消日期和時間更新。When a subscription is Canceled, the expirationTime will be updated with the date and time of the cancellation.
  • 訂閱的識別碼在整個生命週期會維持不變。The ID of the subscription will remain the same during its entire lifetime. 如果自動續約選項已開啟或關閉,它不會變更。It will not change if the auto-renew option is turned on or off. 如果使用者到達終止狀態之後重新購買訂閱,將會建立新的訂閱識別碼。If a user repurchases a subscription after reaching a terminal state, a new subscription ID will be created.
  • 訂閱的識別碼應該用來執行任何個別訂閱作業。The ID of a subscription should be used to execute any operation on an individual subscription.
  • 當使用者在取消或終止訂閱之後重新購買訂閱,如果您查詢使用者的結果,您將會取到兩個項目:一個是終止狀態的舊訂閱識別碼,另一個是使用中狀態的新訂閱識別碼。When a user repurchases a subscription after cancelling or discontinuing it, if you query the results for the user you will get two entries: one with the old subscription ID in a terminal state, and one with the new subscription ID in an active state.
  • 檢查 recurrenceState 和 expirationTime 是良好的做法,因為更新 recurrenceState 可能會延遲片刻(偶爾會延遲數小時)。It's always a good practice to check both recurrenceState and expirationTime, since updates to recurrenceState can potentially be delayed by a few minutes (or occasionally hours).
cancellationDatecancellationDate 字串string 使用者取消訂閱的日期和時間 (ISO 8601 格式)。The date and time the user's subscription was cancelled, in ISO 8601 format.