Planen von Änderungen für ein neues Commerce-Abonnement mithilfe von Partner Center-APIs

gilt für: Partner Center

In diesem Artikel wird beschrieben, wie Sie die Partner Center-API verwenden können, um Änderungen für ein neues Commerce-Abonnement zu planen, die erst bei der Verlängerung erfolgen. Diese API unterstützt neue lizenzbasierte E-Commerce-Abonnements und Softwareabonnements.

Hinweis

Die neuen Commerce-Umgebungen für lizenzbasierte Dienste enthalten zahlreiche neue Funktionen und stehen allen Cloud Solution Providern (CSP) zur Verfügung. Weitere Informationen finden Sie in der Übersicht über neue Commerce-Erfahrungen.

Durch das Erstellen geplanter Änderungen können Sie Ihr Abonnement bei der nächsten Verlängerung automatisch ändern. Durch das Planen von Änderungen können Sie die Anzahl der Lizenzen erhöhen oder verringern, den Abrechnungszeitraum und die Abrechnungshäufigkeit ändern und sogar die SKU aktualisieren. Durch die Planung von Änderungen können Sie Änderungen an Ihrem Abonnement bei der Verlängerung vornehmen, anstatt sofort während der aktuellen Laufzeit.

Von Bedeutung

Wenn Sie eine mittelfristige (unmittelbare) Änderung vor dem Verlängerungsdatum vornehmen, werden alle geplanten Änderungen, die zuvor für die Verlängerung geplant waren, gelöscht.

Voraussetzungen

  • Anmeldeinformationen wie unter Partner Center-Authentifizierung beschrieben. Dieses Szenario unterstützt die Authentifizierung mit eigenständigen App- und App+Benutzeranmeldeinformationen.

  • Eine Kunden-ID (customer-tenant-id). Wenn Sie die Kunden-ID nicht kennen, können Sie sie im Partner Center nachschlagen, indem Sie den Arbeitsbereich Kunden auswählen, dann den Kunden aus der Kundenliste und anschließend Konto. Suchen Sie auf der Kontoseite des Kunden im Abschnitt Kundenkontoinfo nach der Microsoft-ID. Die Microsoft-ID ist identisch mit der Kunden-ID (customer-tenant-id).

  • Eine Abonnement-ID.

  • Die automatische Verlängerung ist für das Abonnement aktiviert.

Partner Center-Methode

So planen Sie Änderungen für ein Abonnement in Partner Center:

  1. Wählen Sie einen Kundenaus.

  2. Wählen Sie das Abonnement aus, für das Sie Änderungen planen möchten.

  3. Aktivieren Sie die automatische Erneuerung.

  4. Wählen Sie Manage renewal (Verlängerung verwalten) aus.

  5. Nehmen Sie Änderungen am Abonnement vor, die bei der Verlängerung erfolgen sollen.

  6. Wählen Sie OK aus, um die Seitenleiste zu schließen.

  7. Wählen Sie Senden aus, um die Änderungen zu speichern.

Hinweis

Verlängerungen werden nach dem letzten Tag einer Laufzeit bearbeitet, beginnend um 12:00 Uhr UTC am folgenden Tag. Verlängerungen werden in einer Warteschlange verarbeitet und es kann bis zu 24 Stunden dauern, bis sie verarbeitet werden.

C#

So planen Sie Änderungen für das Abonnement eines Kunden:

  1. Rufen Sie das Abonnement anhand der ID ab.
  2. Übergangsberechtigung abrufen für den geplanten Typ der Übergangsberechtigung.
  3. Erstellen Sie ein ScheduledNextTermInstructions-Objekt , und legen Sie es auf die Eigenschaft des Abonnements fest.
  4. Rufen Sie die Patch()- Methode auf, um das Abonnement mit den geplanten Änderungen zu aktualisieren.
var selectedSubscription = subscriptionOperations.Get();
selectedSubscription.ScheduledNextTermInstructions = new ScheduledNextTermInstructions
{
    Product = new ProductTerm
    {
        ProductId = changeToProductId,
        SkuId = changeToSkuId,
        AvailabilityId = changeToAvailabilityId,
        BillingCycle = changeToBillingCycle,
        TermDuration = changeToTermDuration,
    },
    Quantity = changeToQuantity,
    customTermEndDate = DateTime,
};
var updatedSubscription = subscriptionOperations.Patch(selectedSubscription);

