Modifier l’état de facturation de l’abonnement d’un utilisateurChange the billing state of a subscription for a user

Utilisez cette méthode dans l’API d'achat du Microsoft Store pour modifier l'état de facturation d'une extension d'abonnement d'un utilisateur donné.Use this method in the Microsoft Store purchase API to change the billing state of a subscription add-on for a given user. Vous pouvez annuler, étendre, rembourser ou désactiver le renouvellement automatique d'un abonnement.You can cancel, extend, refund, or disable automatic renewal for a subscription.

Notes

Cette méthode peut uniquement être utilisée par les comptes de développeur qui ont été configurés par Microsoft pour être en mesure de créer des extensions d’abonnement pour les applications Universal Windows Platform (UWP).This method can only be used by developer accounts that have been provisioned by Microsoft to be able to create subscription add-ons for Universal Windows Platform (UWP) apps. Les extensions d’abonnement ne sont actuellement pas disponibles pour la plupart des comptes de développeur.Subscription add-ons are currently not available to most developer accounts.

Conditions préalablesPrerequisites

Pour utiliser cette méthode, vous devez disposer des éléments suivants :To use this method, you will need:

  • Un jeton d’accès Azure AD créé avec la valeur d’URI d’audience https://onestore.microsoft.com.An Azure AD access token that has the audience URI value https://onestore.microsoft.com.
  • Une clé d’ID du Microsoft Store qui représente l’identité de l’utilisateur qui possède des droits sur l'abonnement que vous souhaitez modifier.A Microsoft Store ID key that represents the identity of the user who has an entitlement to the subscription you want to change.

Pour plus d’informations, consultez Gérer les droits sur les produits à partir d’un service.For more information, see Manage product entitlements from a service.

RequêteRequest

Syntaxe de la requêteRequest syntax

MéthodeMethod URI de requêteRequest URI
POSTPOST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change

En-tête de requêteRequest header

En-têteHeader TypeType DescriptionDescription
AuthorizationAuthorization chaînestring Obligatoire.Required. Le jeton d’accès Azure AD sous la forme PORTEUR < jeton>.The Azure AD access token in the form Bearer <token>.
HostHost chaînestring Doit être défini sur la valeur purchase.mp.microsoft.com.Must be set to the value purchase.mp.microsoft.com.
Content-LengthContent-Length nombrenumber Longueur du corps de la requête.The length of the request body.
Content-TypeContent-Type chaînestring Spécifie le type de requête et de réponse.Specifies the request and response type. Actuellement, la seule valeur prise en charge est application/json.Currently, the only supported value is application/json.

Paramètres de la requêteRequest parameters

NomName TypeType DescriptionDescription ObligatoireRequired
recurrenceIdrecurrenceId chaînestring ID de l’abonnement à modifier.The ID of the subscription you want to change. Pour obtenir cet ID, appelez le obtenir les abonnements d’un utilisateur (méthode), identifier l’entrée de corps de réponse qui représente le module complémentaire abonnement que vous souhaitez modifier et utiliser la valeur de la id champ pour l’entrée.To get this ID, call the get subscriptions for a user method, identify the response body entry that represents the subscription add-on you want to change, and use the value of the id field for the entry. OuiYes

Corps de la requêteRequest body

ChampField TypeType DescriptionDescription ObligatoireRequired
b2bKeyb2bKey chaînestring La clé d’ID du Microsoft Store qui représente l’identité de l’utilisateur dont vous souhaitez modifier l'abonnement.The Microsoft Store ID key that represents the identity of the user whose subscription you want to change. OuiYes
changeTypechangeType chaînestring Une des chaînes suivantes qui identifie le type de modification que vous souhaitez apporter :One of the following strings that identifies the type of change you want to make:
  • Annuler : Annule l’abonnement.Cancel: Cancels the subscription.
  • Étendre: Étend l’abonnement.Extend: Extends the subscription. Si vous spécifiez cette valeur, vous devez également inclure le paramètre extensionTimeInDays.If you specify this value, you must also include the extensionTimeInDays parameter.
  • Remboursement: Remboursements l’abonnement au client.Refund: Refunds the subscription to the customer.
  • ToggleAutoRenew: Désactive le renouvellement automatique pour l’abonnement.ToggleAutoRenew: Disables automatic renewal for the subscription. Si le renouvellement automatique est actuellement désactivé pour l’abonnement, cette valeur n’a aucun effet.If automatic renewal is currently disabled for the subscription, this value does nothing.
