purchase.mp.microsoft.com/v8.0/b2b/recurrences/query

此端點會查詢使用者在 Microsoft Store 中的訂閱產品狀態。它提供的詳細資料比 Collections 更多，包括自動續訂失敗後的寬限期資料。

必要條件

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

要求

要求語法

方法	要求 URI
`POST`	`purchase.mp.microsoft.com/v8.0/b2b/recurrences/query`

要求標頭

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

要求本文

參數	類型	描述	必要
`b2bKey`	`string`	代表您所要求之使用者身分識別的 User Purchase ID。請參閱 User Store ID 金鑰。	是
`sbx`	`string`	使用 UserStoreIds 驗證時的選用值，指定結果應限定的 Sandbox。若無此值，預設為 RETAIL 沙箱。X-Token 驗證不需要此值，因為 Sandbox 已在 X-Token 內指定。	否
`continuationToken`	`string`	如果有多組產品無法容納在 `maxPageSize` 內，當達到頁面限制時，回應本文會傳回接續權杖。請在後續呼叫中提供接續權杖以取得更多結果。	否

要求範例

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/query HTTP/1.1
Host: purchase.mp.microsoft.com
Authorization: Bearer [Microsoft Entra ID bearer token]
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
  "b2bKey":"[UserPurchaseId]",
  "sbx": "XDKS.1"
}

回應

回應本文

參數	類型	描述	必要
`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
date: Tue, 17 Aug 2021 21:22:28 GMT
content-type: application/json; charset=utf-8
content-length: 2382
ms-cv: aft4s000mwNmYF.0
x-content-type-options: nosniff
x-envoy-upstream-service-time: 2099

{
    "items": [
        {
            "autoRenew": true,
            "beneficiary": "pub:NoUserIdProvided",
            "expirationTime": "2021-08-25T23:59:59.00+00:00",
            "expirationTimeWithGrace": "2021-09-08T23:59:59.00+00:00",
            "id": "mdr:0:1ecc1424ed8f457ab6107f08033e6b50:907f0a31-035c-41a2-b70b-5a62925a4f92",
            "isTrial": false,
            "lastModified": "2021-07-26T22:59:55.99+00:00",
            "market": "US",
            "productId": "CFQ7TTC0HC8Z",
            "skuId": "0002",
            "startTime": "2021-07-26T00:00:00.00+00:00",
            "recurrenceState": "Active"
        },
        {
            "autoRenew": true,
            "beneficiary": "pub:NoUserIdProvided",
            "expirationTime": "2021-07-26T21:08:30.52+00:00",
            "expirationTimeWithGrace": "2021-07-26T21:08:30.52+00:00",
            "id": "mdr:0:50c7396d0e5f4e7f9deeede3ba25f1a4:87c4cfae-ed1d-400f-a6b0-19fdb3c327f5",
            "isTrial": false,
            "lastModified": "2021-07-26T21:08:34.61+00:00",
            "market": "US",
            "productId": "CFQ7TTC0HC8Z",
            "skuId": "0002",
            "startTime": "2021-07-15T00:00:00.00+00:00",
            "recurrenceState": "Canceled",
            "cancellationDate": "2021-07-26T21:08:31.52+00:00"
        },
        {
            "autoRenew": false,
            "beneficiary": "pub:NoUserIdProvided",
            "expirationTime": "2021-07-26T22:35:29.54+00:00",
            "expirationTimeWithGrace": "2021-07-26T22:35:29.54+00:00",
            "id": "mdr:0:528115d9771f4e49b79550790fd4a263:f30a646e-54cf-4fe8-8c95-7add9fc2ebde",
            "isTrial": false,
            "lastModified": "2021-07-26T22:35:33.96+00:00",
            "market": "US",
            "productId": "CFQ7TTC0HC8Z",
            "skuId": "0002",
            "startTime": "2021-07-26T00:00:00.00+00:00",
            "recurrenceState": "Canceled",
            "cancellationDate": "2021-07-26T22:35:30.54+00:00"
        },
    ]
}

範例回應說明

此回應顯示使用者的三個訂閱項目：兩個處於 Canceled 狀態，一個目前為 Active，於 2021 年 7 月 26 日開始。作用中訂閱的期間於 2021 年 8 月 26 日結束，並設定為在該日期自動續訂。如果續訂付款失敗，訂閱會轉換至寬限期，在 expirationTimeWithGrace (此範例中為 2021 年 9 月 8 日) 之前，使用者仍會獲得權益。當訂閱轉換至寬限期時，recurrenceState 會變成 InDunning。寬限期結束後，訂閱會轉換至催收期。在此期間，您的服務會停止授與權益，且使用者必須修正其付款方式。使用者在此期間無法取消或開始新的訂閱。處理付款後，寬限時間 (此範例中為兩週) 會從下一個付費期間中扣除。

使用接續權杖要求其餘結果

如果您的查詢結果多於單一回應所能傳回的數量，您的初始查詢回應中會有 continuationToken。接著，您可以將接續權杖新增至先前要求本文的複本，在後續要求中使用此 continuationToken。接續要求範例：

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/query HTTP/1.1
Host: purchase.mp.microsoft.com
Authorization: Bearer [Microsoft Entra ID bearer token]
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
  "continuationToken":"[Continuation Token]",
  "b2bKey":"[UserPurchaseId]",
  "sbx": "XDKS.1"
}

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

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

必要條件

要求

要求語法

要求標頭

要求本文

要求範例

回應

回應本文

週期狀態

回應範例

範例回應說明

使用接續權杖要求其餘結果

相關文章

​必要條件

​要求

​要求語法

​要求標頭

​要求本文

​要求範例

​回應

​回應本文

​週期狀態

​回應範例

​範例回應說明

​使用接續權杖要求其餘結果

​相關文章

必要條件

要求

要求語法

要求標頭

要求本文

要求範例

回應

回應本文

週期狀態

回應範例

範例回應說明

使用接續權杖要求其餘結果

相關文章