So planen Sie Änderungen für ein Kundenabonnement, bei dem die geplante Änderung auf ein anderes Produkt übertragen werden soll:

  1. Rufen Sie das Abonnement anhand der ID ab.
  2. Übergangsberechtigung abrufen für den geplanten Typ der Übergangsberechtigung.
  3. Rufen Sie die Patch()- Methode auf, um das Abonnement mit den geplanten Änderungen zu aktualisieren.

REST-Anforderung

Anforderungssyntax

Methode Anforderungs-URI
PATCH {baseURL}/v1/customers/{Kundschaftsmandaten-ID}/subscriptions/{Abonnement-ID} HTTP/1.1

URI-Parameter

In dieser Tabelle sind die erforderlichen Abfrageparameter zum Aufrufen der API aufgeführt.

Name Typ Erforderlich BESCHREIBUNG
Kunden-Mieter-ID GUID Y Eine GUID für den Kunden.
Abonnement-ID GUID Y Eine GUID für das Abonnement

Anforderungsheader

Weitere Informationen finden Sie unter Partner Center REST-Header.

Anforderungstext

Im Anforderungstext ist eine vollständige Abonnementressource erforderlich, deren scheduledNextTermInstructions Eigenschaft definiert ist. Um Änderungen für Ihr Abonnement zu planen, stellen Sie sicher, dass die AutoRenewEnabled-Eigenschaft auf true festgelegt ist.

Für Verfügbarkeits-ID am Ende des Verkaufs mit Konvertierungen (EndofSaleWithConversions) Angebote:

  1. GetTransitionEligibility gibt jetzt CatalogItemID zurück.

    a) Stellen Sie sicher, dass Sie den Typ der geplanten Berechtigung festlegen, andernfalls ist die Standardeinstellung sofort.

  2. Verwenden Sie CatalogItemID, um dann availabilityID zu extrahieren.

Wenn Sie GET Availabilities verwenden, um die Verfügbarkeit der scheduledNextTerm-Anweisungen zu bestimmen und wenn alle Begriffe EOS-Status sind, erhalten Sie eine leere Liste. Die beste Methode zum Ermitteln gültiger Pfade besteht darin, die GetTransitionEligibilty-API aufzurufen, um die gültigen Optionen zurückzugeben.

Feld Typ Erforderlich BESCHREIBUNG
scheduledNextTermInstructions Objekt Y Legt die Anweisungen für die nächste Laufzeit des Abonnements fest. Die Eigenschaft enthält das product Objekt und das quantity Feld.

Verwenden von scheduledActions zum Festlegen von Anweisungen für die nächste Laufzeit (geplante Änderungen)

Erweiterte Servicebedingungen führen eine neue Methode zum Festlegen von Anweisungen für das Ende der Laufzeit ein. Das neue Konstrukt "scheduledActions" ermöglicht Partnern eine einzige Möglichkeit, die nächsten Laufzeitupdates zu definieren, einschließlich Kündigung, Verlängerung zu erweiterten Servicebedingungen oder Verlängerung an andere End-of-Term-Ziele. Partner können die Anweisungen „scheduledActions RenewToNewTerm“ anstelle der bisherigen „scheduledNextTermInstructions“ festlegen. Weitere Informationen zur Verwendung von scheduledActions zum Festlegen von Anweisungen für die nächste Laufzeit finden Sie in der Dokumentation zur erweiterten Service-Laufzeit.

Partner, die scheduledActions verwenden, sollten bei Aktualisierungen von Abonnements, die für verlängerte Servicezeiträume infrage kommen, nicht auch scheduledNextTermInstructions übergeben. Partner können sich entscheiden, beide zu bestehen, sollten erkennen, dass nur scheduledActions berücksichtigt werden. Partner können weiterhin nur „scheduledNextTermInstructions“ übergeben, um Anweisungen für den nächsten Zeitraum festzulegen.

