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

# Gestion des produits d'abonnement depuis votre service

> Décrit comment utiliser le service Recurrence pour interroger et gérer vos produits d'abonnement et gérer les différents états d'abonnement d'un utilisateur.

Pour les produits d'abonnement, utilisez un service back-end pour valider l'état et gérer les opérations de cycle de vie. Les API Recurrence offrent à vos équipes de support et de live-ops un moyen fiable d'inspecter, de prolonger ou d'annuler des abonnements.

Cet article explique comment utiliser les points de terminaison Recurrence pour ces scénarios.

## Utilisation de la bibliothèque .NET Microsoft.StoreServices et de l'exemple

Pour illustrer les principes et les flux décrits dans cet article, consultez l'exemple Microsoft.StoreServices. L'exemple utilise la bibliothèque Microsoft.StoreServices pour gérer l'authentification et effectuer les appels aux services du Microsoft Store. Le service d'exemple lui-même contient une logique d'exemple pour gérer les produits d'abonnement et fournit un guide de configuration pour sa mise en place.

* [Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services)
* [Exemple Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services-Sample)

## Types de produits d'abonnement

Les types de produits d'abonnement géré par le Store et d'abonnement de type extension fonctionnent tous deux avec le service Recurrence pour afficher et gérer l'abonnement de l'utilisateur. Pour plus d'informations sur chacun de ces types de produits, consultez [Choix du type de produit approprié](/fr/publishing/xstore-commerce/xstore-choosing-product-type#subscriptions)

## Interrogation de l'abonnement d'un utilisateur

Utilisez [purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](/fr/reference/microsoft-store-apis/xstore-v8-recurrence-query) comme point de terminaison principal pour l'état de l'abonnement. Il retourne les périodes d'abonnement actives et historiques, ainsi que le `subscriptionId` nécessaire aux opérations de modification. Il inclut également les champs requis pour distinguer les périodes de grâce (Grace) et de relance (Dunning).

Les API Collections ([b2bLicensePreview (v8)](/fr/reference/microsoft-store-apis/xstore-v8-query-for-products) et [publisherQuery (v9)](/fr/reference/microsoft-store-apis/xstore-v9-query-for-products)) peuvent indiquer un droit d'abonnement actif, mais pas le même niveau de détail sur la récurrence.

## Délai entre la satisfaction des vérifications de droits sur le client et en serveur à serveur

Lorsque vous publiez une mise à jour ajoutant de nouveaux éléments (droits satisfaisants) à un bundle, il existe un délai de visibilité des nouveaux éléments entre les requêtes d'API côté client et les requêtes d'API de serveur à serveur. Ce délai est dû au fait que les différents systèmes du Store mettent à jour leurs caches de catalogue à des intervalles différents. Lorsque la modification est publiée dans le catalogue, les services de licence locaux obtiennent généralement les informations mises à jour en premier, et les caches utilisés par publisherQuery deux à trois heures plus tard. Par conséquent, prévoyez quelques heures pendant lesquelles les API côté client accordent l'accès alors que vos appels de serveur à serveur ne reflètent pas encore la propriété des nouveaux éléments.

Le service Recurrence lui-même n'est pas affecté, seuls les points de terminaison publisherQuery ou b2bLicensePreview qui interrogent les droits satisfaisants sur les éléments nouvellement ajoutés le sont.

### Comprendre les dates de début, de renouvellement et d'expiration d'un abonnement

La date `StartTime` d'un abonnement est la date à laquelle l'abonnement actif a commencé. Si l'abonnement est configuré pour le renouvellement automatique, la date de début reste la même, mais les dates d'expiration changent à mesure que l'abonnement est renouvelé au cours des mois suivants. Si un abonnement est annulé, expiré ou révoqué, un nouvel objet d'abonnement est créé lorsque l'utilisateur achète à nouveau l'abonnement. La nouvelle période d'abonnement active a pour `StartTime` le jour où l'utilisateur a activé ou acheté le nouvel abonnement.

Les périodes d'abonnement dans le Microsoft Store sont normalement configurées sous forme de nombre de mois. Par exemple, 1 mois, 3 mois ou 12 mois. Lorsqu'un utilisateur achète un abonnement d'un mois, le `StartTime` est minuit UTC (00:00:00) du jour où il a commencé l'abonnement. `ExpirationTime` correspond au nombre de mois (et non de jours) ajouté au `StartTime`, moins une seconde (23:59:59 UTC).<br />Cette valeur permet à l'abonnement d'expirer juste avant minuit UTC.

