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

# API de modification de récurrence d'abonnement de Microsoft Store v8

> Point de terminaison de modification des récurrences de Microsoft Store v8 qui permet à un service de jeu d'annuler, de prolonger ou de rembourser la récurrence d'abonnement d'un utilisateur par ID de récurrence.

<Note>
  Cette API fonctionne uniquement si l'abonnement est publié dans RETAIL. Si vous utilisez un sandbox de développement, publiez d'abord l'abonnement dans un groupe de version d'évaluation privé ou en tant qu'élément masqué dans RETAIL, avant d'appeler cette API. Si l'abonnement n'est pas publié dans RETAIL, la réponse est une erreur HTTP 400 avec un message indiquant « Requested catalog product data wasn't found. »
</Note>

Ce point de terminaison est utilisé pour modifier l'état de facturation du produit d'abonnement de l'utilisateur dans le Microsoft Store.
Vous pouvez annuler, prolonger ou rembourser un abonnement, ou en désactiver le renouvellement automatique.

La [bibliothèque Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services) fournit les fonctionnalités de cette méthode au moyen de l'API StoreServicesClient.RecurrenceChangeAsync.

## 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 retourner aucun résultat.

## Requête

### Syntaxe de la requête

| Méthode | URI de la requête |
| - | - |
| `POST` | `purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change` |

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

| En-tête | Type | Description |
| - | - | - |
| `Authorization` | `string` | Obligatoire. Le jeton d'accès au 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`. |

### Paramètres de la requête

| En-tête | Type | Description | Obligatoire |
| - | - | - | - |
| `recurrenceId` | `string` | Unique à l'abonnement de l'utilisateur; il s'agit de la même valeur que `id` de l'[API RecurrenceQuery](/fr-CA/reference/microsoft-store-apis/xstore-v8-recurrence-query) et que `recurrenceData` de l'[API de requête Collections](/fr-CA/reference/microsoft-store-apis/xstore-v9-query-for-products). | Oui |

### Corps de la requête

