purchase.mp.microsoft.com/v8.0/b2b/recurrences/query

Ce point de terminaison interroge l’état des produits d’abonnement d’un utilisateur dans le Microsoft Store. Il fournit plus de détails que Collections, y compris les données de la période de grâce après l’échec d’un renouvellement automatique.

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 retourner aucun résultat.

Requête

Syntaxe de la requête

Méthode	URI de la requête
`POST`	`purchase.mp.microsoft.com/v8.0/b2b/recurrences/query`

En-tête de la requête

En-tête	Type	Description
`Authorization`	`string`	Obligatoire. Le jeton d’accès au service Microsoft Entra ID sous la forme `Bearer` <jeton>.
`Host`	`string`	Doit être défini sur la valeur `purchase.mp.microsoft.com`.
`Content-Length`	`number`	La 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`.

Corps de la requête

Paramètre	Type	Description	Obligatoire
`b2bKey`	`string`	Le User Purchase ID qui représente l’identité de l’utilisateur pour lequel vous effectuez la requête. Consultez Clé User Store ID.	Oui
`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 par défaut est RETAIL. L’authentification par X-Token n’a pas besoin de cette valeur, car le Sandbox est spécifié dans le X-Token.	Non
`continuationToken`	`string`	S’il existe plusieurs ensembles de produits qui ne tiennent pas dans `maxPageSize`, le corps de la réponse retourne un jeton de continuation lorsque la limite de page est atteinte. Fournissez le jeton de continuation dans les appels suivants pour obtenir plus de résultats.	Non

Exemple de requête

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/query HTTP/1.1
Host: purchase.mp.microsoft.com
Authorization: Bearer [Microsoft Entra ID bearer token]
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
  "b2bKey":"[UserPurchaseId]",
  "sbx": "XDKS.1"
}

Réponse

Corps de la réponse

