次の方法で共有


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

このエンドポイントは、ユーザーが Microsoft Store を通じて所有しているサブスクリプション製品タイプのステータスを照会するために使用されます。 自動更新料金が失敗した場合の製品の猶予期間など、これらのサブスクリプションのコレクション サービスよりも多くの情報を提供します。

前提条件

この API を使用するには、以下が必要になります。

  • 対象ユーザーの URI 値 https://onestore.microsoft.com を持つ Microsoft Entra ID アクセス トークン
  • 付与する無料製品のユーザーの ID を表すユーザー購入 ID キー

詳細については、「サーバー間認証にユーザー Store ID を要求する」を参照してください。

さらに、サービスに表示できるようにする製品には、パートナー センターでの追加の構成が必要です。

製品を適切に構成する方法については、「ユーザー Store ID / Microsoft Entra ID 認証を使用して製品を表示および管理するために必要な追加の構成」を参照してください。

注意

製品の構成がまだ行われておらず、パートナー センター経由で発行された場合、購入サービスの呼び出しは成功しますが、応答に結果は入りません。

要求

要求の構文

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

要求ヘッダー

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

リクエストの本文

パラメーター 説明 必須
b2bKey string 要求しているユーザーの ID を表すユーザー購入 ID。 ユーザー ストア ID キーを参照してください。 はい
sbx string 結果のスコープを設定するサンドボックスを指定する UserStoreIds で認証するための省略可能な値。 この値のない既定値は RETAIL サンドボックスです。 サンドボックスは X トークン内で指定されているため、X トークン認証ではこの値は必要ありません。 いいえ
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 ユーザー購入 ID 内の受益者の発行者 ID。 はい
expirationTime DateTime サブスクリプションの有効期限が切れる、または期限切れになる日時 (UTC) はい
expirationTimeWithGrace DateTime ExpirationTime で自動更新が失敗した場合に、ユーザーの猶予期間が終了する日時 (UTC)。 Grace の間、ユーザーは引き続きアクセスでき、有効なサブスクライバーと見なされますが、自動更新の支払いを修正する必要があることを通知されます。 はい
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 サブスクリプションは督促状態にあります (つまり、サブスクリプションの有効期限が近づいているので、Microsoft はサブスクリプションを自動的に更新するための資金を取得しようとしています)。 現在の日付が expirationTimeWithGrace 値より前の場合、ユーザーにはまだサブスクリプション特典を受け取る資格があります。 現在の日付が expirationTimeWithGrace 値より後の場合、ユーザーにはサブスクリプション特典を受け取る資格がありません。
Failed 督促期間が終了し、数回試行しましたがサブスクリプションを更新できませんでした。
  • 非アクティブ/キャンセル済み/失敗は、最終状態です。 サブスクリプションがこれらのいずれかの状態になった場合、ユーザーがサブスクリプションを再度アクティブ化するには、再購入する必要があります。 ユーザーは、これらの状態にあるサービスを使用する資格はありません。
  • サブスクリプションがキャンセルされると、expirationTime はキャンセルの日時で更新されます。
  • サブスクリプションの ID は、有効期間全体にわたって同じまま保持されます。 これは、自動更新オプションがオンでもオフでも、変更されません。 最終状態に達した後にユーザーがサブスクリプションを再購入すると、新しいサブスクリプション ID が作成されます。
  • 個々のサブスクリプションに対して何かの操作を実行するには、サブスクリプションの ID を使用する必要があります。
  • ユーザーがサブスクリプションをキャンセルまたは中止した後にサブスクリプションを再購入した場合、そのユーザーの結果に対してクエリを実行すると、2 つの項目が取得されます。1 つは最終状態の古いサブスクリプション ID を持つ項目、もう 1 つはアクティブ状態の新しいサブスクリプション ID を持つ項目です。
  • recurrenceState の更新は数分 (または場合によっては数時間) 遅れる可能性があるため、常に recurrenceState と expirationTime の両方を確認することをお勧めします。

応答の例

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

応答例の説明

上記の例から、このユーザーには、以前にキャンセルされた 2 つのサブスクリプション期間と、2021 年 7 月 26 日に開始された現在アクティブなサブスクリプション期間があります。 サブスクリプション期間の終了日は 2021 年 8 月 26 日です。 ユーザーは自動更新に登録されているため、Microsoft Store は 2021 年 8 月 26 日頃に処理された支払いでサブスクリプションの更新を試みます。 ユーザーのアカウントでサブスクリプションの更新を完了できない場合、サブスクリプションの状態は 'InDunning' (督促中) に変わりますが、猶予期間が終了するまで、ユーザーは引き続きサブスクリプション特典へのアクセス権を受け取ることができます。 猶予期間の終了 (2021 年 9 月 8 日) の時点でストアが更新の購入を完了できなかった場合は、状態がまだ 'InDunning' (督促中) であっても、サービスはサブスクリプション特典をユーザーに付与しなくなります。 猶予期間の後、ユーザーはサブスクリプションの再購入または再登録をブロックされるようになり、アクティブなサブスクリプションを再度取得するには支払い方法を修正する必要があります。 これは、猶予期間中に 2 週間分の特典を受け取っており、支払いが不足しているためです。 アカウントの支払い方法を解決すると、以前に使用した猶予期間分を調整するために、次のサブスクリプション期間から 2 週間が削除されます。

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

クエリの結果が単一応答で返される結果よりも多い場合、最初のクエリ応答には 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/{recurrenceId}/change

サービスから製品を管理する

サービスからの払い戻しとチャージバックの管理

Microsoft Store API によるサービスの認証

PublisherQuery (コレクション v9) を使用してユーザーの製品と資格を照会する