Schedule changes for a new commerce subscription using Partner Center APIs

Applies To: Partner Center

This article describes how you can use Partner Center API to schedule changes for a new commerce subscription, that only take place on renewal. This API supports new commerce licensed-based and software subscriptions.

Creating scheduled changes allows you to modify your subscription, automatically, when the next renewal occurs. By scheduling changes, you can choose to increase or decrease the number of licenses, modify the billing term and frequency, and even choose to upgrade the SKU. Scheduling changes allows you to make modifications to your subscription on renewal, rather than immediately during the current term.

Prerequisites

• Credentials as described in Partner Center authentication. This scenario supports authentication with both standalone App and App+User credentials.

• A customer ID (customer-tenant-id). If you don't know the customer's ID, you can look it up in Partner Center by selecting the Customers workspace, then the customer from the customer list, then Account. On the customer's Account page, look for the Microsoft ID in the Customer Account Info section. The Microsoft ID is the same as the customer ID (customer-tenant-id).

• A subscription ID.

• Auto-renew is enabled on the subscription.

Partner Center method

To schedule changes for a subscription in Partner Center:

1. Select a customer.

2. Select the subscription that you wish to schedule changes for.

3. Enable Auto-renew.

4. Select Manage renewal.

5. Make modifications to the subscription to take place on renewal.

6. Select Okay to close the side panel.

7. select Submit to save the changes.

C#

To schedules changes for a customer's subscription:

1. Get the subscription by ID.
2. Get transition eligibility for scheduled transition eligibility type.
3. Create a ScheduledNextTermInstructions object and set it to the subscription's property.
4. Call the Patch() method to update the subscription with the scheduled changes.

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);

To schedule changes for a customer's subscription, where the scheduled change desired is to a different product:

1. Get the subscription by ID.
2. Get transition eligibility for scheduled transition eligibility type.
3. Call the Patch() method to update the subscription with the scheduled changes.

REST request

Request syntax

URI parameter

This table lists the required query parameters to call the API.

Request headers

For more information, see Partner Center REST headers.

Request body

A full Subscription resource is required in the request body, with the scheduledNextTermInstructions property defined. To schedule changes for your subscription, ensure that the AutoRenewEnabled property is set to true.

For availability ID on end of sale with conversions (EndofSaleWithConversions) offers:

1. GetTransitionEligibility to return CatalogItemID.

   a. Make sure to set the Scheduled eligibility type otherwise the default is immediate.

2. Use CatalogItemID to then extract availabilityID.

If you are using GET Availabilities to determine the availability for the scheduledNextTerm Instructions and if all the terms are EOS state, you will receive an empty list. The best way to determine valid paths is to call the GetTransitionEligibilty API to return the valid options.

Using scheduledActions to set next term instructions (scheduled changes)

Extended service terms introduce a new way to set end of term instructions. The new construct scheduledActions allowes partners a single way to define next term updates including cancelation, renew to extended service terms, or renewing to other end of term targets. Partners can set the scheduledActions RenewToNewTerm instructions instead of previous scheduledNextTermInstructions. More about using scheduledActions to set next term instructions can be found in the extended service term documentation.

Partners using scheduledActions should avoid also passing scheduledNextTermInstructions when making updates for subscriptions eligible for extended service terms. Partners can choose to pass both should realize that only scheduledActions are considered. Partners can continue to pass only scheduledNextTermInstructions for setting next term instructions.

Request using scheduled actions

{
  "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"
      }
    }
  ]
}

Response using scheduled actions

{
  "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"
      }
    }
  ]
}

Request using scheduled next term instructions

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 response

If the request is successful, this method returns the updated Subscription resource properties in the response body.

Response success and error codes

Each response comes with an HTTP status code that indicates success or failure, and other debugging information. Use a network trace tool to read this code, error type, and other parameters. For the full list, see Error Codes.

Response using scheduled next term instructions

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"},
}