Microsoft Store v8 訂閱週期變更 API

此 API 只有在訂閱已發佈至 RETAIL 時才能運作。如果使用開發沙箱，請先將訂閱發佈至私人測試群組，或在 RETAIL 中以隱藏方式發佈，再呼叫此 API。如果訂閱未發佈至 RETAIL，回應會是 HTTP 400 錯誤，訊息會指出「Requested catalog product data wasn’t found.」

此端點用於變更使用者在 Microsoft Store 中訂閱產品的計費狀態。您可以取消、延長、退款訂閱，或停用訂閱的自動續訂。 Microsoft.StoreServices 程式庫 (GitHub) 透過 StoreServicesClient.RecurrenceChangeAsync API 提供此方法的功能。

必要條件

請檢閱服務對服務 API 的必要條件。此 API 僅支援 Microsoft Entra ID 驗證類型。如果產品設定未在 Partner Center 中發佈，呼叫可能會成功，但不會傳回任何結果。

要求

要求語法

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

要求標頭

標頭	類型	描述
`Authorization`	`string`	必要。Microsoft Entra ID 服務存取權杖，格式為 `Bearer` <token>。
`Host`	`string`	必須設定為值 `purchase.mp.microsoft.com`。
`Content-Length`	`number`	要求本文的長度。
`Content-Type`	`string`	指定要求和回應類型。目前唯一支援的值是 `application/json`。

要求參數

標頭	類型	描述	必要
`recurrenceId`	`string`	對使用者的訂閱而言是唯一的，且與 RecurrenceQuery API 中的 `id` 以及 Collections 查詢 API 中的 `recurrenceData` 為相同的值。	是

要求本文

參數	類型	描述	必要
`b2bKey`	`string`	代表您所要求之使用者身分識別的 User Purchase ID。請參閱 User Store ID 金鑰。	是
`changeType`	`string`	識別您要進行的變更類型。如需可能的值，請參閱變更類型作業表格。	是
`extensionTimeInDays`	`string`	如果 changeType 參數的值為 Extend，此參數會指定要延長訂閱的天數。在測試案例中，此數字可以是負數，以從訂閱中移除天數。	如果 changeType 的值為 Extend，則為是；否則為否。
`sbx`	`string`	使用 UserStoreIds 驗證時的選用值，指定結果應限定的 Sandbox。若無此值，預設為 RETAIL 沙箱。X-Token 驗證不需要此值，因為 Sandbox 已在 X-Token 內指定。	否

變更類型作業

變更類型	描述
`Cancel`	取消訂閱。
`Extend`	延長訂閱。如果您指定此值，也必須在要求本文中包含 `extensionTimeInDays` 參數。
`Refund`	將訂閱退款給客戶。
`ToggleAutoRenew`	停用訂閱的自動續訂。如果訂閱的自動續訂目前已停用，此值不會有任何作用。

要求範例

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

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 回應本文，描述已更新的訂閱附加元件，包括已修改的欄位。

此方法具有與本文開頭所述相同的 RETAIL 發佈需求。

回應本文

參數	類型	描述	必要
`continuationToken`	`string`	如果有多組產品，當達到頁面限制時，就會傳回此權杖。您可以在後續呼叫中指定此接續權杖，以擷取其餘產品。	否
`items`	`list<RecurrenceItem>`	指定使用者的產品陣列。如需詳細資訊，請參閱下表。	是

RecurrenceItem 物件包含下列參數。

參數	類型	描述	必要
`autoRenew`	`bool`	表示使用者是否已註冊在下一個計費週期結束時自動續訂其訂閱。	是
`beneficiary`	`string`	User Purchase ID 中受益人的 Publisher ID。	是
`expirationTime`	`DateTime`	訂閱到期的 UTC 日期和時間。	是
`expirationTimeWithGrace`	`DateTime`	如果在 ExpirationTime 自動續訂失敗，使用者寬限期結束的 UTC 日期和時間。在寬限期間，使用者仍應具有存取權並被視為有效的訂閱者，但應通知他們需要修正自動續訂付款。	是
`id`	`string`	用來區分此集合項目與使用者擁有之其他項目的 ID。此 ID 對每個產品都是唯一的。	是
`isTrial`	`bool`	表示產品是否處於試用期間，例如訂閱。	是
`lastModified`	`DateTime`	此項目上次修改的 UTC 日期。	是
`market`	`string`	購買產品的國家/地區，採用兩個字元的 ISO 3166 國家/地區代碼。例如：US。	是
`productId`	`string`	也稱為 Microsoft Store 目錄中產品的 Store ID。產品的 Store ID 範例為 9NBLGGH42CFD。	是
`recurrenceState`	`string`	週期的目前狀態。請參閱週期狀態。	是
`skuId`	`string`	如果 Microsoft Store 目錄中有多個產品供應項目，則為特定的 SKU 識別碼。SKU 的 Store ID 範例為 0010。	是
`startTime`	`DateTime`	訂閱開始的 UTC 日期。	是
`cancellationDate`	`DateTime`	訂閱被取消的 UTC 日期。	否

