Share via

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

  • Article

Note

This API is no longer needed or used as part of the Clawback flow to detect refunded products. For information on the latest Clawback service, see Managing refunds and chargebacks from your service.

The purchase.mp.microsoft.com/v8.0/b2b/orders/query API provides a game service the ability to query the consumable purchases made by a user over the past 90 days. Using this API, game services can gather some information not available in the Collections Query results including the ShortOrderID field that may be useful for customer support scenarios.

Prerequisites

To use this API, you need the following:

  • A Microsoft Entra ID access token that has the audience URI value https://onestore.microsoft.com
  • A User Purchase ID key that represents the identity of the user for whom you want to grant a free product

For more information, see Requesting a User Store ID for service-to-service authentication.

Additionally, the products that you want to be visible to your service require additional configuration in Partner Center.

See Additional configuration required to view and manage products with a User Store ID / Microsoft Entra ID Auth for how to properly configure your products.

Note

If the product configuration has not been done and published through Partner Center, the calls to Purchase services will succeed but there will not be any results in the response.

Request

Request syntax

Method Request URI
POST https://purchase.mp.microsoft.com/v8.0/b2b/orders/query

Request header

Header Type Description
Authorization string Required. The Microsoft Entra ID service access token in the form Bearer <token>.
Host string Must be set to the value purchase.mp.microsoft.com.
Content-Length number The length of the request body.
Content-Type string Specifies the request and response type. Currently, the only supported value is application/json.

Request body

Parameter Type Description Required
b2bKey string The User Purchase Id that represents the identity of the user for whom you are requesting. See User Store ID key. Yes
lineItemStateFilter list<string> Specifies which item states to return in the query results. For a list of valid values, see Line item states. No
sbx string Optional value for authenticating with UserStoreIds that specifies the Sandbox the results should be scoped to. Default without this value is the RETAIL sandbox. X-Token auth does not need this value as the Sandbox is specified within the X-Token. No

Line item states

Value Description
Purchased Consumable purchases that are in an active (good) state. This state includes unfulfilled and fulfilled consumables.
Revoked Consumable purchases that were fulfilled / consumed by the game service, but were later refunded by the user.
Refunded Consumable purchases that were refunded but were not yet fulfilled / consumed by the game service.

Request example

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

Response

Response body

Parameter Type Description Required
items list<PurchasedItem> An array of products for the specified user. For more information, see the following table. Yes

The PurchasedItem object contains the following parameters.

Parameter Type Description Required
orderId GUID Long form ID of the purchase's order #. This is the orderID used by Collections and other services. Yes
shortOrderId GUID Short form ID of the purchase's order #. This is the order # that the end-user will see in their purchase history and confirmation emails. If providing customer support, the users will provide this ID to your support staff to represent their purchase. No
orderLineItems list<OrderLineItem> An array of additional information related to the consumable within the purchasing OrderId from the user. For more information, see the following table. Yes
orderPurchasedDate datetime The UTC date and time that the consumable was purchased. Yes
orderRefundedDate datetime The UTC date and time that the consumable was refunded. This value takes a few hours to show up on a refunded item. No

The OrderLineItem object contains the following parameters.

Parameter Type Description Required
lineItemId GUID Identifies the lineItem within the purchase order for the consumable (orders can have multiple lineItemIds for shopping cart scenarios) Yes
lineItemState string The state of this specific consumable purchase. See Line item states. Yes
productId string Also refereed to as the Store ID for the product within the Microsoft Store catalog. An example Store ID for a product is 9NBLGGH42CFD. Yes
quantity number The quantity of the item when purchased in the order. Yes
skuId string The specific SKU identifier if there are multiple offerings of the product in the Microsoft Store catalog. An example Store ID for a SKU is 0010. Yes
wasConsumableQuantityRevoked bool Indicates if the purchased quantity was able to be removed from the user's store account when the refund happened. No

Response Example

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

Explanation of example response

From the above example (where we asked for all states) we see that the user's account purchased the consumable 9MT5TGW893HV 5 times. Two of those purchases however have a line item state of Revoked, which means that they were refunded after they were consumed by our example game service. For tracking refund events when they happen, the purchase.mp.microsoft.com/v8.0/b2b/orders/query should not be used. Instead, your service should use the Clawback event service outlined in Managing refunds and chargebacks from your service.

Managing consumable products from your service

Managing refunds and chargebacks from your service

Manage products from your services

Authenticating your service with the Microsoft Store APIs

Using PublisherQuery (Collections v9) to query a user's products and entitlements