> ## 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://devdocs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-authenticating-service.md)」を確認してください。

この API は Microsoft Entra ID 認証タイプのみをサポートします。

パートナー センターで製品構成が公開されていない場合、成功する可能性がありますが、結果は返されません。

## 要求

### 要求の構文

| メソッド | 要求 URI |
| - | - |
| `POST` | `purchase.mp.microsoft.com/v8.0/b2b/recurrences/query` |

### 要求ヘッダー

| ヘッダー | 型 | 説明 |
| - | - | - |
| `Authorization` | `string` | 必須。`Bearer` \<*token*> 形式の Microsoft Entra ID サービス アクセス トークン。 |
| `Host` | `string` | 値 `purchase.mp.microsoft.com` を設定する必要があります。 |
| `Content-Length` | `number` | 要求本文の長さ。 |
| `Content-Type` | `string` | 要求と応答の種類を指定します。現在サポートされているのは `application/json` のみです。 |

### 要求本文

| パラメーター | 型 | 説明 | 必須 |
| - | - | - | - |
| `b2bKey` | `string` | 要求対象のユーザーの ID を表すユーザー購入 ID。「[User Store ID キー](https://devdocs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-requesting-userstoreid.md#step-4-create-a-user-store-id-key)」を参照してください。 | はい |
| `sbx` | `string` | UserStoreIds で認証するときに結果をスコープするサンドボックスを指定するオプションの値。この値がない場合の既定は RETAIL サンドボックスです。X-Token 認証では、サンドボックスが 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` | ユーザー購入 ID 内の受益者のパブリッシャー ID。 | はい |
| `expirationTime` | `DateTime` | サブスクリプションの有効期限が切れる UTC の日時 | はい |
| `expirationTimeWithGrace` | `DateTime` | ExpirationTime に自動更新が失敗した場合に、ユーザーの猶予期間が終了する UTC の日時。猶予期間中、ユーザーは引き続きアクセスでき、有効なサブスクライバーと見なされる必要がありますが、自動更新の支払いを修正する必要があることが通知されます。 | はい |
| `id` | `string` | ユーザーが所有する他のアイテムからこのコレクション アイテムを識別する ID。この ID は製品ごとに一意です。 | はい |
| `isTrial` | `bool` | 製品がサブスクリプションなどのトライアル期間にあるかどうかを示します。 | はい |
| `lastModified` | `DateTime` | このアイテムが最後に変更された UTC 日付。 | はい |
| `market` | `string` | 2 文字の 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` | サブスクリプションが督促 (Dunning) 中です (つまり、サブスクリプションが有効期限に近づいており、Microsoft はサブスクリプションを自動更新するための資金の取得を試みています)。現在の日付が expirationTimeWithGrace 値より前の場合、ユーザーは引き続きサブスクリプション特典を受ける権利があります。現在の日付が expirationTimeWithGrace 値より後の場合、ユーザーはサブスクリプション特典にアクセスできません。 |
| `Failed` | 督促期間が終了し、複数の試行後もサブスクリプションの更新に失敗しました。 |

* *Inactive/Canceled/Failed* は終端状態です。サブスクリプションがこれらの状態のいずれかに入ると、ユーザーはサブスクリプションを再度アクティブ化するために再購入する必要があります。ユーザーはこれらの状態でサービスを利用する権利はありません。
* サブスクリプションが Canceled になると、expirationTime はキャンセルの日時で更新されます。
* サブスクリプションの ID は、そのライフタイム全体で同じままです。自動更新オプションのオン/オフによって変わることはありません。ユーザーが終端状態に達した後にサブスクリプションを再購入した場合は、新しいサブスクリプション ID が作成されます。
* サブスクリプションの ID は、個々のサブスクリプションに対する操作の実行に使用してください。
* ユーザーがキャンセルまたは中止した後にサブスクリプションを再購入した場合、そのユーザーの結果を照会すると、終端状態にある古いサブスクリプション ID とアクティブ状態の新しいサブスクリプション ID の 2 つのエントリが取得されます。
* recurrenceState の更新は数分 (場合によっては数時間) 遅れる可能性があるため、recurrenceState と expirationTime の両方を確認することが常に推奨されます。

### 応答の例

```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"
        },
    ]
}

```

### 応答例の説明

この応答は、ユーザーに対する 3 つのサブスクリプション エントリを示しています。2 つは `Canceled` 状態で、1 つは 2021 年 7 月 26 日に開始された現在 `Active` のものです。
アクティブなサブスクリプションの期間は 2021 年 8 月 26 日に終了し、その日に自動更新されるように設定されています。

更新の支払いが失敗した場合、サブスクリプションは猶予ウィンドウに移行し、ユーザーは `expirationTimeWithGrace` (この例では 2021 年 9 月 8 日) より前に引き続き特典を受け取ります。
サブスクリプションが猶予ウィンドウに移行すると、`recurrenceState` は `InDunning` になります。

猶予が終了すると、サブスクリプションは督促ウィンドウに移行します。
この期間中、サービスは特典の付与を停止し、ユーザーは支払い方法を修正する必要があります。
この期間中、ユーザーはキャンセルしたり、新しいサブスクリプションを開始したりすることはできません。
支払いが処理されると、猶予時間 (この例では 2 週間) が次の有料期間から差し引かれます。

### 継続トークンを使用して残りの結果を要求する

クエリに 1 回の応答で返せる以上の結果がある場合、最初のクエリ応答には 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](https://devdocs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v8-recurrence-change.md)

[サービスから製品を管理する](https://devdocs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-authenticating-service.md)

[サービスからの返金とチャージバックの管理](https://devdocs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-managing-refunds.md)

[Microsoft Store API でサービスを認証する](https://devdocs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-authenticating-service.md)

[publisherQuery (Collections v9) を使用してユーザーの製品と使用権を照会する](https://devdocs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v9-query-for-products.md)


## Related topics

- [サービスからサブスクリプション製品を管理する](https://devdocs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-managing-subscriptions.md)
- [Microsoft Store サービス API (目次)](https://devdocs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-nav.md)
- [purchase.mp.microsoft.com/v8.0/b2b/orders/query](https://devdocs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)
- [purchase.mp.microsoft.com/v8.0/b2b/clawback/sastoken](https://devdocs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v8-clawbackv2-sastoken.md)
- [collections.mp.microsoft.com/v8.0/collections/b2bLicensePreview](https://devdocs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v8-query-for-products.md)