> ## 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

> API purchases/grant de Microsoft Store v8 qui permet à un service de jeu d'accorder une application ou un module complémentaire gratuit directement au compte d'un utilisateur au moyen de l'authentification Microsoft Entra ID.

Utilisez l'API d'achat du Microsoft Store pour accorder une application ou un module complémentaire gratuit au compte d'un utilisateur.

Seuls les produits gratuits peuvent être accordés directement au compte d'un utilisateur.
Les tentatives d'octroi de produits payants retournent une erreur.

## Prérequis

Consultez [Prérequis pour les API de service à service](https://learn.microsoft.com/reference/service-to-service-nav#prerequisites-for-service-to-service-apis).

Cette API prend uniquement en charge le type d'authentification Microsoft Entra ID.

Si la configuration du produit n'est pas publiée dans Partner Center, les appels peuvent réussir, mais ne retourner aucun résultat.

## Requête

### Syntaxe de la requête

| Méthode | URI de la requête |
| - | - |
| `POST` | `https://purchase.mp.microsoft.com/v7.0/purchases/grant` |

### En-tête de la requête

| En-tête | Type | Description |
| - | - | - |
| `Authorization` | `string` | Obligatoire. Le jeton d'accès de service Microsoft Entra ID sous la forme `Bearer` \<*jeton*>. |
| `Host` | `string` | Doit être défini sur la valeur `purchase.mp.microsoft.com`. |
| `Content-Length` | `number` | La longueur du corps de la requête. |
| `Content-Type` | `string` | Spécifie le type de la requête et de la réponse. Actuellement, la seule valeur prise en charge est `application/json`. |

### Corps de la requête

| Paramètre | Type | Description | Obligatoire |
| - | - | - | - |
| `availabilityId` | `string` | L'ID de disponibilité du produit à accorder à partir du catalogue du Microsoft Store. | Oui |
| `b2bKey` | `string` | La [clé User Store ID](https://learn.microsoft.com/reference/xstore-requesting-a-userstoreid#step-4-create-a-user-store-id-key) qui représente l'identité de l'utilisateur auquel vous souhaitez accorder un produit. | Oui |
| `devOfferId` | `string` | Un ID d'offre spécifié par le développeur qui apparaît dans l'article de la collection après l'achat. | Non |
| `language` | `string` | La langue de l'utilisateur. | Oui |
| `market` | `string` | Le marché de l'utilisateur. | Oui |
| `orderId` | `GUID` | Un GUID généré pour la commande. Cette valeur est unique pour l'utilisateur, mais elle n'a pas besoin d'être unique parmi toutes les commandes. | Oui |
| `productId` | `string` | Le [Store ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids) du [produit](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities) dans le catalogue du Microsoft Store. Un exemple de Store ID de produit est 9NBLGGH42CFD. | Oui |
| `quantity` | `int` | La quantité à acheter. Actuellement, la seule valeur prise en charge est 1. Si elle n'est pas spécifiée, la valeur par défaut est 1. | Non |
| `skuId` | `string` | Le [Store ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids) de la [SKU](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities) du produit dans le catalogue du Microsoft Store. Un exemple de Store ID de SKU est 0010. | Oui |
| `sbx` | `string` | Valeur facultative pour l'authentification avec des UserStoreIds qui spécifie le bac à sable auquel les résultats doivent être limités. Sans cette valeur, le bac à sable RETAIL est utilisé par défaut. L'authentification X-Token n'a pas besoin de cette valeur, car le bac à sable est spécifié dans le X-Token. | Non |

### Exemple de requête

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

## Réponse

### Corps de la réponse

| Paramètre | Type | Description | Obligatoire |
| - | - | - | - |
| `clientContext` | `ClientContextV8` | Les informations contextuelles du client pour la commande. Attribué à la valeur `clientID` du jeton Microsoft Entra ID. | Oui |
| `createdtime` | `datetimeoffset` | L'heure à laquelle la commande a été créée. | Oui |
| `currencyCode` | `string` | Le code de devise pour `totalAmount` et `totalTaxAmount`. Sans objet pour les articles gratuits. | Oui |
| `friendlyName` | `string` | Le nom convivial de la commande. Sans objet pour les commandes passées au moyen de l'API d'achat du Microsoft Store. | Oui |
| `isPIRequired` | `boolean` | Indique si un instrument de paiement (PI) est requis dans le cadre du bon de commande. | Oui |
| `language` | `string` | L'ID de langue de la commande (par exemple, "en"). | Oui |
| `market` | `string` | L'ID de marché de la commande (par exemple, "US"). | Oui |
| `orderId` | `string` | Un ID qui identifie la commande pour un utilisateur particulier. | Oui |
| `orderLineItems` | `list<OrderLineItemV8>` | La liste des articles de ligne de la commande. En général, il y a un article de ligne par commande. | Oui |
| `orderState` | `string` | L'état de la commande. Les états valides sont `Editing`, `CheckingOut`, `Pending`, `Purchased`, `Refunded`, `ChargedBack` et `Canceled`. | Oui |
| `orderValidityEndTime` | `string` | Moment où la tarification de la commande prend fin; sans objet pour les applications gratuites. | Oui |
| `orderValidityStartTime` | `string` | Moment où la tarification de la commande commence; sans objet pour les applications gratuites. | Oui |
| `purchaser` | `IdentityV6` | Un objet qui décrit l'identité de l'acheteur. | Oui |
| `totalAmount` | `decimal` | Le montant total de l'achat de tous les articles de la commande, taxes incluses. | Oui |
| `totalAmountBeforeTax` | `decimal` | Le montant total de l'achat de tous les articles de la commande, avant taxes. | Oui |
| `totalChargedToCsvTopOffPI` | `decimal` | En cas d'utilisation d'un instrument de paiement distinct et d'une valeur stockée (CSV), le montant facturé à la valeur stockée. | Oui |
| `totalTaxAmount` | `decimal` | Le montant total des taxes pour tous les articles de ligne. | Oui |

L'objet `ClientContext` contient les paramètres suivants.

| Paramètre | Type | Description | Obligatoire |
| - | - | - | - |
| `client` | `string` | L'ID du client qui a créé la commande. | Non |

L'objet `OrderLineItemV8` contient les paramètres suivants.

| Paramètre | Type | Description | Obligatoire |
| - | - | - | - |
| `agent` | `IdentityV8` | L'agent qui a modifié l'article de ligne en dernier. Pour plus d'informations sur cet objet, consultez le tableau suivant. | Non |
| `availabilityId` | `string` | L'ID de disponibilité du produit à acheter à partir du catalogue du Microsoft Store. | Oui |
| `beneficiary` | `IdentityV8` | L'identité du bénéficiaire de la commande. | Non |
| `billingState` | `string` | L'état de facturation de la commande. Défini sur `Charged` une fois terminée. | Non |
| `campaignId` | `string` | L'ID de campagne de cette commande. | Non |
| `currencyCode` | `string` | Le code de devise utilisé pour les détails de prix. | Oui |
| `description` | `string` | Une description localisée de l'article de ligne. | Oui |
| `devofferId` | `string` | L'ID d'offre de la commande particulière, s'il est présent. | Non |
| `fulfillmentDate` | `datetimeoffset` | La date à laquelle l'exécution a eu lieu. | Non |
| `fulfillmentState` | `string` | L'état de l'exécution de l'article. Défini sur `Fulfilled` une fois terminée. | Non |
| `isPIRequired` | `boolean` | Indique si un instrument de paiement est requis pour cet article de ligne. | Oui |
| `isTaxIncluded` | `boolean` | Indique si les taxes sont incluses dans les détails de prix de l'article. | Oui |
| `legacyBillingOrderId` | `string` | L'ancien ID de facturation. | Non |
| `lineItemId` | `string` | L'ID d'article de ligne de l'article dans cette commande. | Oui |
| `listPrice` | `decimal` | Le prix courant de l'article dans cette commande. | Oui |
| `productId` | `string` | Le [Store ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids) du [produit](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities) qui représente l'article de ligne dans le catalogue du Microsoft Store. Un exemple de Store ID de produit est 9NBLGGH42CFD. | Oui |
| `productType` | `string` | Le type du produit. Les valeurs prises en charge sont `Durable`, `Application` et `UnmanagedConsumable`. | Oui |
| `quantity` | `int` | La quantité de l'article commandé. | Oui |
| `retailPrice` | `decimal` | Le prix de détail de l'article commandé. | Oui |
| `revenueRecognitionState` | `string` | L'état de comptabilisation des revenus. | Oui |
| `skuId` | `string` | Le [Store ID](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#store-ids) de la [SKU](https://learn.microsoft.com/windows/uwp/monetize/in-app-purchases-and-trials#products-skus-and-availabilities) de l'article de ligne dans le catalogue du Microsoft Store. Un exemple de Store ID de SKU est 0010. | Oui |
| `taxAmount` | `decimal` | Le montant des taxes pour l'article de ligne. | Oui |
| `taxType` | `string` | Le type de taxe pour les taxes applicables. | Oui |
| `Title` | `string` | Le titre localisé de l'article de ligne. | Oui |
| `totalAmount` | `decimal` | Le montant total de l'achat de l'article de ligne, taxes incluses. | Oui |

L'objet `IdentityV8` contient les paramètres suivants.

| Paramètre | Type | Description | Obligatoire |
| - | - | - | - |
| `identityType` | `string` | Contient la valeur `"pub"`. | Oui |
| `identityValue` | `string` | La valeur de chaîne du *publisherUserId* de la clé User Store ID spécifiée. | Oui |

### Exemple de réponse

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

## Codes d'erreur

| Code | Erreur | Code d'erreur interne | Description |
| - | - | - | - |
| 401 | Unauthorized | AuthenticationTokenInvalid | Le jeton d'accès Microsoft Entra ID n'est pas valide. Dans certains cas, les détails de ServiceError contiennent plus d'informations, par exemple lorsque le jeton est expiré ou que la revendication *appid* est manquante. |
| 401 | Unauthorized | PartnerAadTicketRequired | Aucun jeton d'accès Microsoft Entra ID n'a été transmis au service dans l'en-tête d'autorisation. |
| 401 | Unauthorized | InconsistentClientId | La revendication `clientId` de la clé User Store ID et l'`appid` du jeton d'accès ne correspondent pas. |
| 400 | BadRequest | InvalidParameter | Les détails contiennent des informations sur le corps de la requête et sur les champs dont la valeur n'est pas valide. |

## Articles connexes

[Gérer les produits à partir de vos services](https://learn.microsoft.com/reference/service-to-service-nav)

[Demande d'un User Store ID pour l'authentification de service à service](https://learn.microsoft.com/reference/xstore-requesting-a-userstoreid)

[Renouveler une clé 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)