OuiYes
extensionTimeInDaysextensionTimeInDays chaînestring Si le paramètre changeType a la valeur Étendre, ce paramètre spécifie le nombre de jours pour étendre l’abonnement.If the changeType parameter has the value Extend, this parameter specifies the number of days to extend the subscription. Oui, si changeType a la valeur Étendre ; le cas contraire, non.Yes, if changeType has the value Extend; otherwise, no.

Exemple de requêteRequest example

L’exemple suivant présente comment utiliser cette méthode afin d’étendre la période d’abonnement de 5 jours.The following example demonstrates how to use this method to extend the subscription period by 5 days. Remplacez la valeur b2bKey par la la clé d’ID du Microsoft Store qui représente l’identité de l’utilisateur dont vous souhaitez modifier l'abonnement.Replace the b2bKey value with the Microsoft Store ID key that represents the identity of the user whose subscription you want to change.

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éponseResponse

Cette méthode renvoie un corps de réponse JSON qui contient des informations sur l’extension d’abonnement modifié, ainsi que tous les champs également modifiés.This method returns a JSON response body that contains information about the subscription add-on that was modified, including any fields that were modified. L’exemple suivant présente un corps de réponse associé à cette méthode.The following example demonstrates a response body for this method.

{
  "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 la réponseResponse body

Le corps de réponse contient les données suivantes.The response body contains the following data.

ValeurValue TypeType DescriptionDescription
autoRenewautoRenew BooléenBoolean Indique si l’abonnement est configuré pour se renouveler automatiquement à la fin de la période d’abonnement en cours.Indicates whether the subscription is configured to automatically renew at the end of the current subscription period.
beneficiarybeneficiary chaînestring L’ID du bénéficiaire du droit associé à cet abonnement.The ID of the beneficiary of the entitlement that is associated with this subscription.
expirationTimeexpirationTime chaînestring La date et l’heure auxquelles l’abonnement expire, au format ISO 8601.The date and time the subscription will expire, in ISO 8601 format. Ce champ est uniquement disponible lorsque l’abonnement est dans certains états.This field is only available when the subscription is in certain states. Généralement, le délai d’expiration indique le moment où l’état actuel arrive à expiration.The expiration time usually indicates when the current state expires. Par exemple, pour un abonnement actif, la date d’expiration indique quand le renouvellement automatique suivant a lieu.For example, for an active subscription, the expiration date indicates when the next automatic renewal will occur.
expirationTimeWithGraceexpirationTimeWithGrace chaînestring Date et heure de qu'expiration de l’abonnement, y compris la période de grâce, au format ISO 8601.The date and time the subscription will expire including the grace period, in ISO 8601 format. Cette valeur indique que lorsque l’utilisateur perd l’accès à l’abonnement une fois que l’abonnement n’a pas pu renouveler automatiquement.This value indicates when the user will lose access to the subscription after the subscription has failed to automatically renew.
idid chaînestring L’ID de l’abonnement.The ID of the subscription. Utilisez cette valeur afin d’indiquer l’abonnement que vous souhaitez modifier lorsque vous appelez la méthode modifier l’état de facturation de l’abonnement d’un utilisateur.Use this value to indicate which subscription you want to modify when you call the change the billing state of a subscription for a user method.
isTrialisTrial BooléenBoolean Indique si l’abonnement est une version d’évaluation.Indicates whether the subscription is a trial.
lastModifiedlastModified chaînestring La date et l’heure auxquelles l’abonnement a été modifié pour la dernière fois, au format ISO 8601.The date and time the subscription was last modified, in ISO 8601 format.
marketmarket chaînestring Le code pays (code de deux lettres au format ISO 3166-1 alpha-2) dans lequel l’utilisateur a obtenu l’abonnement.The country code (in two-letter ISO 3166-1 alpha-2 format) in which the user acquired the subscription.
productIdproductId chaînestring L’ID Store pour le produit qui représente l’extension d’abonnement dans le catalogue Microsoft Store.The Store ID for the product that represents the subscription add-on in the Microsoft Store catalog. Exemple d’ID Windows Store pour un produit : 9NBLGGH42CFD.An example Store ID for a product is 9NBLGGH42CFD.
skuIdskuId chaînestring L’ID Store pour la SKU qui représente l’extension d’abonnement dans le catalogue Microsoft Store.The Store ID for the SKU that represents the subscription add-on the Microsoft Store catalog. Exemple d’ID Windows Store pour une référence (SKU) : 0010.An example Store ID for a SKU is 0010.
startTimestartTime chaînestring L’heure et la date de début de l’abonnement, au format ISO 8601.The start date and time for the subscription, in ISO 8601 format.
recurrenceStaterecurrenceState chaînestring Une des valeurs suivantes :One of the following values:
  • Aucun :  cela indique un abonnement à durée indéterminée.None:  This indicates a perpetual subscription.
  • Actif :  l’abonnement est actif et l’utilisateur est autorisé à utiliser les services.Active:  The subscription is active and the user is entitled to use the services.
  • Inactif :  l’abonnement est expiré et l’utilisateur a désactivé l’option de renouvellement automatique de l’abonnement.Inactive:  The subscription is past the expiration date, and the user turned off the automatic renew option for the subscription.
  • Annulé :  l’abonnement a été délibérément arrêté avant la date d’expiration, avec ou sans remboursement.Canceled:  The subscription has been purposefully terminated before the expiration date, with or without a refund.
  • InDunning :  l’abonnement est en relance (autrement dit, l’abonnement est arrivé à expiration et Microsoft essaie d’acquérir des fonds pour renouveler automatiquement l’abonnement).InDunning:  The subscription is in dunning (that is, the subscription is nearing expiration, and Microsoft is trying to acquire funds to automatically renew the subscription).
  • Échec :  la période de relance est terminée et malgré plusieurs essais, l’abonnement n’a pu être renouvelé.Failed:  The dunning period is over and the subscription failed to renew after several attempts.

Remarque :Note:

  • Inactif/Annulé/Échec sont des états terminaux.Inactive/Canceled/Failed are terminal states. Lorsqu’un abonnement acquiert l’un de ces états, l’utilisateur doit obligatoirement procéder au rachat de l’abonnement pour le réactiver.When a subscription enters one of these states, the user must repurchase the subscription to activate it again. L’utilisateur n’est pas autorisé à utiliser les services dans ces états.The user is not entitled to use the services in these states.
  • Lorsqu’un abonnement est Annulé, la valeur expirationTime sera mise à jour avec la date et l’heure de l’annulation.When a subscription is Canceled, the expirationTime will be updated with the date and time of the cancellation.
  • L’ID de l’abonnement reste le même pendant toute sa durée de vie.The ID of the subscription will remain the same during its entire lifetime. Il ne changera pas si l’option renouvellement automatique est activée ou désactivée.It will not change if the auto-renew option is turned on or off. Si un utilisateur rachète un abonnement après avoir atteint un état de terminal, un nouvel ID d’abonnement sera généré.If a user repurchases a subscription after reaching a terminal state, a new subscription ID will be created.
  • L’ID d’un abonnement doit être utilisé pour exécuter n’importe quelle opération sur un abonnement individuel.The ID of a subscription should be used to execute any operation on an individual subscription.
  • Dans le cas où un utilisateur rachète un abonnement après une annulation ou une interruption, si vous interrogez les résultats de l’utilisateur, vous allez obtenir deux entrées : une entrée avec l’ancien ID d’abonnement en état terminal et une entrée avec le nouvel ID d’abonnement en état actif.When a user repurchases a subscription after cancelling or discontinuing it, if you query the results for the user you will get two entries: one with the old subscription ID in a terminal state, and one with the new subscription ID in an active state.
  • Il est toujours bon de vérifier à la fois les valeurs recurrenceState et expirationTime, dans la mesure où les mises à jour vers la valeur recurrenceState peuvent être potentiellement retardées de quelques minutes (parfois même quelques heures).It's always a good practice to check both recurrenceState and expirationTime, since updates to recurrenceState can potentially be delayed by a few minutes (or occasionally hours).
cancellationDatecancellationDate chaînestring La date et l’heure auxquelles l’abonnement de l’utilisateur a été annulé, au format ISO 8601.The date and time the user's subscription was cancelled, in ISO 8601 format.