Von Bedeutung

Vermeiden Sie es, Anweisungen für den nächsten Begriff gleichzeitig in den scheduledActions und in den nextTermInstructions zu übergeben. Verwenden Sie eine oder die andere. Wenn beide übergeben werden, werden standardmäßig die Anweisungen für scheduledActions verwendet.

Anforderung mithilfe geplanter Aktionen

{
  "autoRenewEnabled": true,
  "scheduledActions": [
    {
      "scheduledType": "TermEnd",
      "actionType": "RenewToNewTerm",
      "instructions": {
        "product": {
          "productId": "CFQ7TTC0LHXH",
          "skuId": "0001",
          "availabilityId": "CFQ7TTC0LHXH",
          "billingCycle": "annual",
          "termDuration": "P1Y",
          "promotionId": "39NFJQT20KJ2:0001:39NFJQT1Q5KK"
        },
        "quantity": 25,
        "customTermEndDate": "2027-11-31T23:59:59.000Z"
      }
    }
  ]
}

Antwort mithilfe geplanter Aktionen

{
  "autoRenewEnabled": true,
  "scheduledNextTermInstructions" : {
     "product": {
        "productId": "CFQ7TTC0LHXH",
        "skuId": "0001",
        "availabilityId": "CFQ7TTC0LHXH",
        "billingCycle": "annual",
        "termDuration": "P1Y",
        "promotionId": "39NFJQT20KJ2:0001:39NFJQT1Q5KK"
      },
      "quantity": 25,
      "customTermEndDate": "2027-11-31T23:59:59.000Z"
  },
  "scheduledActions":   "scheduledActions": [
    {
      "scheduledType": "TermEnd",
      "actionType": "RenewToNewTerm",
      "instructions": {
        "product": {
          "productId": "CFQ7TTC0LHXH",
          "skuId": "0001",
          "availabilityId": "CFQ7TTC0LHXH",
          "billingCycle": "annual",
          "termDuration": "P1Y",
          "promotionId": "39NFJQT20KJ2:0001:39NFJQT1Q5KK"
        },
        "quantity": 25,
        "customTermEndDate": "2027-11-31T23:59:59.000Z"
      }
    }
  ]
}

Verwenden von scheduledActions zum Festlegen von Übergängen am Jahrestag

Bestimmte ausgewählte dreijährige SKUs mit Teams können so geplant werden, dass der Übergang zum Jahrestag der Laufzeit erfolgt.

Anforderung mithilfe geplanter Aktionen

{ 
    "id": "c10138d2-083b-4330-cf0d-6565dfaf22be", 
    "offerId": "CFQ7TTC0ZSXT:0001:CFQ7TTC0K85Z", 
    … 
    "scheduledActions": [ 
        { 
            "scheduleType": "CustomDate", // currently supported - EndOfTerm
            "actionType": "Transition", // currently supported - RenewToNewTerm, RenewToExtendedServiceTerm, Cancel 
            "effectiveDate": "2026-08-01", 
            "instructions": { 
                "product": { 
                    "productId": "CFQ7TTC0ZSXT", 
                    "skuId": "0001", 
                    "availabilityId": "CFQ7TTC0K8B0", 
                    "billingCycle": "monthly", 
                    "termDuration": "P1M" 
                }, 
            } 
        } 
    ] 
}

Anfrage mithilfe geplanter Anweisungen für den nächsten Termin

PATCH https://api.partnercenter.microsoft.com/v1/customers/<customer-tenant-id>/subscriptions/<subscription-id> HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: ca7c39f7-1a80-43bc-90d8-ee7d1cad3831
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
If-Match: <etag>
Content-Type: application/json
Content-Length: 1029
Expect: 100-continue
Connection: Keep-Alive

