Ändern des Abrechnungszustands eines Abonnements für einen BenutzerChange the billing state of a subscription for a user

Verwenden Sie diese Methode in der Microsoft Store-Einkaufs-API, um den Abrechnungszustand eines Abonnement-Add-Ons für einen bestimmten Benutzer zu ändern.Use this method in the Microsoft Store purchase API to change the billing state of a subscription add-on for a given user. Sie können ein Abonnement abbrechen, erweitern, erstatten oder die automatische Verlängerung deaktivieren.You can cancel, extend, refund, or disable automatic renewal for a subscription.

Hinweis

Diese Methode kann nur über Entwicklerkonten verwendet werden, die von Microsoft bereitgestellt wurden, um Abonnement-Add-Ons für UWP-Apps (Universelle Windows-Plattform) erstellen zu können.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. Abonnement-Add-Ons sind derzeit für die meisten Entwicklerkonten nicht verfügbar.Subscription add-ons are currently not available to most developer accounts.

VoraussetzungenPrerequisites

Zur Verwendung dieser Methode benötigen Sie:To use this method, you will need:

  • Ein Azure AD-Zugriffstoken, das mit dem Zielgruppen-URI https://onestore.microsoft.com erstellt wurde.An Azure AD access token that has the audience URI value https://onestore.microsoft.com.
  • Ein Microsoft Store-ID-Schlüssel, der die Identität des Benutzers darstellt, der über eine Berechtigung für das Abonnement verfügt, das Sie ändern möchten.A Microsoft Store ID key that represents the identity of the user who has an entitlement to the subscription you want to change.

Weitere Informationen finden Sie unter Verwalten von Produktansprüchen aus einem Dienst.For more information, see Manage product entitlements from a service.

AnfordernRequest

AnforderungssyntaxRequest syntax

MethodeMethod Anforderungs-URIRequest URI
POSTPOST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change

AnforderungsheaderRequest header

HeaderHeader TypType BeschreibungDescription
AutorisierungAuthorization stringstring Erforderlich.Required. Die Azure AD-Zugriffstoken in der Form Bearer < token>.The Azure AD access token in the form Bearer <token>.
HostHost stringstring Muss auf den Wert purchase.mp.microsoft.com festgelegt werden.Must be set to the value purchase.mp.microsoft.com.
Content-LengthContent-Length numbernumber Die Länge des Anforderungstexts.The length of the request body.
Content-TypeContent-Type stringstring Gibt den Anforderungs- und Antworttyp an.Specifies the request and response type. Derzeit wird als einziger Wert application/json unterstützt.Currently, the only supported value is application/json.

AnforderungsparameterRequest parameters

NameName TypType BeschreibungDescription ErforderlichRequired
recurrenceIdrecurrenceId stringstring Die ID des Abonnements, das Sie ändern möchten.The ID of the subscription you want to change. Rufen Sie zum Abrufen dieser ID den rufen Sie die Abonnements für einen Benutzer Methode, identifizieren Sie den Eintrag der Antwort-Text, der stellt dar, die Abonnement-Add-On, die Sie ändern möchten, und verwenden Sie den Wert der Id Feld für den Eintrag.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. JaYes

AnforderungstextRequest body

FeldField TypType BeschreibungDescription ErforderlichRequired
b2bKeyb2bKey stringstring Der Microsoft Store-ID-Schlüssel, der die Identität des Benutzers darstellt, dessen Abonnement Sie ändern möchten.The Microsoft Store ID key that represents the identity of the user whose subscription you want to change. JaYes
changeTypechangeType stringstring Eine der folgenden Zeichenfolgen, die die Art der Änderung angibt, die Sie vornehmen möchten:One of the following strings that identifies the type of change you want to make:
  • Abbrechen: Bricht das Abonnement ab.Cancel: Cancels the subscription.
  • Erweitern Sie: Erweitert das Abonnement an.Extend: Extends the subscription. Wenn Sie diesen Wert angeben, müssen Sie auch den Parameter extensionTimeInDays hinzufügen.If you specify this value, you must also include the extensionTimeInDays parameter.
  • Erstatten Sie: Rückerstattungen das Abonnement, für dem Kunden.Refund: Refunds the subscription to the customer.
  • ToggleAutoRenew: Deaktiviert die automatische Verlängerung des Abonnements.ToggleAutoRenew: Disables automatic renewal for the subscription. Wenn die automatische Verlängerung für das Abonnement derzeit deaktiviert ist, hat dieser Wert keine Auswirkung.If automatic renewal is currently disabled for the subscription, this value does nothing.
