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

> Microsoft Store v8 purchases/grant API，允许游戏服务使用 Microsoft Entra ID 身份验证将免费应用或加载项直接授予用户帐户。

使用 Microsoft Store 购买 API 将免费应用或加载项授予用户帐户。

只有免费产品可以直接授予用户帐户。
尝试授予付费产品将返回错误。

## 先决条件

请查看[服务到服务 API 的先决条件](https://devdocs.xbox.com/zh-CN/publishing/xstore-commerce/xstore-authenticating-service.md)。

此 API 仅支持 Microsoft Entra ID 身份验证类型。

如果你未在 Partner Center 中发布产品配置，调用可能成功但不返回任何结果。

## 请求

### 请求语法

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

### 请求标头

| 标头 | 类型 | 说明 |
| - | - | - |
| `Authorization` | `string` | 必需。Microsoft Entra ID 服务访问令牌，格式为 `Bearer` \<*token*>。 |
| `Host` | `string` | 必须设置为值 `purchase.mp.microsoft.com`。 |
| `Content-Length` | `number` | 请求正文的长度。 |
| `Content-Type` | `string` | 指定请求和响应类型。目前唯一支持的值为 `application/json`。 |

### 请求正文

| 参数 | 类型 | 说明 | 必需 |
| - | - | - | - |
| `availabilityId` | `string` | Microsoft Store 目录中要授予的产品的可用性 ID。 | 是 |
| `b2bKey` | `string` | [User Store ID 密钥](https://devdocs.xbox.com/zh-CN/publishing/xstore-commerce/xstore-requesting-userstoreid.md#step-4-create-a-user-store-id-key)，表示你要为其授予产品的用户的标识。 | 是 |
| `devOfferId` | `string` | 开发者指定的套餐 ID，购买后会显示在收藏项目中。 | 否 |
| `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` | 使用 UserStoreId 进行身份验证时的可选值，用于指定结果的沙盒范围。如果不提供此值，则默认为 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` | 订单的语言 ID（例如 "en"）。 | 是 |
| `market` | `string` | 订单的市场 ID（例如 "US"）。 | 是 |
| `orderId` | `string` | 标识特定用户订单的 ID。 | 是 |
| `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` | 创建订单的客户端 ID。 | 否 |

`OrderLineItemV8` 对象包含以下参数。

| 参数 | 类型 | 说明 | 必需 |
| - | - | - | - |
| `agent` | `IdentityV8` | 上次编辑行项目的代理。有关此对象的详细信息，请参阅下表。 | 否 |
| `availabilityId` | `string` | Microsoft Store 目录中要购买的产品的可用性 ID。 | 是 |
| `beneficiary` | `IdentityV8` | 订单受益人的标识。 | 否 |
| `billingState` | `string` | 订单的计费状态。完成后设置为 `Charged`。 | 否 |
| `campaignId` | `string` | 此订单的营销活动 ID。 | 否 |
| `currencyCode` | `string` | 用于价格详细信息的货币代码。 | 是 |
| `description` | `string` | 行项目的本地化说明。 | 是 |
| `devofferId` | `string` | 特定订单的套餐 ID（如果存在）。 | 否 |
| `fulfillmentDate` | `datetimeoffset` | 履行发生的日期。 | 否 |
| `fulfillmentState` | `string` | 项目的履行状态。完成后设置为 `Fulfilled`。 | 否 |
| `isPIRequired` | `boolean` | 指示此行项目是否需要付款方式。 | 是 |
| `isTaxIncluded` | `boolean` | 指示项目的定价详细信息中是否包含税款。 | 是 |
| `legacyBillingOrderId` | `string` | 旧版计费 ID。 | 否 |
| `lineItemId` | `string` | 此订单中项目的行项目 ID。 | 是 |
| `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://devdocs.xbox.com/zh-CN/publishing/xstore-commerce/xstore-authenticating-service.md)

[请求用于服务到服务身份验证的 User Store ID](https://devdocs.xbox.com/zh-CN/publishing/xstore-commerce/xstore-requesting-userstoreid.md)

[续订 Microsoft Store ID 密钥](https://learn.microsoft.com/reference/xstore-renew-a-user-store-id-key)


## Related topics

- [Microsoft Store 服务 API（内容）](https://devdocs.xbox.com/zh-CN/reference/microsoft-store-apis/xstore-nav.md)
- [purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](https://devdocs.xbox.com/zh-CN/reference/microsoft-store-apis/xstore-v8-recurrence-query.md)
- [purchase.mp.microsoft.com/v8.0/b2b/orders/query](https://devdocs.xbox.com/zh-CN/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)
- [purchase.mp.microsoft.com/v8.0/b2b/clawback/sastoken](https://devdocs.xbox.com/zh-CN/reference/microsoft-store-apis/xstore-v8-clawbackv2-sastoken.md)
- [purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change](https://devdocs.xbox.com/zh-CN/reference/microsoft-store-apis/xstore-v8-recurrence-change.md)