> ## 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/purchases/grant

> Microsoft Store v8 purchases/grant API，可讓遊戲服務使用 Microsoft Entra ID 驗證，將免費應用程式或附加元件直接授與使用者的帳戶。

使用 Microsoft Store 購買 API，將免費應用程式或附加元件授與使用者的帳戶。

只有免費產品可以直接授與使用者的帳戶。
嘗試授與付費產品會傳回錯誤。

## 必要條件

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

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

如果產品設定未在 Partner Center 中發佈，呼叫可能會成功，但不會傳回任何結果。

## 要求

### 要求語法

| 方法 | 要求 URI |
| - | - |
| `POST` | `https://purchase.mp.microsoft.com/v7.0/purchases/grant` |

### 要求標頭

| 標頭 | 類型 | 描述 |
| - | - | - |
| `Authorization` | `string` | 必要。格式為 `Bearer` \<*token*> 的 Microsoft Entra ID 服務存取權杖。 |
| `Host` | `string` | 必須設定為值 `purchase.mp.microsoft.com`。 |
| `Content-Length` | `number` | 要求本文的長度。 |
| `Content-Type` | `string` | 指定要求和回應類型。目前唯一支援的值是 `application/json`。 |

### 要求本文

| 參數 | 類型 | 描述 | 必要 |
| - | - | - | - |
| `availabilityId` | `string` | 要從 Microsoft Store 目錄授與之產品的可用性識別碼。 | 是 |
| `b2bKey` | `string` | 代表您要授與產品之使用者身分識別的 [User Store ID 金鑰](https://learn.microsoft.com/reference/xstore-requesting-a-userstoreid#step-4-create-a-user-store-id-key)。 | 是 |
| `devOfferId` | `string` | 開發人員指定的供應項目識別碼，會在購買後出現在 Collection 項目中。 | 否 |
| `language` | `string` | 使用者的語言。 | 是 |
| `market` | `string` | 使用者的市場。 | 是 |
| `orderId` | `GUID` | 為訂單產生的 GUID。此值對使用者而言是唯一的，但不需要在所有訂單中都是唯一的。 | 是 |
| `productId` | `string` | Microsoft Store 目錄中[產品](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities)的 [Store ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids)。產品的 Store ID 範例為 9NBLGGH42CFD。 | 是 |
| `quantity` | `int` | 要購買的數量。目前唯一支援的值是 1。如果未指定，預設值為 1。 | 否 |
| `skuId` | `string` | Microsoft Store 目錄中產品 [SKU](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities) 的 [Store ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids)。SKU 的 Store ID 範例為 0010。 | 是 |
| `sbx` | `string` | 使用 UserStoreIds 進行驗證時的選用值，用來指定結果應限定的沙箱。若沒有此值，預設為 RETAIL 沙箱。X-Token 驗證不需要此值，因為沙箱已在 X-Token 中指定。 | 否 |

### 要求範例

```syntax theme={null}
POST https://purchase.mp.microsoft.com/v7.0/purchases/grant HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJK...
Content-Length: 1863
Content-Type: application/json

{
    "b2bKey" : "eyJ0eXAiOiJK...",
    "availabilityId" : "9RT7C09D5J3W",
    "productId" : "9NBLGGH5WVP6",
    "skuId" : "0010",
    "language" : "en-us",
    "market" : "us",
    "orderId" : "3eea1529-611e-4aee-915c-345494e4ee76",
    "sbx" : "XDKS.1"
}
```

## 回應

### 回應本文

| 參數 | 類型 | 描述 | 必要 |
| - | - | - | - |
| `clientContext` | `ClientContextV8` | 訂單的用戶端內容資訊。指派給 Microsoft Entra ID 權杖中的 `clientID` 值。 | 是 |
| `createdtime` | `datetimeoffset` | 建立訂單的時間。 | 是 |
| `currencyCode` | `string` | `totalAmount` 和 `totalTaxAmount` 的貨幣代碼。免費項目不適用。 | 是 |
| `friendlyName` | `string` | 訂單的易記名稱。使用 Microsoft Store 購買 API 所下的訂單不適用。 | 是 |
| `isPIRequired` | `boolean` | 指出購買訂單是否需要付款方式 (PI)。 | 是 |
| `language` | `string` | 訂單的語言識別碼 (例如 "en")。 | 是 |
| `market` | `string` | 訂單的市場識別碼 (例如 "US")。 | 是 |
| `orderId` | `string` | 識別特定使用者之訂單的識別碼。 | 是 |
| `orderLineItems` | `list<OrderLineItemV8>` | 訂單的明細項目清單。一般而言，每筆訂單有一個明細項目。 | 是 |
| `orderState` | `string` | 訂單的狀態。有效狀態為 `Editing`、`CheckingOut`、`Pending`、`Purchased`、`Refunded`、`ChargedBack` 和 `Canceled`。 | 是 |
| `orderValidityEndTime` | `string` | 訂單定價結束的時間，免費應用程式不適用。 | 是 |
| `orderValidityStartTime` | `string` | 訂單定價開始的時間，免費應用程式不適用。 | 是 |
| `purchaser` | `IdentityV6` | 描述購買者身分識別的物件。 | 是 |
| `totalAmount` | `decimal` | 訂單中所有項目的含稅購買總金額。 | 是 |
| `totalAmountBeforeTax` | `decimal` | 訂單中所有項目的稅前購買總金額。 | 是 |
| `totalChargedToCsvTopOffPI` | `decimal` | 如果使用不同的付款方式和儲值 (逗號分隔值 (CSV))，則為向 CSV 收取的金額。 | 是 |
| `totalTaxAmount` | `decimal` | 所有明細項目的稅額總計。 | 是 |

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

| 參數 | 類型 | 描述 | 必要 |
| - | - | - | - |
| `client` | `string` | 建立訂單的用戶端識別碼。 | 否 |

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

| 參數 | 類型 | 描述 | 必要 |
| - | - | - | - |
| `agent` | `IdentityV8` | 最後編輯明細項目的代理程式。如需此物件的詳細資訊，請參閱下表。 | 否 |
| `availabilityId` | `string` | 要從 Microsoft Store 目錄購買之產品的可用性識別碼。 | 是 |
| `beneficiary` | `IdentityV8` | 訂單受益人的身分識別。 | 否 |
| `billingState` | `string` | 訂單的計費狀態。完成時設定為 `Charged`。 | 否 |
| `campaignId` | `string` | 此訂單的行銷活動識別碼。 | 否 |
| `currencyCode` | `string` | 用於價格詳細資料的貨幣代碼。 | 是 |
| `description` | `string` | 明細項目的當地語系化描述。 | 是 |
| `devofferId` | `string` | 特定訂單的供應項目識別碼 (如果有的話)。 | 否 |
| `fulfillmentDate` | `datetimeoffset` | 發生履行的日期。 | 否 |
| `fulfillmentState` | `string` | 項目的履行狀態。完成時設定為 `Fulfilled`。 | 否 |
| `isPIRequired` | `boolean` | 指出此明細項目是否需要付款方式。 | 是 |
| `isTaxIncluded` | `boolean` | 指出項目的定價詳細資料中是否包含稅金。 | 是 |
| `legacyBillingOrderId` | `string` | 舊版計費識別碼。 | 否 |
| `lineItemId` | `string` | 此訂單中項目的明細項目識別碼。 | 是 |
| `listPrice` | `decimal` | 此訂單中項目的定價。 | 是 |
| `productId` | `string` | Microsoft Store 目錄中代表該明細項目之[產品](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities)的 [Store ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids)。產品的 Store ID 範例為 9NBLGGH42CFD。 | 是 |
| `productType` | `string` | 產品的類型。支援的值為 `Durable`、`Application` 和 `UnmanagedConsumable`。 | 是 |
| `quantity` | `int` | 所訂購項目的數量。 | 是 |
| `retailPrice` | `decimal` | 所訂購項目的零售價格。 | 是 |
| `revenueRecognitionState` | `string` | 營收認列狀態。 | 是 |
| `skuId` | `string` | Microsoft Store 目錄中明細項目 [SKU](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities) 的 [Store ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids)。SKU 的 Store ID 範例為 0010。 | 是 |
| `taxAmount` | `decimal` | 明細項目的稅額。 | 是 |
| `taxType` | `string` | 適用稅金的稅別。 | 是 |
| `Title` | `string` | 明細項目的當地語系化標題。 | 是 |
| `totalAmount` | `decimal` | 明細項目的含稅購買總金額。 | 是 |

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

| 參數 | 類型 | 描述 | 必要 |
| - | - | - | - |
| `identityType` | `string` | 包含值 `"pub"`。 | 是 |
| `identityValue` | `string` | 來自指定 User Store ID 金鑰之 *publisherUserId* 的字串值。 | 是 |

### 回應範例

```syntax theme={null}
Content-Length: 1203
Content-Type: application/json
MS-CorrelationId: fb2e69bc-f26a-4aab-a823-7586c19f5762
MS-RequestId: c1bc832c-f742-47e4-a76c-cf061402f698
MS-CV: XfrNWLQlEaux6Mt.8
MS-ServerId: 030032362
Date: Tue, 13 Oct 2019 21:21:51 GMT

{
    "clientContext": {
        "client": "86b78998-d05a-487b-b380-6c738f6553ea"
    },
    "createdTime": "2015-10-13T21:21:51.1863494+00:00",
    "currencyCode": "USD",
    "isPIRequired": false,
    "language": "en-us",
    "market": "us",
    "orderId": "3eea1529-611e-4aee-915c-345494e4ee76",
    "orderLineItems": [{
        "availabilityId": "9RT7C09D5J3W",
        "beneficiary": {
            "identityType": "pub",
            "identityValue": "user1"
        },
        "billingState": "Charged",
        "currencyCode": "USD",
        "description": "Jewels, Jewels, Jewels - Consumable 2",
        "fulfillmentDate": "2015-10-13T21:21:51.639478+00:00",
        "fulfillmentState": "Fulfilled",
        "isPIRequired": false,
        "isTaxIncluded": true,
        "lineItemId": "2814d758-3ee3-46b3-9671-4fb3bdae9ffe",
        "listPrice": 0.0,
        "payments": [],
        "productId": "9NBLGGH5WVP6",
        "productType": "UnmanagedConsumable",
        "quantity": 1,
        "retailPrice": 0.0,
        "revenueRecognitionState": "None",
        "skuId": "0010",
        "taxAmount": 0.0,
        "taxType": "NoApplicableTaxes",
        "title": "Jewels, Jewels, Jewels - Consumable 2",
        "totalAmount": 0.0
    }],
    "orderState": "Purchased",
    "orderValidityEndTime": "2015-10-14T21:21:51.1863494+00:00",
    "orderValidityStartTime": "2015-10-13T21:21:51.1863494+00:00",
    "purchaser": {
        "identityType": "pub",
        "identityValue": "user1"
    },
    "testScenarios": "None",
    "totalAmount": 0.0,
    "totalTaxAmount": 0.0
}
```

## 錯誤碼

| 代碼 | 錯誤 | 內部錯誤碼 | 描述 |
| - | - | - | - |
| 401 | Unauthorized | AuthenticationTokenInvalid | Microsoft Entra ID 存取權杖無效。在某些情況下，ServiceError 詳細資料會包含更多資訊，例如權杖已過期或缺少 *appid* 宣告時。 |
| 401 | Unauthorized | PartnerAadTicketRequired | 未在授權標頭中將 Microsoft Entra ID 存取權杖傳遞給服務。 |
| 401 | Unauthorized | InconsistentClientId | User Store ID 金鑰中的 `clientId` 宣告與存取權杖中的 `appid` 不相符。 |
| 400 | BadRequest | InvalidParameter | 詳細資料包含與要求本文相關的資訊，以及哪些欄位具有無效值。 |

## 相關文章

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

[要求 User Store ID 以進行服務對服務驗證](https://learn.microsoft.com/reference/xstore-requesting-a-userstoreid)

[更新 Microsoft Store ID 金鑰](https://learn.microsoft.com/reference/xstore-renew-a-user-store-id-key)


## Related topics

- [purchase.mp.microsoft.com/v8.0/purchases/grant](/reference/microsoft-store-apis/xstore-v8-grant.md)
- [purchase.mp.microsoft.com/v8.0/b2b/orders/query](/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)
- [purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](/reference/microsoft-store-apis/xstore-v8-recurrence-query.md)