JaYes
extensionTimeInDaysextensionTimeInDays stringstring Wenn der Parameter changeType den Wert Extend aufweist, gibt dieser Parameter die Anzahl von Tagen an, um die das Abonnement verlängert wird.If the changeType parameter has the value Extend, this parameter specifies the number of days to extend the subscription. „Ja“, wenn changeType den Wert Extend aufweist; andernfalls „Nein“.Yes, if changeType has the value Extend; otherwise, no.

AnforderungsbeispielRequest example

Im folgenden Beispiel wird veranschaulicht, wie anhand dieser Methode der Abonnementzeitraum um 5 Tage verlängert wird.The following example demonstrates how to use this method to extend the subscription period by 5 days. Ersetzen Sie den Wert b2bKey durch den Microsoft Store-ID-Schlüssel, der die Identität des Benutzers darstellt, dessen Abonnement Sie ändern möchten.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"
}

AntwortResponse

Diese Methode gibt einen JSON-Antworttext zurück, der Informationen über das geänderte Abonnement-Add-On enthält, einschließlich der bearbeiteten Felder.This method returns a JSON response body that contains information about the subscription add-on that was modified, including any fields that were modified. Das folgende Beispiel zeigt einen Antworttext für diese Methode.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"
    }
  ]
}

AntworttextResponse body

Der Antworttext enthält die folgenden Daten.The response body contains the following data.

WertValue TypType BeschreibungDescription
autoRenewautoRenew BooleschBoolean Gibt an, ob das Abonnement für die automatische Verlängerung am Ende des aktuellen Abonnementzeitraums konfiguriert ist.Indicates whether the subscription is configured to automatically renew at the end of the current subscription period.
beneficiarybeneficiary stringstring Die ID des Begünstigten für die Berechtigung, die diesem Abonnement zugeordnet ist.The ID of the beneficiary of the entitlement that is associated with this subscription.
expirationTimeexpirationTime stringstring Datum und Uhrzeit, an dem bzw. zu der das Abonnement abläuft, im Format ISO 8601.The date and time the subscription will expire, in ISO 8601 format. Dieses Feld ist nur verfügbar, wenn sich das Abonnement in bestimmten Zuständen befindet.This field is only available when the subscription is in certain states. Die Ablaufzeit gibt in der Regel an, wann der aktuelle Zustand abläuft.The expiration time usually indicates when the current state expires. Beispiel: Bei einem aktiven Abonnement gibt das Ablaufdatum an, wann die nächste automatische Verlängerung erfolgt.For example, for an active subscription, the expiration date indicates when the next automatic renewal will occur.
expirationTimeWithGraceexpirationTimeWithGrace stringstring Das Datum und Uhrzeit, die das Abonnement abläuft, einschließlich der Toleranzperiode im ISO 8601-Format.The date and time the subscription will expire including the grace period, in ISO 8601 format. Dieser Wert gibt an, wenn der Benutzer verlieren Zugriff auf das Abonnement nach dem das Abonnement nicht automatisch verlängert werden konnte.This value indicates when the user will lose access to the subscription after the subscription has failed to automatically renew.
idid stringstring Die ID des Abonnements.The ID of the subscription. Verwenden Sie diesen Wert, um das Abonnement anzugeben, das Sie durch Aufrufen der Methode zum Ändern des Abrechnungszustands eines Abonnements für einen Benutzer ändern möchten.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 BooleschBoolean Gibt an, ob es sich bei dem Abonnement um eine Testversion handelt.Indicates whether the subscription is a trial.
lastModifiedlastModified stringstring Datum und Uhrzeit, an dem bzw. zu der das Abonnement zuletzt geändert wurde, im Format ISO 8601.The date and time the subscription was last modified, in ISO 8601 format.
marketmarket stringstring Der Ländercode (ein aus zwei Buchstaben bestehendes ISO 3166-1-Alpha-2-Format), der vom Benutzer beim Kauf des Abonnement verwendet wurde.The country code (in two-letter ISO 3166-1 alpha-2 format) in which the user acquired the subscription.
productIdproductId stringstring Die Store-ID für das Produkt, die das Abonnement-Add-On im Microsoft Store-Katalog darstellt.The Store ID for the product that represents the subscription add-on in the Microsoft Store catalog. Ein Beispiel für eine Store-ID für ein Produkt ist 9NBLGGH42CFD.An example Store ID for a product is 9NBLGGH42CFD.
skuIdskuId stringstring Die Store-ID für die SKU, die das Abonnement-Add-On im Microsoft Store-Katalog darstellt.The Store ID for the SKU that represents the subscription add-on the Microsoft Store catalog. Ein Beispiel für eine Store-ID für eine SKU ist 0010.An example Store ID for a SKU is 0010.
startTimestartTime stringstring Startdatum und -uhrzeit des Abonnements im Format ISO 8601.The start date and time for the subscription, in ISO 8601 format.
recurrenceStaterecurrenceState stringstring Einer der folgenden Werte:One of the following values:
  • None:  Gibt ein unbefristetes Abonnement an.None:  This indicates a perpetual subscription.
  • Active:  Das Abonnement ist aktiv und der Benutzer ist zur Verwendung der Dienste berechtigt.Active:  The subscription is active and the user is entitled to use the services.
  • Inactive:  Das Abonnement hat das Ablaufdatum überschritten und der Benutzer hat die Option zur automatischen Verlängerung des Abonnements deaktiviert.Inactive:  The subscription is past the expiration date, and the user turned off the automatic renew option for the subscription.
  • Canceled:  Das Abonnement wurde absichtlich vor dem Ablaufdatum beendet, mit oder ohne Rückerstattung.Canceled:  The subscription has been purposefully terminated before the expiration date, with or without a refund.
  • InDunning:  Das Abonnement befindet sich im Mahnstatus (d. h. das Abonnement läuft in Kürze ab und Microsoft versucht, die Mittel zur automatischen Verlängerung des Abonnements zu akquirieren).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).
  • Failed:  Der Mahnungszeitraum ist abgelaufen und das Abonnement konnte trotz mehrerer Versuche nicht verlängert werden.Failed:  The dunning period is over and the subscription failed to renew after several attempts.

