> ## 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 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 à l'aide de l'authentification Microsoft Entra ID.

Utilisez l'API d'achat 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 renvoient 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, l'appel peut réussir mais ne renvoyer aucun résultat.

## Requête

### Syntaxe de la requête

| Méthode | URI de 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. Jeton d'accès au service Microsoft Entra ID au format `Bearer` \<*jeton*>. |
| `Host` | `string` | Doit être défini sur la valeur `purchase.mp.microsoft.com`. |
| `Content-Length` | `number` | 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` | ID de disponibilité du produit à accorder à partir du catalogue du Microsoft Store. | Oui |
| `b2bKey` | `string` | [Clé d'ID Store utilisateur](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` | ID d'offre spécifié par le développeur qui apparaît dans l'élément de collection après l'achat. | Non |
| `language` | `string` | Langue de l'utilisateur. | Oui |
| `market` | `string` | Marché de l'utilisateur. | Oui |
| `orderId` | `GUID` | GUID généré pour la commande. Cette valeur est unique pour l'utilisateur, mais elle n'a pas besoin d'être unique pour toutes les commandes. | Oui |
| `productId` | `string` | [ID Store](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. Exemple d'ID Store pour un produit : 9NBLGGH42CFD. | Oui |
| `quantity` | `int` | 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` | [ID Store](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. Exemple d'ID Store pour une SKU : 0010. | Oui |
| `sbx` | `string` | Valeur facultative pour l'authentification avec des UserStoreIds qui spécifie le sandbox auquel les résultats doivent être limités. Sans cette valeur, le sandbox RETAIL est utilisé par défaut. L'authentification X-Token n'a pas besoin de cette valeur, car le sandbox 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` | Informations contextuelles du client pour la commande. Affecté à la valeur `clientID` du jeton Microsoft Entra ID. | Oui |
| `createdtime` | `datetimeoffset` | Heure de création de la commande. | Oui |
| `currencyCode` | `string` | Code de devise pour `totalAmount` et `totalTaxAmount`. Non applicable pour les éléments gratuits. | Oui |
| `friendlyName` | `string` | Nom convivial de la commande. Non applicable pour les commandes passées à l'aide de l'API d'achat Microsoft Store. | Oui |
| `isPIRequired` | `boolean` | Indique si un instrument de paiement (PI) est requis dans le cadre du bon de commande. | Oui |
| `language` | `string` | ID de langue de la commande (par exemple, « en »). | Oui |
| `market` | `string` | ID de marché de la commande (par exemple, « US »). | Oui |
| `orderId` | `string` | ID qui identifie la commande pour un utilisateur particulier. | Oui |
| `orderLineItems` | `list<OrderLineItemV8>` | Liste des lignes de commande. En règle générale, il y a une ligne par commande. | Oui |
| `orderState` | `string` | État de la commande. Les états valides sont `Editing`, `CheckingOut`, `Pending`, `Purchased`, `Refunded`, `ChargedBack` et `Canceled`. | Oui |
| `orderValidityEndTime` | `string` | Date de fin de la tarification de la commande ; non applicable pour les applications gratuites. | Oui |
| `orderValidityStartTime` | `string` | Date de début de la tarification de la commande ; non applicable pour les applications gratuites. | Oui |
| `purchaser` | `IdentityV6` | Objet qui décrit l'identité de l'acheteur. | Oui |
| `totalAmount` | `decimal` | Montant total de l'achat de tous les éléments de la commande, taxes comprises. | Oui |
| `totalAmountBeforeTax` | `decimal` | Montant total de l'achat de tous les éléments de la commande, hors taxes. | Oui |
| `totalChargedToCsvTopOffPI` | `decimal` | En cas d'utilisation d'un instrument de paiement distinct et d'une valeur stockée (CSV, comma-separated value), montant facturé à la valeur stockée. | Oui |
| `totalTaxAmount` | `decimal` | Montant total des taxes pour toutes les lignes de commande. | Oui |

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

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

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

| Paramètre | Type | Description | Obligatoire |
| - | - | - | - |
| `agent` | `IdentityV8` | Agent qui a modifié la ligne de commande en dernier. Pour plus d'informations sur cet objet, consultez le tableau suivant. | Non |
| `availabilityId` | `string` | ID de disponibilité du produit à acheter à partir du catalogue du Microsoft Store. | Oui |
| `beneficiary` | `IdentityV8` | Identité du bénéficiaire de la commande. | Non |
| `billingState` | `string` | État de facturation de la commande. Défini sur `Charged` une fois terminé. | Non |
| `campaignId` | `string` | ID de campagne de cette commande. | Non |
| `currencyCode` | `string` | Code de devise utilisé pour les détails du prix. | Oui |
| `description` | `string` | Description localisée de la ligne de commande. | Oui |
| `devofferId` | `string` | ID d'offre de la commande concernée, le cas échéant. | Non |
| `fulfillmentDate` | `datetimeoffset` | Date à laquelle le traitement a eu lieu. | Non |
| `fulfillmentState` | `string` | État du traitement de l'élément. Défini sur `Fulfilled` une fois terminé. | Non |
| `isPIRequired` | `boolean` | Indique si un instrument de paiement est requis pour cette ligne de commande. | Oui |
| `isTaxIncluded` | `boolean` | Indique si les taxes sont incluses dans les détails de tarification de l'élément. | Oui |
| `legacyBillingOrderId` | `string` | ID de facturation hérité. | Non |
| `lineItemId` | `string` | ID de ligne de commande de l'élément dans cette commande. | Oui |
| `listPrice` | `decimal` | Prix catalogue de l'élément dans cette commande. | Oui |
| `productId` | `string` | [ID Store](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 la ligne de commande dans le catalogue du Microsoft Store. Exemple d'ID Store pour un produit : 9NBLGGH42CFD. | Oui |
| `productType` | `string` | Type du produit. Les valeurs prises en charge sont `Durable`, `Application` et `UnmanagedConsumable`. | Oui |
| `quantity` | `int` | Quantité commandée de l'élément. | Oui |
| `retailPrice` | `decimal` | Prix de vente de l'élément commandé. | Oui |
| `revenueRecognitionState` | `string` | État de la comptabilisation des revenus. | Oui |
| `skuId` | `string` | [ID Store](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 la ligne de commande dans le catalogue du Microsoft Store. Exemple d'ID Store pour une SKU : 0010. | Oui |
| `taxAmount` | `decimal` | Montant des taxes pour la ligne de commande. | Oui |
| `taxType` | `string` | Type de taxe pour les taxes applicables. | Oui |
| `Title` | `string` | Titre localisé de la ligne de commande. | Oui |
| `totalAmount` | `decimal` | Montant total de l'achat de la ligne de commande, taxes comprises. | Oui |

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

| Paramètre | Type | Description | Obligatoire |
| - | - | - | - |
| `identityType` | `string` | Contient la valeur `"pub"`. | Oui |
| `identityValue` | `string` | Valeur de chaîne du *publisherUserId* issue de la clé d'ID Store utilisateur 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 a 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é d'ID Store utilisateur 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 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 ID Store utilisateur pour l'authentification de service à service](https://learn.microsoft.com/reference/xstore-requesting-a-userstoreid)

[Renouveler une clé d'ID Microsoft Store](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)