{
    "id": "6e7aa601-629e-461b-8933-0898c3cc3c7c",
    "offerId": "DZH318Z0BXWC:0001:DZH318Z0BMJX",
    "offerName": "offer Name",
    "friendlyName": "friendly Name",
    "quantity": 1,
    "customTermEndDate": "2019-01-09T00:21:45.9263727",
    "unitType": "License(s)",
    "hasPurchasableAddons": false,
    "creationDate": "2019-01-04T01:00:12.6647304Z",
    "effectiveStartDate": "2019-01-09T00:21:45.9263727+00:00",
    "commitmentEndDate": "2019-02-08T00:21:45.9263727+00:00",
    "status": "active",
    "autoRenewEnabled": true,
    "scheduledNextTermInstructions": { 
      "product": { 
         "productId":  "DG7GMGF0DVSV", 
         "skuId":  "000P", 
         "availabilityId":  "DG7GMGF0F3Q9", 
         "billingCycle":  "Annual", 
         "termDuration":  "P3Y",
         "promotionId": "39NFJQT1PFPJ:000H:39NFJQT1Q5DK"
        }, 
      "quantity":  1 
      "customTermEndDate" : "2019-01-09T00:21:45.9263727",
     },  // original value = null 
    "isTrial": false,
    "billingType": "license",
    "billingCycle": "monthly",
    "termDuration": "P1M",
    "refundOptions": [{
        "type": "Full",
        "expiresAt": "2019-01-10T00:21:45.9263727+00:00"
    }],
    "isMicrosoftProduct": false,
    "partnerId": "",
    "contractType": "subscription",
    "publisherName": "publisher Name",
    "orderId": "ImxjLNL4_fOc-2KoyOxGTZcrlIquzls11",
    "attributes": {"objectType": "Subscription"},
}

REST-Antwort

Wenn die Anforderung erfolgreich ist, gibt diese Methode die aktualisierten Eigenschaften der Abonnementressource im Antworttext zurück.

Antworterfolgs- und Fehlercodes

Jede Antwort enthält einen HTTP-Statuscode, der den Erfolg oder Misserfolg angibt, sowie andere Debuginformationen. Verwenden Sie ein Netzwerkablaufverfolgungstool, um diesen Code, fehlertyp und andere Parameter zu lesen. Die vollständige Liste findest du unter Fehlercodes.

Antwort unter Verwendung geplanter Anweisungen für den nächsten Begriff

HTTP/1.1 200 OK
Content-Length: 1322
Content-Type: application/json; charset=utf-8
MS-RequestId: ca7c39f7-1a80-43bc-90d8-ee7d1cad3831
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
X-Locale: en-US

{
    "id": "6e7aa601-629e-461b-8933-0898c3cc3c7c",
    "offerId": "DZH318Z0BXWC:0001:DZH318Z0BMJX",
    "offerName": "offer Name",
    "friendlyName": "friendly Name",
    "quantity": 1,
    "customTermEndDate": "2019-01-09T00:21:45.9263727",
    "unitType": "License(s)",
    "hasPurchasableAddons": false,
    "creationDate": "2019-01-04T01:00:12.6647304Z",
    "effectiveStartDate": "2019-01-09T00:21:45.9263727+00:00",
    "commitmentEndDate": "2019-02-08T00:21:45.9263727+00:00",
    "status": "active",
    "autoRenewEnabled": true,
    "scheduledNextTermInstructions": { 
      "product": { 
         "productId":  "DG7GMGF0DVSV", 
         "skuId":  "000P", 
         "availabilityId":  "DG7GMGF0F3Q9", 
         "billingCycle":  "Annual", 
         "termDuration":  "P3Y",
         "promotionId": "39NFJQT1PFPJ:000H:39NFJQT1Q5DK"
        }, 
      "quantity":  1 
      "customTermEndDate": "2019-01-09T00:21:45.9263727",
     },  // original value = null 
    "isTrial": false,
    "billingType": "license",
    "billingCycle": "monthly",
    "termDuration": "P1M",
    "refundOptions": [{
        "type": "Full",
        "expiresAt": "2019-01-10T00:21:45.9263727+00:00"
    }],
    "isMicrosoftProduct": false,
    "partnerId": "",
    "contractType": "subscription",
    "publisherName": "publisher Name",
    "orderId": "ImxjLNL4_fOc-2KoyOxGTZcrlIquzls11",
    "attributes": {"objectType": "Subscription"},
}
  • Last updated on