Cependant, certains mois comportent un nombre de jours différent, ce qui crée un conflit pour les abonnements commençant le 29, le 30 ou le 31 d'un mois.<br />Si le `StartTime` de l'utilisateur tombe l'un de ces jours, l'`ExpirationTime` est modifié pour être 23:59:59 UTC le dernier jour du mois d'expiration. Ainsi, la date de renouvellement est toujours minuit UTC (00:00:00) le premier jour du mois par la suite, et l'`ExpirationTime` est toujours 23:59:59 UTC le dernier jour du mois.

#### Exemple de comportement des dates de début, de renouvellement et d'expiration d'un abonnement d'un mois

| Date d'achat | StartTime | ExpireTime | Date de renouvellement automatique | Jours actifs |
| - | - | - | - | - |
| 2023-02-27T12:00:00Z | 2023-02-27T00:00:00Z | 2023-03-26T23:59:59Z | 2023-03-27T00:00:00Z | 28 |
| 2023-03-27T12:00:00Z | 2023-03-27T00:00:00Z | 2023-04-26T23:59:59Z | 2023-05-27T00:00:00Z | 31 |
| 2023-03-29T12:00:00Z | 2023-03-29T00:00:00Z | 2023-04-30T23:59:59Z | 2023-05-01T00:00:00Z | 32 |
| 2023-04-29T12:00:00Z | 2023-04-29T00:00:00Z | 2023-05-31T23:59:59Z | 2023-06-01T00:00:00Z | 33 |
| 2023-04-30T12:00:00Z | 2023-04-30T00:00:00Z | 2023-05-31T23:59:59Z | 2023-06-01T00:00:00Z | 32 |
| 2024-02-27T12:00:00Z | 2024-02-27T00:00:00Z | 2024-03-26T23:59:59Z | 2024-03-27T00:00:00Z | 29 (année bissextile) |

### Comprendre les états Grace et Dunning

Si un paiement de renouvellement automatique échoue à l'`ExpirationTime`, l'abonnement passe en période de grâce (Grace), puis en période de relance (Dunning) si le problème n'est toujours pas résolu. Les deux périodes signalent l'état `InDunning` ; déterminez donc la période en cours en comparant l'heure UTC actuelle à `ExpirationTimeWithGrace`.

Lorsque l'abonnement d'un utilisateur est en période Grace ou Dunning, vous devez inviter les utilisateurs à vérifier l'état de leur facturation sur [Services et abonnements du compte Microsoft](https://account.microsoft.com/services).

