Partager via

Modifier l’état de facturation de l’abonnement d’un utilisateur

  • Article

Utilisez cette méthode dans l’API d’achat du Microsoft Store pour modifier l’état de facturation d’un module complémentaire d’abonnement pour un utilisateur donné. Vous pouvez annuler, étendre, rembourser ou désactiver le renouvellement automatique pour un abonnement.

Remarque

Cette méthode peut uniquement être utilisée par les comptes de développeur qui ont été provisionnés par Microsoft pour pouvoir créer des modules complémentaires d’abonnement pour les applications plateforme Windows universelle (UWP). Les modules complémentaires d’abonnement ne sont actuellement pas disponibles pour la plupart des comptes de développeur.

La bibliothèque Microsoft.StoreServices fournit les fonctionnalités de cette méthode via l’API StoreServicesClient.RecurrenceChangeAysnc.

Prérequis

Pour utiliser cette méthode, vous aurez besoin des éléments suivants :

  • Jeton d’accès Azure AD qui a la valeur https://onestore.microsoft.comde l’URI d’audience .
  • Clé d’ID du Microsoft Store qui représente l’identité de l’utilisateur disposant d’un droit à l’abonnement que vous souhaitez modifier.

Pour plus d’informations, consultez Gérer les droits de produit à partir d’un service.

Requête

Syntaxe de la requête

Méthode URI de demande
POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change

En-tête de requête

En-tête Type Description
Autorisation string Obligatoire. Jeton d’accès Azure AD au format porteur<jeton>.
Host string Doit être défini sur la valeur purchase.mp.microsoft.com.
Longueur-contenu nombre Longueur du corps de la demande.
Content-Type string Spécifie le type de demande et de réponse. Actuellement, la seule valeur prise en charge est application/json.

Paramètres de la demande

Nom Type Description Obligatoire
recurrenceId string ID de l’abonnement que vous souhaitez modifier. Pour obtenir cet ID, appelez les abonnements Get pour une méthode utilisateur , identifiez l’entrée du corps de la réponse qui représente le module complémentaire d’abonnement que vous souhaitez modifier et utilisez la valeur du champ ID pour l’entrée. Oui

Corps de la demande

Champ Type Description Obligatoire
b2bKey string Clé d’ID du Microsoft Store qui représente l’identité de l’utilisateur dont vous souhaitez modifier l’abonnement. Oui
changeType string Une des chaînes suivantes qui identifie le type de modification que vous souhaitez effectuer :
  • Annuler : annule l’abonnement.
  • Étendre : étend l’abonnement. Si vous spécifiez cette valeur, vous devez également inclure le paramètre extensionTimeInDays .
  • Remboursement : remboursement de l’abonnement au client.
  • ToggleAutoRenew : désactive le renouvellement automatique de l’abonnement. Si le renouvellement automatique est actuellement désactivé pour l’abonnement, cette valeur ne fait rien.
 Oui
extensionTimeInDays string Si le paramètre changeType a la valeur Extend, ce paramètre spécifie le nombre de jours pour étendre l’abonnement. Oui, si changeType a la valeur Extend ; sinon, non.

Exemple de requête

L’exemple suivant montre comment utiliser cette méthode pour étendre la période d’abonnement de 5 jours. Remplacez la valeur b2bKey par la clé d’ID du Microsoft Store 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"
}

Response

Cette méthode retourne un corps de réponse JSON qui contient des informations sur le module complémentaire d’abonnement modifié, y compris les champs qui ont été modifiés. L’exemple suivant illustre un corps de réponse pour cette méthode.

{
  "items": [
    {
      "autoRenew":true,
      "beneficiary":"pub:gFVuEBiZHPXonkYvtdOi+tLE2h4g2Ss0ZId0RQOwzDg=",
      "expirationTime":"2017-06-16T03:07:49.2552941+00:00",
      "id":"mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac",
      "lastModified":"2017-01-10T21:08:13.1459644+00:00",
      "market":"US",
      "productId":"9NBLGGH52Q8X",
      "skuId":"0024",
      "startTime":"2017-01-10T21:07:49.2552941+00:00",
      "recurrenceState":"Active"
    }
  ]
}