Paramètre	Type	Description	Obligatoire
`continuationToken`	`string`	Ce jeton est retourné 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>`	Un 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 est inscrit au renouvellement automatique de son abonnement à la fin du prochain cycle de facturation.	Oui
`beneficiary`	`string`	Le Publisher ID du bénéficiaire dans le User Purchase ID.	Oui
`expirationTime`	`DateTime`	La date et l’heure UTC d’expiration de l’abonnement	Oui
`expirationTimeWithGrace`	`DateTime`	La date et l’heure UTC de fin de la période de grâce de l’utilisateur si le renouvellement automatique échoue à l’ExpirationTime. Pendant la période de grâce, les utilisateurs devraient toujours avoir accès et être considérés comme des abonnés valides, mais être avisés qu’ils doivent corriger leur paiement de renouvellement automatique.	Oui
`id`	`string`	Un ID qui distingue cet article de collection des autres articles que possède l’utilisateur. Cet ID est unique par produit.	Oui
`isTrial`	`bool`	Indique si le produit est dans une période d’essai, comme pour un abonnement.	Oui
`lastModified`	`DateTime`	La date UTC de la dernière modification de cet article.	Oui
`market`	`string`	La région du marché où le produit a été acheté, selon le code de région ISO 3166 à deux caractères. Ex. : US.	Oui
`productId`	`string`	Également appelé Store ID du produit dans le catalogue du Microsoft Store. Un exemple de Store ID pour un produit est 9NBLGGH42CFD.	Oui
`recurrenceState`	`string`	État actuel de la récurrence. Consultez États de récurrence.	Oui
`skuId`	`string`	L’identificateur de SKU spécifique s’il existe plusieurs offres du produit dans le catalogue du Microsoft Store. Un exemple de Store ID pour un SKU est 0010.	Oui
`startTime`	`DateTime`	La date UTC à laquelle l’abonnement devient valide.	Oui
`cancellationDate`	`DateTime`	La 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é résilié volontairement 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 devrait toujours avoir droit aux avantages de l’abonnement. Si la date actuelle est postérieure à la valeur expirationTimeWithGrace, l’utilisateur ne devrait 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 terminaux. Lorsqu’un abonnement entre dans l’un de ces états, l’utilisateur doit racheter l’abonnement pour l’activer de nouveau. L’utilisateur n’a pas le droit d’utiliser les services dans ces états.
Lorsqu’un abonnement est 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 lorsque 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 sera 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 de cet utilisateur, vous obtiendrez deux entrées : une avec l’ancien ID d’abonnement dans un état terminal, et une 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 (ou parfois de quelques heures).

Exemple de réponse

HTTP/1.1 200 OK
date: Tue, 17 Aug 2021 21:22:28 GMT
content-type: application/json; charset=utf-8
content-length: 2382
ms-cv: aft4s000mwNmYF.0
x-content-type-options: nosniff
x-envoy-upstream-service-time: 2099

{
    "items": [
        {
            "autoRenew": true,
            "beneficiary": "pub:NoUserIdProvided",
            "expirationTime": "2021-08-25T23:59:59.00+00:00",
            "expirationTimeWithGrace": "2021-09-08T23:59:59.00+00:00",
            "id": "mdr:0:1ecc1424ed8f457ab6107f08033e6b50:907f0a31-035c-41a2-b70b-5a62925a4f92",
            "isTrial": false,
            "lastModified": "2021-07-26T22:59:55.99+00:00",
            "market": "US",
            "productId": "CFQ7TTC0HC8Z",
            "skuId": "0002",
            "startTime": "2021-07-26T00:00:00.00+00:00",
            "recurrenceState": "Active"
        },
        {
            "autoRenew": true,
            "beneficiary": "pub:NoUserIdProvided",
            "expirationTime": "2021-07-26T21:08:30.52+00:00",
            "expirationTimeWithGrace": "2021-07-26T21:08:30.52+00:00",
            "id": "mdr:0:50c7396d0e5f4e7f9deeede3ba25f1a4:87c4cfae-ed1d-400f-a6b0-19fdb3c327f5",
            "isTrial": false,
            "lastModified": "2021-07-26T21:08:34.61+00:00",
            "market": "US",
            "productId": "CFQ7TTC0HC8Z",
            "skuId": "0002",
            "startTime": "2021-07-15T00:00:00.00+00:00",
            "recurrenceState": "Canceled",
            "cancellationDate": "2021-07-26T21:08:31.52+00:00"
        },
        {
            "autoRenew": false,
            "beneficiary": "pub:NoUserIdProvided",
            "expirationTime": "2021-07-26T22:35:29.54+00:00",
            "expirationTimeWithGrace": "2021-07-26T22:35:29.54+00:00",
            "id": "mdr:0:528115d9771f4e49b79550790fd4a263:f30a646e-54cf-4fe8-8c95-7add9fc2ebde",
            "isTrial": false,
            "lastModified": "2021-07-26T22:35:33.96+00:00",
            "market": "US",
            "productId": "CFQ7TTC0HC8Z",
            "skuId": "0002",
            "startTime": "2021-07-26T00:00:00.00+00:00",
            "recurrenceState": "Canceled",
            "cancellationDate": "2021-07-26T22:35:30.54+00:00"
        },
    ]
}

Explication de l’exemple de réponse

Cette réponse présente trois entrées d’abonnement pour l’utilisateur : deux dans un état Canceled et une actuellement Active qui a commencé le 26 juillet 2021. La période de l’abonnement actif se termine le 26 août 2021 et l’abonnement est configuré pour se renouveler automatiquement à cette date. Si le paiement du renouvellement échoue, l’abonnement passe à la période de grâce, pendant laquelle l’utilisateur reçoit toujours les avantages avant expirationTimeWithGrace (le 8 septembre 2021 dans cet exemple). Lorsque l’abonnement passe à la période de grâce, recurrenceState devient InDunning. Après la fin de la période de grâce, l’abonnement passe à la période de recouvrement. Pendant cette période, votre service cesse d’accorder les avantages, et l’utilisateur doit corriger son mode de paiement. L’utilisateur ne peut ni annuler, ni commencer un nouvel abonnement pendant cette période. Lorsque le paiement est traité, la durée de la période de grâce (deux semaines dans cet exemple) est déduite de la prochaine période payée.

Demande des résultats restants avec le jeton de continuation

Si votre requête comporte plus de résultats que ne peut en retourner une seule réponse, la réponse à votre requête initiale contient un continuationToken. Vous pouvez ensuite utiliser ce continuationToken dans une requête subséquente en ajoutant le jeton de continuation à une copie du corps de la requête précédente. Exemple de requête de continuation :

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/query HTTP/1.1
Host: purchase.mp.microsoft.com
Authorization: Bearer [Microsoft Entra ID bearer token]
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
  "continuationToken":"[Continuation Token]",
  "b2bKey":"[UserPurchaseId]",
  "sbx": "XDKS.1"
}

Articles connexes

purchase.mp.microsoft.com/v8.0/b2b/recurrences//change Gérer les produits à partir de vos services Gestion des remboursements et des rétrofacturations à partir de votre service Authentification de votre service avec les API du Microsoft Store Utilisation de publisherQuery (Collections v9) pour interroger les produits et les droits d’utilisation d’un utilisateur

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

Prérequis

Requête

Syntaxe de la requête

En-tête de la requête

Corps de la requête

Exemple de requête

Réponse

Corps de la réponse

États de récurrence

Exemple de réponse

Explication de l’exemple de réponse

Demande des résultats restants avec le jeton de continuation

Articles connexes

​Prérequis

​Requête

​Syntaxe de la requête

​En-tête de la requête

​Corps de la requête

​Exemple de requête

​Réponse

​Corps de la réponse

​États de récurrence

​Exemple de réponse

​Explication de l’exemple de réponse

​Demande des résultats restants avec le jeton de continuation

​Articles connexes

Prérequis

Requête

Syntaxe de la requête

En-tête de la requête

Corps de la requête

Exemple de requête

Réponse

Corps de la réponse

États de récurrence

Exemple de réponse

Explication de l’exemple de réponse

Demande des résultats restants avec le jeton de continuation

Articles connexes