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 d’un abonnement.

Notes

Cette méthode ne peut être utilisée que 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 extensions 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 devez disposer des éléments suivants :

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

Pour plus d’informations, consultez Gérer les droits d’utilisation d’un 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 sous la formeJeton> du porteur<.
Host string Doit être défini sur la valeur purchase.mp.microsoft.com.
Content-Length nombre Longueur du corps de la demande.
Content-Type string Spécifie le type de requête 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 la méthode get subscriptions d’un utilisateur , identifiez l’entrée de corps de réponse qui représente le module complémentaire d’abonnement que vous souhaitez modifier, puis 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 L’une des chaînes suivantes qui identifie le type de modification que vous souhaitez apporter :
  • Annuler : annule l’abonnement.
  • Étendre : étend l’abonnement. Si vous spécifiez cette valeur, vous devez également inclure le paramètre extensionTimeInDays .
  • Remboursement : rembourse 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 n’a rien à faire.
 Oui
extensionTimeInDays string Si le paramètre changeType a la valeur Extend, ce paramètre spécifie le nombre de jours d’extension de 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 prolonger 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 qui a été 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"
    }
  ]
}

Response body

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

Valeur Type Description
autoRenew Boolean Indique si l’abonnement est configuré pour se renouveler automatiquement à la fin de la période d’abonnement actuelle.
beneficiary string ID du bénéficiaire du droit associé à cet abonnement.
expirationTime string Date et heure d’expiration de l’abonnement, au format ISO 8601. Ce champ n’est disponible que lorsque l’abonnement se trouve dans certains états. Le délai d’expiration indique généralement quand l’état actuel expire. Par exemple, pour un abonnement actif, la date d’expiration indique quand le prochain renouvellement automatique aura lieu.
expirationTimeWithGrace string Date et heure d’expiration de l’abonnement, y compris la période de grâce, au format ISO 8601. Cette valeur indique quand l’utilisateur perd l’accès à l’abonnement une fois que l’abonnement n’a pas pu être renouvelé automatiquement.
id string ID de l'abonnement. Utilisez cette valeur pour indiquer l’abonnement que vous souhaitez modifier lorsque vous appelez le modifier l’état de facturation d’un abonnement pour une méthode utilisateur .
isTrial Boolean Indique si l’abonnement est une version d’évaluation.
lastModified string Date et heure de la dernière modification de l’abonnement, au format ISO 8601.
market string L’indicatif 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 du Microsoft Store. Un exemple d’ID store pour un produit est 9NBLGGH42CFD.
skuId string ID store de la référence SKU qui représente le complément d’abonnement dans le catalogue du Microsoft Store. Un exemple d’ID de magasin 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 pour l’abonnement.
  • Annulé : l’abonnement a été délibérément arrêté avant la date d’expiration, avec ou sans remboursement.
  • InDunning : l’abonnement est en cours de relance (autrement dit, l’abonnement arrive à expiration et Microsoft tente d’acquérir des fonds pour renouveler automatiquement l’abonnement).
  • Échec : la période de relance est terminée et l’abonnement n’a pas pu être renouvelé après plusieurs tentatives.

Remarque :

  • Inactif/Annulé/Les états terminal ont échoué . Lorsqu’un abonnement entre dans l’un de ces états, l’utilisateur doit racheter l’abonnement pour l’activer à nouveau. L’utilisateur n’est pas autorisé à utiliser les services dans ces états.
  • Lorsqu’un abonnement est annulé, expirationTime est mis à jour avec la date et l’heure de l’annulation.
  • L’ID de l’abonnement restera le même pendant toute sa durée de vie. Elle 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 terminal, 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 arrêté, si vous interrogez les résultats pour l’utilisateur, vous obtenez deux entrées : l’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 case activée à la fois recurrenceState et expirationTime, car les mises à jour de recurrenceState peuvent potentiellement être retardées de quelques minutes (ou parfois de quelques heures).
cancellationDate string Date et heure d’annulation de l’abonnement de l’utilisateur, au format ISO 8601.