> ## 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 Entra ID 認証を使用して、無料のアプリまたはアドオンをユーザーのアカウントに直接付与できる Microsoft Store v8 の purchases/grant API。

Microsoft Store 購入 API を使用して、無料のアプリまたはアドオンをユーザーのアカウントに付与します。

ユーザーのアカウントに直接付与できるのは無料の製品のみです。
有料の製品を付与しようとすると、エラーが返されます。

## 前提条件

[サービス間 API の前提条件](/ja-jp/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` | 必須。`Bearer` \<*token*> の形式の Microsoft Entra ID サービス アクセス トークン。 |
| `Host` | `string` | 値 `purchase.mp.microsoft.com` に設定する必要があります。 |
| `Content-Length` | `number` | 要求本文の長さ。 |
| `Content-Type` | `string` | 要求と応答の種類を指定します。現在サポートされている値は `application/json` のみです。 |

### 要求本文

| パラメーター | 型 | 説明 | 必須 |
| - | - | - | - |
| `availabilityId` | `string` | Microsoft Store カタログから付与する製品の可用性 ID。 | はい |
| `b2bKey` | `string` | 製品を付与するユーザーの ID を表す [User Store ID キー](/ja-jp/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)の[ストア ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids)。製品のストア 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) の[ストア ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids)。SKU のストア 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>` | 注文の明細項目のリスト。通常、注文ごとに 1 つの明細項目があります。 | はい |
| `orderState` | `string` | 注文の状態。有効な状態は `Editing`、`CheckingOut`、`Pending`、`Purchased`、`Refunded`、`ChargedBack`、`Canceled` です。 | はい |
| `orderValidityEndTime` | `string` | 注文の価格設定が終了する日時。無料のアプリには該当しません。 | はい |
| `orderValidityStartTime` | `string` | 注文の価格設定が開始する日時。無料のアプリには該当しません。 | はい |
| `purchaser` | `IdentityV6` | 購入者の ID を表すオブジェクト。 | はい |
| `totalAmount` | `decimal` | 税金を含む、注文内のすべての項目の購入合計金額。 | はい |
| `totalAmountBeforeTax` | `decimal` | 税引前の、注文内のすべての項目の購入合計金額。 | はい |
| `totalChargedToCsvTopOffPI` | `decimal` | 別の支払い方法とストアド バリュー (CSV (Currency Stored Value)) を使用している場合に、CSV に請求された金額。 | はい |
| `totalTaxAmount` | `decimal` | すべての明細項目の税額の合計。 | はい |

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

| パラメーター | 型 | 説明 | 必須 |
| - | - | - | - |
| `client` | `string` | 注文を作成したクライアント ID。 | いいえ |

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

| パラメーター | 型 | 説明 | 必須 |
| - | - | - | - |
| `agent` | `IdentityV8` | 明細項目を最後に編集したエージェント。このオブジェクトの詳細については、次の表を参照してください。 | いいえ |
| `availabilityId` | `string` | Microsoft Store カタログから購入する製品の可用性 ID。 | はい |
| `beneficiary` | `IdentityV8` | 注文の受益者の ID。 | いいえ |
| `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)の[ストア ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids)。製品のストア 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) の[ストア ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids)。SKU のストア 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 アクセス トークンが無効です。トークンの有効期限が切れている場合や *appid* 要求がない場合など、ServiceError の詳細に追加情報が含まれることがあります。 |
| 401 | Unauthorized | PartnerAadTicketRequired | Microsoft Entra ID アクセス トークンが Authorization ヘッダーでサービスに渡されませんでした。 |
| 401 | Unauthorized | InconsistentClientId | User Store ID キーの `clientId` 要求とアクセス トークンの `appid` が一致しません。 |
| 400 | BadRequest | InvalidParameter | 詳細には、要求本文と、無効な値を持つフィールドに関する情報が含まれます。 |

## 関連記事

[サービスからの製品の管理](/ja-jp/publishing/xstore-commerce/xstore-authenticating-service.md)

[サービス間認証のための User Store ID の要求](/ja-jp/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 (目次)](/ja-jp/reference/microsoft-store-apis/xstore-nav.md)
- [purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](/ja-jp/reference/microsoft-store-apis/xstore-v8-recurrence-query.md)
- [purchase.mp.microsoft.com/v8.0/b2b/orders/query](/ja-jp/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)
- [purchase.mp.microsoft.com/v8.0/b2b/clawback/sastoken](/ja-jp/reference/microsoft-store-apis/xstore-v8-clawbackv2-sastoken.md)
- [X-Token または OAuth 2.0 を使用したサービスからのユーザー Store ID の要求](/ja-jp/publishing/xstore-commerce/xstore-requesting-userstoreid-oauth.md)