Gérer les produits d'abonnement à partir de votre service

Pour les produits d’abonnement, utilisez un service principal (back-end) pour valider l’état et gérer les opérations de cycle de vie. L’utilisation des API Recurrence offre à vos équipes de soutien et d’exploitation en direct un moyen fiable d’inspecter, de prolonger ou d’annuler des abonnements. Cet article explique comment utiliser les points de terminaison Recurrence dans 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 contient lui-même une logique type pour gérer les produits d’abonnement et fournit un guide de configuration pour le mettre en place.

• Microsoft.StoreServices (GitHub)
• Exemple Microsoft.StoreServices (GitHub)

​

Types de produits d’abonnement

Les types de produits d’abonnement gérés par le Store et d’abonnement en tant que module complémentaire fonctionnent tous deux avec le service Recurrence pour afficher et gérer l’abonnement de l’utilisateur. Pour plus d’information sur chacun de ces types de produits, consultez Choisir le bon type de produit

​

Interroger l’abonnement d’un utilisateur

Utilisez purchase.mp.microsoft.com/v8.0/b2b/recurrences/query comme point de terminaison principal pour l’état des abonnements. Il renvoie 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) et publisherQuery (v9)) peuvent indiquer un droit d’utilisation 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 d’utilisation sur le client et en mode serveur à serveur

Lorsque vous publiez une mise à jour qui ajoute de nouveaux éléments (droits d’utilisation satisfaisants) à un ensemble, il existe un délai de visibilité des nouveaux éléments entre les requêtes d’API côté client et les requêtes serveur à serveur. Ce délai survient parce 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 licences locaux obtiennent généralement les informations mises à jour en premier, et les caches utilisés par publisherQuery les reçoivent de deux à trois heures plus tard. Prévoyez donc quelques heures pendant lesquelles les API côté client accordent l’accès alors que vos appels 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 d’utilisation satisfaisants des éléments nouvellement ajoutés le sont.

​

Comprendre les dates de début, de renouvellement et d’expiration des abonnements

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é, expire ou est révoqué, un nouvel objet d’abonnement est créé lorsque l’utilisateur achète de nouveau l’abonnement. La nouvelle période d’abonnement active a comme 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 en nombre de mois. Par exemple, 1 mois, 3 mois ou 12 mois. Lorsqu’un utilisateur achète un abonnement d’un mois, la valeur StartTime correspond à minuit UTC (00:00:00) du jour où il a commencé l’abonnement. ExpirationTime correspond au nombre de mois (et non de jours) ajouté à StartTime, moins une seconde (23:59:59 UTC).
Cette valeur fait en sorte que l’abonnement expire juste avant minuit UTC. Cependant, certains mois comptent 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.
Si la valeur StartTime de l’utilisateur tombe l’un de ces jours, la valeur ExpirationTime est modifiée pour correspondre à 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 la valeur 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

​

Comprendre les états Grace et Dunning

Si un paiement de renouvellement automatique échoue à ExpirationTime, l’abonnement passe à l’état Grace (période de grâce), puis à l’état Dunning (période de relance) 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. Pendant que l’abonnement d’un utilisateur est en période de grâce ou de relance, vous devriez aviser les utilisateurs de vérifier l’état de leur facturation sur Services et abonnements du compte Microsoft. Pour placer correctement un compte dans chacun de ces états à des fins de test, consultez Tester les produits d’abonnement.

​

Période de grâce

Pendant la période de grâce, gardez les avantages de l’abonnement activés pendant que le Store tente de nouveau 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églé avant ExpirationTimeWithGrace, l’abonnement passe à la période de relance.

​

Période de relance

La période de relance commence à la fin de la période de grâce. Désactivez les avantages de l’abonnement pendant cette période. Les utilisateurs ne peuvent pas racheter ni échanger le même abonnement pendant la période de relance. Si le paiement n’est toujours pas réglé à la fin de la période de relance, l’abonnement devient inactif.

​

Durées des périodes de grâce et de relance

​

Modifier l’abonnement d’un utilisateur

Vos services peuvent également modifier des abonnements avec purchase.mp.microsoft.com/v8.0/b2b/recurrences//change. Les opérations prises en charge comprennent 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 et des valeurs recurrenceData de l’API de requête Collections) pour agir sur l’abonnement de l’utilisateur. Voici quelques exemples de la façon dont le point de terminaison Recurrence Change peut être utile à vos services :

• Ajouter du temps aux abonnements des utilisateurs touchés par une interruption de service.
• Intégration avec vos équipes de soutien à la clientèle pour aider les utilisateurs en leur donnant de l’information sur l’état de leur abonnement, les annulations, etc.
• Interface utilisateur en jeu permettant aux utilisateurs de modifier des paramètres comme le renouvellement automatique ou de mettre fin à leur abonnement.

​

Tester les produits d’abonnement

L’API Recurrence Change peut aussi servir aux 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.

​

Tester les é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, puis 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 la valeur ExpirationTime soit antérieure à la date et l’heure UTC actuelles.

​

Tester les états Grace et Dunning

Pour tester les états Grace et Dunning, l’abonnement doit avoir un prix non nul.
De plus, le compte de test doit être configuré de façon à ce que les paiements subséquents échouent lorsque la valeur ExpirationTime est dépassée. Actuellement, le Microsoft Store n’offre pas de moyens de paiement de test; la façon la plus simple de configurer un compte consiste donc à utiliser des codes de devise prépayée 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 de 1,00 $ou 2,00$ pour couvrir le premier achat de l’abonnement (taxes comprises), mais pas le renouvellement.
3. Échangez 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 renouveler l’abonnement.
6. Utilisez Recurrence Change pour déplacer la valeur ExpirationTime de l’abonnement dans les prochaines 24 heures (voir la remarque suivante).
7. Attendez que la valeur ExpirationTime soit dépassée naturellement et que l’état affiche InDunning (cela peut prendre jusqu’à 24 heures après ExpirationTime).

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

​

Voir aussi

Vue d’ensemble du commerce API de service du Microsoft Store purchase.mp.microsoft.com/v8.0/b2b/recurrences/query purchase.mp.microsoft.com/v8.0/b2b/recurrences//change


Bibliothèque Microsoft.StoreServices (GitHub) Exemple Microsoft.StoreServices (GitHub)