Corps de réponse

Le corps de la réponse contient les données suivantes.

Valeur Type Description
autoRenew Boolean Indique si l’abonnement est configuré pour renouveler automatiquement à la fin de la période d’abonnement en cours.
bénéficiaire string ID du bénéficiaire du droit associé à cet abonnement.
expirationTime string La date et l’heure d’expiration de l’abonnement, au format ISO 8601. Ce champ n’est disponible que lorsque l’abonnement se trouve dans certains états. L’heure d’expiration indique généralement à quel moment l’état actuel expire. Par exemple, pour un abonnement actif, la date d’expiration indique quand le prochain renouvellement automatique se produit.
expirationTimeWithGrace string La date et l’heure auxquelles l’abonnement expire, y compris la période de grâce, au format ISO 8601. Cette valeur indique quand l’utilisateur perd l’accès à l’abonnement après l’échec du renouvellement automatique de l’abonnement.
id string ID de l'abonnement. Utilisez cette valeur pour indiquer l’abonnement que vous souhaitez modifier lorsque vous appelez le changement de l’état de facturation d’un abonnement pour une méthode utilisateur .
isTrial Boolean Indique si l’abonnement est un essai.
lastModified string Date et heure de la dernière modification de l’abonnement au format ISO 8601.
market string Code de pays (au format ISO 3166-1 alpha-2 à deux lettres) dans lequel l’utilisateur a acquis l’abonnement.
productId string ID Store du produit qui représente le module complémentaire d’abonnement dans le catalogue microsoft Store. Un exemple d’ID Store pour un produit est 9NBLGGH42CFD.
skuId string ID store pour la référence SKU qui représente le module complémentaire d’abonnement dans le catalogue microsoft Store. Un exemple d’ID store pour une référence SKU est 0010.
startTime string Date et heure de début de l’abonnement, au format ISO 8601.
recurrenceState string Une des valeurs suivantes :
  • Aucun : cela indique un abonnement perpétuel.
  • Actif : l’abonnement est actif et l’utilisateur a le droit d’utiliser les services.
  • Inactif : l’abonnement dépasse la date d’expiration et l’utilisateur a désactivé l’option de renouvellement automatique de l’abonnement.
  • Annulé : l’abonnement a été correctement arrêté avant la date d’expiration, avec ou sans remboursement.
  • InDunning : L’abonnement est en service (autrement dit, l’abonnement arrive à expiration et Microsoft essaie d’acquérir des fonds pour renouveler automatiquement l’abonnement).
  • Échec : la période de vidage est terminée et l’abonnement n’a pas pu être renouvelé après plusieurs tentatives.

Remarque :

  • L’échec annulé/inactif/est les états de terminal. Lorsqu’un abonnement entre dans l’un de ces états, l’utilisateur doit réaffecter 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é, l’heure d’expiration est mise à 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. Elle ne changera pas si l’option de renouvellement automatique est activée ou désactivée. Si un utilisateur réaffecte un abonnement après avoir atteint l’état du terminal, un nouvel ID d’abonnement est créé.
  • L’ID d’un abonnement doit être utilisé pour exécuter une opération sur un abonnement individuel.
  • Lorsqu’un utilisateur effectue un rachat d’un abonnement après l’annulation ou la suppression de celui-ci, si vous interrogez les résultats pour l’utilisateur, vous obtenez deux entrées : une avec l’ancien ID d’abonnement dans un état terminal 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 potentiellement être retardées de quelques minutes (ou parfois des heures).
cancellationDate string Date et heure de l’annulation de l’abonnement de l’utilisateur, au format ISO 8601.