> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Microsoft Store v8 recurrences/query 端點，可傳回使用者的訂閱狀態，包括自動續訂失敗後的寬限期詳細資料。

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

## 必要條件

請檢閱[服務對服務 API 的必要條件](https://learn.microsoft.com/reference/service-to-service-nav#prerequisites-for-service-to-service-apis)。

此 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 金鑰](https://learn.microsoft.com/reference/xstore-requesting-a-userstoreid#step-4-create-a-user-store-id-key)。 | 是 |
| `sbx` | `string` | 使用 UserStoreIds 驗證時的選用值，指定結果應限定的 Sandbox。若無此值，預設為 RETAIL 沙箱。X-Token 驗證不需要此值，因為 Sandbox 已在 X-Token 內指定。 | 否 |
| `continuationToken` | `string` | 如果有多組產品無法容納在 `maxPageSize` 內，當達到頁面限制時，回應本文會傳回接續權杖。請在後續呼叫中提供接續權杖以取得更多結果。 | 否 |

### 要求範例

```html theme={null}
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 的更新可能會延遲幾分鐘 (偶爾會延遲數小時)。

### 回應範例

```json theme={null}
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。

接續要求範例：

```html theme={null}
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/{recurrenceId}/change](/zh-TW/reference/microsoft-store-apis/xstore-v8-recurrence-change)

[從您的服務管理產品](https://learn.microsoft.com/reference/service-to-service-nav)

[從您的服務管理退款和退單](https://learn.microsoft.com/reference/xstore-managing-refunds-and-chargebacks)

[使用 Microsoft Store API 驗證您的服務](https://learn.microsoft.com/reference/xstore-authenticating-your-service)

[使用 publisherQuery (Collections v9) 查詢使用者的產品和權利](/zh-TW/reference/microsoft-store-apis/xstore-v9-query-for-products)


## Related topics

- [purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](/reference/microsoft-store-apis/xstore-v8-recurrence-query.md)
- [Microsoft Store v8 subscription recurrence change API](/reference/microsoft-store-apis/xstore-v8-recurrence-change.md)
- [Managing subscription products from your service](/publishing/xstore-commerce/xstore-managing-subscriptions.md)
- [从你的服务管理订阅产品](/zh-CN/publishing/xstore-commerce/xstore-managing-subscriptions.md)
- [서비스에서 구독 제품 관리](/ko/publishing/xstore-commerce/xstore-managing-subscriptions.md)