| Paramètre | Type | Description | Obligatoire |
| - | - | - | - |
| `b2bKey` | `string` | Le User Purchase ID qui représente l'identité de l'utilisateur pour lequel vous effectuez la requête. Consultez [Clé User Store ID](https://learn.microsoft.com/reference/xstore-requesting-a-userstoreid#step-4-create-a-user-store-id-key). | Oui |
| `changeType` | `string` | Identifie le type de modification que vous souhaitez effectuer. Consultez le tableau [Opérations de type de modification](#change-type-operations) pour connaître les valeurs possibles. | Oui |
| `extensionTimeInDays` | `string` | Si le paramètre changeType a la valeur Extend, ce paramètre spécifie le nombre de jours de prolongation de l'abonnement. Dans les scénarios de test, ce nombre peut être négatif afin de retirer des jours de l'abonnement. | Oui, si changeType a la valeur *Extend*; sinon, non. |
| `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 par défaut est RETAIL. L'authentification par X-Token n'a pas besoin de cette valeur, car le Sandbox est spécifié dans le X-Token. | Non |

### Opérations de type de modification

| Type de modification | Description |
| - | - |
| `Cancel` | Annule l'abonnement. |
| `Extend` | Prolonge l'abonnement. Si vous spécifiez cette valeur, vous devez également inclure le paramètre `extensionTimeInDays` dans le corps de la requête. |
| `Refund` | Rembourse l'abonnement au client. |
| `ToggleAutoRenew` | Désactive le renouvellement automatique de l'abonnement. Si le renouvellement automatique est déjà désactivé pour l'abonnement, cette valeur n'a aucun effet. |

### Exemple de requête

L'exemple suivant montre comment utiliser cette méthode pour prolonger la période d'abonnement de cinq jours. Remplacez la valeur b2bKey par la clé User Store ID qui représente l'identité de l'utilisateur dont vous souhaitez modifier l'abonnement.

```html theme={null}
POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac/change HTTP/1.1
Authorization: Bearer <your access token>
Content-Type: application/json
Host: https://purchase.mp.microsoft.com

{
  "b2bKey":  "eyJ0eXAiOiJ...",
  "changeType": "Extend",
  "extensionTimeInDays": "5"
}
```

## Réponse

Cette méthode retourne un corps de réponse JSON décrivant l'extension d'abonnement mise à jour, y compris les champs modifiés.

<Note>
  Cette méthode est soumise à la même exigence de publication dans RETAIL que celle décrite au début de cet article.
</Note>

### Corps de la réponse

| Paramètre | Type | Description | Obligatoire |
| - | - | - | - |
| `continuationToken` | `string` | S'il existe plusieurs ensembles de produits, ce jeton est retourné lorsque la limite de page est atteinte. Vous pouvez spécifier ce jeton de continuation dans les appels suivants pour récupérer les produits restants. | Non |
| `items` | `list<RecurrenceItem>` | Un tableau de produits pour l'utilisateur spécifié. Pour plus d'informations, consultez le tableau suivant. | Oui |

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

| Paramètre | Type | Description | Obligatoire |
| - | - | - | - |
| `autoRenew` | `bool` | Indique si l'utilisateur est inscrit au renouvellement automatique de son abonnement à la fin du prochain cycle de facturation. | Oui |
| `beneficiary` | `string` | Le Publisher ID du bénéficiaire dans le User Purchase ID. | Oui |
| `expirationTime` | `DateTime` | La date et l'heure UTC d'expiration de l'abonnement. | Oui |
| `expirationTimeWithGrace` | `DateTime` | La date et l'heure UTC de fin de la période de grâce de l'utilisateur si le renouvellement automatique échoue à l'ExpirationTime. Pendant la période de grâce, les utilisateurs devraient toujours avoir accès et être considérés comme des abonnés valides, mais être avisés qu'ils doivent corriger leur paiement de renouvellement automatique. | Oui |
| `id` | `string` | Un ID qui distingue cet article de collection des autres articles que possède l'utilisateur. Cet ID est unique par produit. | Oui |
| `isTrial` | `bool` | Indique si le produit est dans une période d'essai, comme pour un abonnement. | Oui |
| `lastModified` | `DateTime` | La date UTC de la dernière modification de cet article. | Oui |
| `market` | `string` | Le pays ou la région où le produit a été acheté, selon le code de pays/région ISO 3166 à deux caractères. Ex. : US. | Oui |
| `productId` | `string` | Également appelé Store ID du produit dans le catalogue du Microsoft Store. Un exemple de Store ID pour un produit est 9NBLGGH42CFD. | Oui |
| `recurrenceState` | `string` | État actuel de la récurrence. Consultez États de récurrence. | Oui |
| `skuId` | `string` | L'identificateur de SKU spécifique s'il existe plusieurs offres du produit dans le catalogue du Microsoft Store. Un exemple de Store ID pour un SKU est 0010. | Oui |
| `startTime` | `DateTime` | La date UTC de début de l'abonnement. | Oui |
| `cancellationDate` | `DateTime` | La date UTC d'annulation de l'abonnement. | Non |

### États de récurrence

| Valeur | Description |
| - | - |
| `None` | Indique un abonnement perpétuel. |
| `Active` | L'abonnement est valide et l'utilisateur a droit aux avantages de l'abonnement. |
| `Inactive` | L'abonnement a dépassé sa date d'expiration et l'utilisateur a désactivé l'option de renouvellement automatique de l'abonnement. |
| `Canceled` | L'abonnement a été résilié volontairement avant la date d'expiration, avec ou sans remboursement. |
| `InDunning` | L'abonnement est en recouvrement (c'est-à-dire que l'abonnement approche de son expiration et que Microsoft tente d'obtenir les fonds nécessaires pour le renouveler automatiquement). Si la date actuelle est antérieure à la valeur expirationTimeWithGrace, l'utilisateur devrait toujours avoir droit aux avantages de l'abonnement. Si la date actuelle est postérieure à la valeur expirationTimeWithGrace, l'utilisateur ne devrait pas avoir accès aux avantages de l'abonnement. |
| `Failed` | La période de recouvrement est terminée et le renouvellement de l'abonnement a échoué après plusieurs tentatives. |

* *Inactive/Canceled/Failed* sont des états terminaux. Lorsqu'un abonnement entre dans l'un de ces états, l'utilisateur doit racheter l'abonnement pour l'activer de nouveau. L'utilisateur n'a pas le droit d'utiliser les services dans ces états.
* Lorsqu'un abonnement est Canceled, `expirationTime` est mis à jour avec la date et l'heure de l'annulation.
* L'ID de l'abonnement reste le même pendant toute sa durée de vie. Il ne change pas lorsque l'option de renouvellement automatique est activée ou désactivée. Si un utilisateur rachète un abonnement après avoir atteint un état terminal, un nouvel ID d'abonnement sera créé.
* L'ID d'un abonnement doit être utilisé pour exécuter toute opération sur un abonnement individuel.
* Lorsqu'un utilisateur rachète un abonnement après l'avoir annulé ou interrompu, si vous interrogez les résultats de cet utilisateur, vous obtiendrez deux entrées : une avec l'ancien ID d'abonnement dans un état terminal, et une avec le nouvel ID d'abonnement dans un état actif.
* Il est toujours recommandé de vérifier à la fois recurrenceState et `expirationTime`, car les mises à jour de `recurrenceState` peuvent être retardées de quelques minutes (ou parfois de quelques heures).

### Exemple de réponse

```json theme={null}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 431
ms-correlationid: 95b2aee4-1118-437b-8910-a2f7d84d0766
ms-cv: Kl684e1htkqb19Ch.0
Date: Thu, 03 Mar 2022 23:19:12 GMT

{
    "autoRenew": true,
    "beneficiary": "pub:NoUserIdProvided",
    "expirationTime": "2022-03-03T23:59:59.00+00:00",
    "expirationTimeWithGrace": "2022-03-17T23:59:59.00+00:00",
    "id": "mdr:0:3172048a2d1849ba9a24fd305854d4a8:cedca1d3-9580-4229-9cb5-f00c4547078c",
    "isTrial": false,
    "lastModified": "2022-03-03T23:19:12.26+00:00",
    "market": "US",
    "productId": "CFQ7TTC0HC8Z",
    "skuId": "0003",
    "startTime": "2022-03-03T00:00:00.00+00:00",
    "recurrenceState": "Active"
}

```

## Articles connexes

[purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](/fr-CA/reference/microsoft-store-apis/xstore-v8-recurrence-query)

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

[Gestion des remboursements et des rétrofacturations à partir de votre service](https://learn.microsoft.com/reference/xstore-managing-refunds-and-chargebacks)

[Authentification de votre service avec les API du Microsoft Store](https://learn.microsoft.com/reference/xstore-authenticating-your-service)

[Utilisation de publisherQuery (Collections v9) pour interroger les produits et les droits d'utilisation d'un utilisateur](/fr-CA/reference/microsoft-store-apis/xstore-v9-query-for-products)


## Related topics

- [API b2bLicensePreview de Collections v8 de Microsoft Store](/es/reference/microsoft-store-apis/xstore-v8-query-for-products.md)
- [Autenticación de su servicio con las API de Microsoft Store](/es/publishing/xstore-commerce/xstore-authenticating-service.md)
- [APIs de servicio de Microsoft Store](/es/reference/microsoft-store-apis/xstore-nav.md)
- [Administración de productos de suscripción desde su servicio](/es/publishing/xstore-commerce/xstore-managing-subscriptions.md)
- [Mises à niveau de compte](/fr/services/playfab/pricing/account-upgrades.md)