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

Cette API ne fonctionne que 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 que produit 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 le message « Requested catalog product data wasn’t found. »

Ce point de terminaison permet de 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) fournit les fonctionnalités de cette méthode via l’API StoreServicesClient.RecurrenceChangeAsync.

Prérequis

Consultez Prérequis pour les API de service à service. 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`	`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. 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`.

Paramètres de la requête

En-tête	Type	Description	Obligatoire
`recurrenceId`	`string`	Unique pour l’abonnement de l’utilisateur ; correspond à la même valeur que `id` dans l’API RecurrenceQuery et que `recurrenceData` dans l’API de requête Collections.	Oui

Corps de la requête

Paramètre	Type	Description	Obligatoire
`b2bKey`	`string`	ID d’achat utilisateur qui représente l’identité de l’utilisateur pour lequel vous effectuez la requête. Consultez Clé d’ID Store utilisateur.	Oui
`changeType`	`string`	Identifie le type de modification que vous souhaitez effectuer. Consultez le tableau Opérations de type de modification 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. Pour les scénarios de test, ce nombre peut être négatif afin de retirer des jours à 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 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

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é d’ID Store utilisateur qui représente l’identité de l’utilisateur dont vous souhaitez modifier l’abonnement.

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 renvoie un corps de réponse JSON décrivant l’extension d’abonnement mise à jour, y compris les champs modifiés.

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

Corps de la réponse

Paramètre	Type	Description	Obligatoire
`continuationToken`	`string`	S’il existe plusieurs ensembles de produits, ce jeton est renvoyé 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>`	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 a choisi le renouvellement automatique de son abonnement à la fin du prochain cycle de facturation.	Oui
`beneficiary`	`string`	ID d’éditeur du bénéficiaire dans l’ID d’achat utilisateur.	Oui
`expirationTime`	`DateTime`	Date et heure UTC d’expiration de l’abonnement.	Oui
`expirationTimeWithGrace`	`DateTime`	Date et heure UTC de fin de la période de grâce de l’utilisateur si le renouvellement automatique échoue à la date ExpirationTime. Pendant la période de grâce, les utilisateurs doivent conserver l’accès et être considérés comme des abonnés valides, mais être avertis qu’ils doivent corriger leur moyen de paiement pour le renouvellement automatique.	Oui
`id`	`string`	ID qui distingue cet élément de collection des autres éléments que possède l’utilisateur. Cet ID est unique par produit.	Oui
`isTrial`	`bool`	Indique si le produit est en période d’essai, comme un abonnement.	Oui
`lastModified`	`DateTime`	Date UTC de la dernière modification de cet élément.	Oui
`market`	`string`	Pays/région d’achat du produit, selon le code de pays/région ISO 3166 à deux caractères. Ex. : US.	Oui
`productId`	`string`	Également appelé ID Store du produit dans le catalogue du Microsoft Store. Exemple d’ID Store pour un produit : 9NBLGGH42CFD.	Oui
`recurrenceState`	`string`	État actuel de la récurrence. Consultez États de récurrence.	Oui
`skuId`	`string`	Identificateur de SKU spécifique s’il existe plusieurs offres du produit dans le catalogue du Microsoft Store. Exemple d’ID Store pour une SKU : 0010.	Oui
`startTime`	`DateTime`	Date UTC de début de l’abonnement.	Oui
`cancellationDate`	`DateTime`	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é volontairement résilié 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 doit toujours avoir droit aux avantages de l’abonnement. Si la date actuelle est postérieure à la valeur expirationTimeWithGrace, l’utilisateur ne doit 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 finaux. Lorsqu’un abonnement entre dans l’un de ces états, l’utilisateur doit racheter l’abonnement pour l’activer à nouveau. L’utilisateur n’a pas le droit d’utiliser les services dans ces états.
Lorsqu’un abonnement est annulé (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 si 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 final, un nouvel ID d’abonnement est 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 pour cet utilisateur, vous obtenez deux entrées : l’une avec l’ancien ID d’abonnement dans un état final, et l’autre 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 (voire parfois de quelques heures).

Exemple de réponse

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 Gérer les produits à partir de vos services Gérer les remboursements et les rétrofacturations à partir de votre service Authentifier votre service auprès des API du Microsoft Store Utiliser publisherQuery (Collections v9) pour interroger les produits et les droits d’un utilisateur

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

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

Prérequis

Requête

Syntaxe de la requête

En-tête de la requête

Paramètres de la requête

Corps de la requête

Opérations de type de modification

Exemple de requête

Réponse

Corps de la réponse

États de récurrence

Exemple de réponse

Articles connexes

​Prérequis

​Requête

​Syntaxe de la requête

​En-tête de la requête

​Paramètres de la requête

​Corps de la requête

​Opérations de type de modification

​Exemple de requête

​Réponse

​Corps de la réponse

​États de récurrence

​Exemple de réponse

​Articles connexes

Prérequis

Requête

Syntaxe de la requête

En-tête de la requête

Paramètres de la requête

Corps de la requête

Opérations de type de modification

Exemple de requête

Réponse

Corps de la réponse

États de récurrence

Exemple de réponse

Articles connexes