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

この API は返金検出のために非推奨となっています。代わりに、「サービスからの返金とチャージバックの管理」で説明されている Clawback イベントサービスを使用してください。

purchase.mp.microsoft.com/v8.0/b2b/orders/query API を使用すると、ゲームサービスは過去 90 日間のユーザーの消費型購入を照会できます。また、サポートワークフロー向けの ShortOrderID など、Collections クエリでは利用できないフィールドも返します。

前提条件

「サービス間 API の前提条件」を確認してください。この API は Microsoft Entra ID 認証タイプのみをサポートします。パートナーセンターで製品構成が公開されていない場合、API は成功する可能性がありますが、結果は返されません。

要求

要求の構文

メソッド	要求 URI
`POST`	`https://purchase.mp.microsoft.com/v8.0/b2b/orders/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 key」を参照してください。	はい
`lineItemStateFilter`	`list<string>`	クエリ結果に返すアイテムの状態を指定します。有効な値の一覧については、「明細アイテムの状態」を参照してください。	いいえ
`sbx`	`string`	UserStoreIds で認証するときに結果をスコープするサンドボックスを指定するオプションの値。この値がない場合の既定は RETAIL サンドボックスです。X-Token 認証では、サンドボックスが X-Token 内で指定されるため、この値は不要です。	いいえ

明細アイテムの状態

値	説明
`Purchased`	アクティブ (良好) な状態にある消費型購入。この状態には、未消化および消化済みの消費型アイテムが含まれます。
`Revoked`	ゲームサービスによって消化または消費された後、ユーザーが返金を受けた消費型購入。
`Refunded`	消化または消費される前にユーザーが返金を受けた消費型購入。

要求の例

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

{
  "b2bKey":"[UserPurchaseId]",
  "lineItemStateFilter": [
    "Purchased",
    "Revoked",
    "Refunded"],
  "sbx": "XDKS.1"
}

応答

応答本文

パラメーター	型	説明	必須
`items`	`list<PurchasedItem>`	指定されたユーザーの製品の配列。詳細については、次の表を参照してください。	はい

PurchasedItem オブジェクトには、次のパラメーターが含まれています。

パラメーター	型	説明	必須
`orderId`	`GUID`	購入注文番号のロング形式 ID。Collections や他のサービスで使用される OrderID。	はい
`shortOrderId`	`GUID`	購入注文番号のショート形式 ID。エンドユーザーが購入履歴や確認メールで見る注文番号。ユーザーはこの ID をサポートスタッフに提供して購入を示します。	いいえ
`orderLineItems`	`list<OrderLineItem>`	ユーザーからの購入 OrderId 内の消費型アイテムに関連する追加情報の配列。詳細については、次の表を参照してください。	はい
`orderPurchasedDate`	`datetime`	消費型アイテムが購入された UTC の日付と時刻。	はい
`orderRefundedDate`	`datetime`	消費型アイテムが返金された UTC の日付と時刻。この値が返金アイテムに表示されるまで数時間かかります。	いいえ

OrderLineItem オブジェクトには、次のパラメーターが含まれています。

パラメーター	型	説明	必須
`lineItemId`	`GUID`	消費型アイテムに対する注文内の明細アイテムを識別します (ショッピングカートシナリオでは、注文に複数の lineItemIds が含まれる場合があります)	はい
`lineItemState`	`string`	この特定の消費型購入の状態。「明細アイテムの状態」を参照してください。	はい
`productId`	`string`	Microsoft Store カタログ内の製品に対する Store ID とも呼ばれます。製品の Store ID の例は 9NBLGGH42CFD です。	はい
`quantity`	`number`	注文時に購入されたアイテムの数量。	はい
`skuId`	`string`	Microsoft Store カタログに製品の複数のオファリングがある場合の特定の SKU 識別子。SKU の Store ID の例は 0010 です。	はい
`wasConsumableQuantityRevoked`	`bool`	返金時にユーザーのストアアカウントから購入数量を削除できたかどうかを示します。	いいえ

応答の例

HTTP/1.1 200 OK
Content-Length: 1042
Content-Type: application/json
MS-CorrelationId: b5157f23-7f26-4e0b-8f06-07733bd09355
MS-RequestId: 2b0933bc-19f7-4f96-bb47-2602491fed1f
MS-CV: OAIoYIzDJkO2Knp.7
MS-ServerId: 1
Date: Tue, 30 Jun 2020 18:29:22 GMT
 
{
    "items": [
        {
            "orderId": "3c1ad7bc-b0c2-442c-aad4-46d8d0e0184e",
            "shortOrderId": "8483143756",
            "orderLineItems": [
                {
                    "lineItemId": "febdd51b-97aa-45fc-bf46-0120eacbf8aa",
                    "lineItemState": "Purchased",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-12T23:57:51.1415104+00:00"
        },
        {
            "orderId": "75bf81ec-7c31-46f9-9828-6ac61464e553",
            "shortOrderId": "3145294485",
            "orderLineItems": [
                {
                    "lineItemId": "ad7adfc5-be76-4548-aede-155084490044",
                    "lineItemState": "Purchased",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-13T23:57:51.1415104+00:00"
        },
        {
            "orderId": "b9d6d1fd-3e68-423b-85fa-feea1ee125b3",
            "shortOrderId": "7620137155",
            "orderLineItems": [
                {
                    "lineItemId": "eb565041-6e1f-4210-97a3-54a2ab80f49e",
                    "lineItemState": "Revoked",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-142T23:57:51.1415104+00:00",
            "orderRefundedDate": "2021-06-162T10:05:35.9634676+00:00"
        },
        {
            "orderId": "cda65a53-30b0-4e19-8ec1-c08219174e45",
            "shortOrderId": "5993204763",
            "orderLineItems": [
                {
                    "lineItemId": "a30b4285-c456-4486-8048-a9f5b5231b76",
                    "lineItemState": "Revoked",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-152T23:57:51.1415104+00:00",
            "orderRefundedDate": "2021-06-162T10:05:35.9634676+00:00"
        },
        {
            "orderId": "f1da6d12-8b0d-4dc1-8aca-c52fcece582a",
            "shortOrderId": "8768763421",
            "orderLineItems": [
                {
                    "lineItemId": "7da73274-b4bc-4a4f-bb93-e49618f7a7d7",
                    "lineItemState": "Purchased",
                    "productId": "9MT5TGW893HV",
                    "quantity": 1,
                    "skuId": "0010",
                    "wasConsumableQuantityRevoked": false
                }
            ],
            "orderPurchasedDate": "2021-06-16T23:57:51.1415104+00:00"
        }
    ]
}

応答例の説明

この例では、ユーザーが消費型 9MT5TGW893HV を 5 回購入しています。うち 2 件は Revoked になっており、消費された後に返金されたことを意味します。ニアリアルタイムでの返金検出には、「サービスからの返金とチャージバックの管理」で説明されている Clawback イベントフローを使用してください。

サービスから消費型製品を管理するサービスからの返金とチャージバックの管理サービスから製品を管理する Microsoft Store API でサービスを認証する publisherQuery (Collections v9) を使用してユーザーの製品と使用権を照会する

Microsoft Store APIs

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

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

前提条件

要求

要求の構文

要求ヘッダー

要求本文

明細アイテムの状態

要求の例

応答

応答本文

応答の例

応答例の説明

関連記事

​purchase.mp.microsoft.com/v8.0/b2b/orders/query

​前提条件

​要求

​要求の構文

​要求ヘッダー

​要求本文

​明細アイテムの状態

​要求の例

​応答

​応答本文

​応答の例

​応答例の説明

​関連記事

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

前提条件

要求

要求の構文

要求ヘッダー

要求本文

明細アイテムの状態

要求の例

応答

応答本文

応答の例

応答例の説明

関連記事