週期狀態

值	描述
`None`	表示永久訂閱。
`Active`	訂閱有效，且使用者有權享有訂閱權益。
`Inactive`	訂閱已超過到期日，且使用者已關閉訂閱的自動續訂選項。
`Canceled`	訂閱在到期日之前被刻意終止，不論是否有退款。
`InDunning`	訂閱處於催收狀態 (也就是訂閱即將到期，且 Microsoft 正嘗試取得款項以自動續訂訂閱)。如果目前日期早於 expirationTimeWithGrace 值，使用者仍應有權享有訂閱權益。如果目前日期晚於 expirationTimeWithGrace 值，使用者不應具有訂閱權益的存取權。
`Failed`	催收期間已結束，且訂閱在多次嘗試後仍無法續訂。

Inactive/Canceled/Failed 是終止狀態。當訂閱進入其中一種狀態時，使用者必須重新購買訂閱才能再次啟用。使用者在這些狀態下無權使用服務。
當訂閱為 Canceled 時，expirationTime 會更新為取消的日期和時間。
訂閱的 ID 在其整個存留期間都保持不變。開啟或關閉自動續訂選項時，ID 不會變更。如果使用者在到達終止狀態後重新購買訂閱，將會建立新的訂閱 ID。
應使用訂閱的 ID 來對個別訂閱執行任何作業。
當使用者在取消或停止訂閱後重新購買時，如果您查詢該使用者的結果，將會得到兩個項目：一個是處於終止狀態的舊訂閱 ID，另一個是處於作用中狀態的新訂閱 ID。
最好一律同時檢查 recurrenceState 和 expirationTime，因為 recurrenceState 的更新可能會延遲幾分鐘 (偶爾會延遲數小時)。

回應範例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 431
ms-correlationid: 95b2aee4-1118-437b-8910-a2f7d84d0766
ms-cv: Kl684e1htkqb19Ch.0
Date: Thu, 03 Mar 2022 23:19:12 GMT

{
    "autoRenew": true,
    "beneficiary": "pub:NoUserIdProvided",
    "expirationTime": "2022-03-03T23:59:59.00+00:00",
    "expirationTimeWithGrace": "2022-03-17T23:59:59.00+00:00",
    "id": "mdr:0:3172048a2d1849ba9a24fd305854d4a8:cedca1d3-9580-4229-9cb5-f00c4547078c",
    "isTrial": false,
    "lastModified": "2022-03-03T23:19:12.26+00:00",
    "market": "US",
    "productId": "CFQ7TTC0HC8Z",
    "skuId": "0003",
    "startTime": "2022-03-03T00:00:00.00+00:00",
    "recurrenceState": "Active"
}

purchase.mp.microsoft.com/v8.0/b2b/recurrences/query 從您的服務管理產品從您的服務管理退款和退單使用 Microsoft Store API 驗證您的服務使用 publisherQuery (Collections v9) 查詢使用者的產品和權利

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

必要條件

要求

要求語法

要求標頭

要求參數

要求本文

變更類型作業

要求範例

回應

回應本文

週期狀態

回應範例

相關文章

​必要條件

​要求

​要求語法

​要求標頭

​要求參數

​要求本文

​變更類型作業

​要求範例

​回應

​回應本文

​週期狀態

​回應範例

​相關文章

必要條件

要求

要求語法

要求標頭

要求參數

要求本文

變更類型作業

要求範例

回應

回應本文

週期狀態

回應範例

相關文章