Hinweis:Note:

  • Inactive/Canceled/Failed sind abschließende Zustände.Inactive/Canceled/Failed are terminal states. Wenn ein Abonnement in einen dieser Status wechselt, muss der Benutzer das Abonnement erneut kaufen, um es wieder zu aktivieren.When a subscription enters one of these states, the user must repurchase the subscription to activate it again. Der Benutzer ist nicht berechtigt, die Dienste in diesen Zuständen zu verwenden.The user is not entitled to use the services in these states.
  • Wenn ein Abonnement sich im Status Canceled befindet, wird die Ablaufzeit mit dem Datum und der Uhrzeit des Abbruchs aktualisiert.When a subscription is Canceled, the expirationTime will be updated with the date and time of the cancellation.
  • Die ID des Abonnements bleibt während der gesamten Gültigkeitsdauer unverändert.The ID of the subscription will remain the same during its entire lifetime. Sie wird nicht geändert, wenn die Option zur automatischen Verlängerung aktiviert oder deaktiviert wird.It will not change if the auto-renew option is turned on or off. Wenn ein Benutzer ein Abonnement nach Erreichen eines abschließenden Zustands erneut kauft, wird eine neue Abonnement-ID erstellt.If a user repurchases a subscription after reaching a terminal state, a new subscription ID will be created.
  • Die Abonnement-ID sollte bei allen Aktionen verwendet werden, die auf ein individuelles Abonnement angewendet werden.The ID of a subscription should be used to execute any operation on an individual subscription.
  • Wenn ein Benutzer ein Abonnement nach der Kündigung bzw. Einstellung erneut erwirbt, werden beim Anfordern der Ergebnisse zum betreffenden Benutzer zwei Einträge angezeigt: ein Eintrag mit der alten Abonnement-ID in einem abschließenden Zustand und ein Eintrag mit der neuen Abonnement-ID in einem aktiven Zustand.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.
  • Es empfiehlt sich, die Werte „recurrenceState“ und „expirationTime“ stets zu überprüfen, da Aktualisierungen auf „recurrenceState“ u. U. einige Minuten (gelegentlich auch Stunden) verzögert erfolgen.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 stringstring Datum und Uhrzeit, an dem bzw. zu der das Abonnement des Benutzers storniert wurde, im Format ISO 8601.The date and time the user's subscription was cancelled, in ISO 8601 format.