Pour placer correctement un compte dans chacun de ces états à des fins de test, consultez [Test des produits d'abonnement](#testing-subscription-products).

#### Période de grâce (Grace)

Pendant la période Grace, maintenez les avantages de l'abonnement activés pendant que le Store retente le paiement du renouvellement. Si le renouvellement réussit, les jours de grâce utilisés sont déduits de la période suivante. Si le paiement n'est pas résolu avant `ExpirationTimeWithGrace`, l'abonnement passe en période Dunning.

#### Période de relance (Dunning)

La période Dunning commence à la fin de la période Grace. Désactivez les avantages de l'abonnement pendant cette période. Les utilisateurs ne peuvent pas racheter ni utiliser un code pour le même abonnement pendant la période Dunning. Si le paiement reste non résolu pendant toute la période Dunning, l'abonnement devient inactif.

### Durées des périodes Grace et Dunning

| Type d'abonnement | Durée de l'abonnement | Grace | Dunning (après Grace) |
| - | - | - | - |
| Abonnement de type extension | Toute | 3 jours | 39 jours |
| Abonnement géré par le Store | Toute | 7 jours | 36 jours |

## Modification de l'abonnement d'un utilisateur

Vos services peuvent également modifier les abonnements avec [purchase.mp.microsoft.com/v8.0/b2b/recurrences/](/fr/reference/microsoft-store-apis/xstore-v8-recurrence-change){recurrenceId}[/change](/fr/reference/microsoft-store-apis/xstore-v8-recurrence-change). Les opérations prises en charge incluent l'ajout de jours, la désactivation du renouvellement automatique et l'annulation de l'abonnement. Votre service a besoin du `recurrenceId` (même valeur que `id` de l'[API RecurrenceQuery](/fr/reference/microsoft-store-apis/xstore-v8-recurrence-query) et que les valeurs `recurrenceData` de l'[API de requête Collections](/fr/reference/microsoft-store-apis/xstore-v9-query-for-products)) pour agir sur l'abonnement de l'utilisateur.

Voici quelques exemples d'utilisation du point de terminaison Recurrence Change avec vos services :

* Ajout de temps aux abonnements des utilisateurs ayant subi une interruption de service.
* Intégration avec vos équipes de support client pour aider les utilisateurs avec des informations sur l'état de leur abonnement, les annulations, etc.
* Interface utilisateur dans le jeu permettant aux utilisateurs de modifier des paramètres tels que le renouvellement automatique ou de mettre fin à leur abonnement.

## Test des produits d'abonnement

L'[API Recurrence Change](/fr/reference/microsoft-store-apis/xstore-v8-recurrence-change) peut également être utilisée pour les tests. `Extend` accepte des valeurs de jours négatives, ce qui vous permet de faire avancer un abonnement de test vers les états ciblés.

### Test des états Active, Inactive et Canceled

Lorsque vous testez les états Active, Inactive et Canceled d'un abonnement, vous pouvez utiliser un prix de base de \$0.00 pour l'abonnement. Ajoutez l'abonnement au compte de test pour vérifier l'état Active et utilisez le point de terminaison Recurrence Change pour désactiver le renouvellement automatique. Utilisez ensuite le point de terminaison Recurrence Change pour annuler l'abonnement ou soustraire suffisamment de jours pour que l'`ExpirationTime` soit antérieur à la date et l'heure UTC actuelles.

### Test des états Grace et Dunning

Pour tester les états Grace et Dunning, l'abonnement doit avoir un prix non nul.<br />De plus, le compte de test doit être configuré de manière à ce que les paiements ultérieurs échouent une fois l'`ExpirationTime` passé. Actuellement, le Microsoft Store ne dispose pas d'instruments de paiement de test ; le moyen le plus simple de configurer un compte consiste donc à utiliser des codes de devise prépayés comme suit :

1. Configurez l'abonnement avec un prix bas, par exemple \$0.99, dans votre environnement de test.
2. [Achetez une carte cadeau prépayée XBOX](https://www.microsoft.com/en-us/p/xbox-gift-card-digital-code/cfq7ttc0k63h/0002?activetab=pivot:overviewtab) de $1.00 ou $2.00 pour couvrir le premier achat de l'abonnement (taxes comprises), mais pas le renouvellement.
3. Utilisez la carte cadeau sur votre compte de test.
4. Achetez l'abonnement sur le compte de test.
5. Assurez-vous que le renouvellement automatique est activé pour l'abonnement, mais que les fonds sont insuffisants pour le renouveler.
6. Utilisez Recurrence Change pour placer l'`ExpirationTime` de l'abonnement dans les prochaines 24 heures (consultez la remarque suivante).
7. Attendez que l'`ExpirationTime` soit naturellement dépassé et que l'état affiche `InDunning` (cela peut prendre jusqu'à 24 heures après l'`ExpirationTime`).

Pour obtenir un comportement Grace -> Dunning -> Inactive exact, laissez le compte progresser naturellement après avoir configuré le test.

<Note>
  Pour placer correctement un compte dans l'état 'InDunning' pour les périodes Grace et Dunning, le compte doit dépasser naturellement les dates `ExpirationTime` et `ExpirationTimeWithGrace`. Lorsque vous soustrayez des jours, ciblez un `ExpirationTime` situé dans les prochaines 24 heures, puis laissez le temps s'écouler naturellement. Si vous déplacez l'`ExpirationTime` vers un moment déjà passé, `InDunning` risque de ne pas apparaître et l'état de test peut devenir invalide. La seule façon de résoudre ce problème consiste à annuler l'abonnement et à créer un nouvel abonnement de test.
</Note>

## Voir aussi

[Vue d'ensemble du commerce](/fr/publishing/xstore-commerce/xstore-commerce-overview)

[API de service du Microsoft Store](/fr/reference/microsoft-store-apis/index)

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

[purchase.mp.microsoft.com/v8.0/b2b/recurrences/](/fr/reference/microsoft-store-apis/xstore-v8-recurrence-change){recurrenceId}[/change](/fr/reference/microsoft-store-apis/xstore-v8-recurrence-change)

[Bibliothèque Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services)

[Exemple Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services-Sample)


## Related topics

- [Gestion des produits consommables depuis votre service](/fr/publishing/xstore-commerce/xstore-managing-consumables.md)
- [Gestion des remboursements et des rétrofacturations depuis votre service](/fr/publishing/xstore-commerce/xstore-managing-refunds.md)
- [Utilisation côté client des privilèges utilisateur des services XBOX](/fr/services/xbox-services/fundamentals/identity/privileges/concepts/live-user-privileges-client.md)
- [API de modification de la récurrence d'abonnement Microsoft Store v8](/fr/reference/microsoft-store-apis/xstore-v8-recurrence-change.md)
- [Accorder aux joueurs l'accès au contenu des modules complémentaires](/fr/publishing/xstore-commerce/xstore-granting-access.md)