> ## 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/orders/query

> 已淘汰的 Microsoft Store v8 orders/query API，可讓遊戲服務查詢使用者過去 90 天內的消耗品購買，包括 ShortOrderID。

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

<Note>
  此 API 已淘汰，不再用於退款偵測。請改用收回事件服務，如[從您的服務管理退款和退單](https://learn.microsoft.com/reference/xstore-managing-refunds-and-chargebacks)中所述。
</Note>

`purchase.mp.microsoft.com/v8.0/b2b/orders/query` API 可讓遊戲服務查詢使用者過去 90 天內的消耗品購買。它也會傳回 Collections 查詢中沒有的欄位，例如用於支援工作流程的 `ShortOrderID`。

## 必要條件

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

此 API 僅支援 Microsoft Entra ID 驗證類型。

如果產品設定未在 Partner Center 中發佈，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` | 代表您要為其提出要求之使用者身分識別的 User Purchase ID。請參閱 [User Store ID 金鑰](https://learn.microsoft.com/reference/xstore-requesting-a-userstoreid#step-4-create-a-user-store-id-key)。 | 是 |
| `lineItemStateFilter` | `list<string>` | 指定要在查詢結果中傳回哪些項目狀態。如需有效值的清單，請參閱[明細項目狀態](#line-item-states)。 | 否 |
| `sbx` | `string` | 使用 UserStoreIds 進行驗證時的選用值，用來指定結果應限定的沙箱。若沒有此值，預設為 RETAIL 沙箱。X-Token 驗證不需要此值，因為沙箱已在 X-Token 中指定。 | 否 |

### 明細項目狀態

| 值 | 描述 |
| - | - |
| `Purchased` | 處於有效 (良好) 狀態的消耗品購買。此狀態包括未履行和已履行的消耗品。 |
| `Revoked` | 已由遊戲服務履行或消耗，之後由使用者退款的消耗品購買。 |
| `Refunded` | 在履行或消耗之前就已退款給使用者的消耗品購買。 |

### 要求範例

```html theme={null}
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` | 購買訂單號碼的完整格式識別碼。Collections 和其他服務所使用的 OrderID。 | 是 |
| `shortOrderId` | `GUID` | 購買訂單號碼的簡短格式識別碼。終端使用者在其購買記錄和確認電子郵件中看到的訂單號碼。使用者會向您的支援人員提供此識別碼來代表其購買。 | 否 |
| `orderLineItems` | `list<OrderLineItem>` | 與使用者購買 OrderId 內消耗品相關之其他資訊的陣列。如需詳細資訊，請參閱下表。 | 是 |
| `orderPurchasedDate` | `datetime` | 購買消耗品的 UTC 日期和時間。 | 是 |
| `orderRefundedDate` | `datetime` | 消耗品退款的 UTC 日期和時間。此值需要幾個小時才會出現在已退款的項目上。 | 否 |

`OrderLineItem` 物件包含下列參數。

| 參數 | 類型 | 描述 | 必要 |
| - | - | - | - |
| `lineItemId` | `GUID` | 識別消耗品購買訂單中的 lineItem (在購物車案例中，訂單可以有多個 lineItemId) | 是 |
| `lineItemState` | `string` | 此特定消耗品購買的狀態。請參閱[明細項目狀態](#line-item-states)。 | 是 |
| `productId` | `string` | 也稱為 Microsoft Store 目錄中產品的 Store ID。產品的 Store ID 範例為 9NBLGGH42CFD。 | 是 |
| `quantity` | `number` | 在訂單中購買時的項目數量。 | 是 |
| `skuId` | `string` | 如果 Microsoft Store 目錄中有多個產品供應項目，則為特定的 SKU 識別碼。SKU 的 Store ID 範例為 0010。 | 是 |
| `wasConsumableQuantityRevoked` | `bool` | 指出發生退款時，是否能夠從使用者的 Store 帳戶中移除所購買的數量。 | 否 |

### 回應範例

```json theme={null}
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` 五次。其中兩筆購買為 `Revoked`，表示它們是在消耗*之後*才退款。如需近乎即時的退款偵測，請使用[從您的服務管理退款和退單](https://learn.microsoft.com/reference/xstore-managing-refunds-and-chargebacks)中所述的收回事件流程。

## 相關文章

[從您的服務管理消耗品](https://learn.microsoft.com/reference/xstore-managing-consumables-and-refunds)

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

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

[使用 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/orders/query](/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)
- [Microsoft Store service APIs](/reference/microsoft-store-apis/xstore-nav.md)
- [APIs de servicio de Microsoft Store](/es/reference/microsoft-store-apis/xstore-nav.md)
- [Microsoft Store 服务 API](/zh-CN/reference/microsoft-store-apis/xstore-nav.md)
- [Managing consumable products from your service](/publishing/xstore-commerce/xstore-managing-consumables.md)