Планирование изменений для новой коммерческой подписки с помощью API Центра партнеров

Статья
03/07/2025

применимо к: Центр партнеров

В этой статье описывается, как использовать API Центра партнеров для планирования изменений для новой коммерческой подписки, которые вступают в силу только при продлении. Этот API поддерживает новые лицензированные и программные подписки на основе коммерческой коммерции.

Заметка

Новые коммерческие возможности для служб на основе лицензий включают множество новых возможностей и доступны для всех поставщиков облачных решений (CSPS). Для получения дополнительной информации смотрите обзор новых коммерческих возможностей .

Создание запланированных изменений позволяет автоматически изменять подписку при следующем продлении. Запланируя изменения, вы можете увеличить или уменьшить количество лицензий, изменить срок и частоту выставления счетов, а также даже обновить номер SKU. Планирование изменений позволяет вносить изменения в подписку при продлении, а не сразу в течение текущего срока.

Важный

Если вы вносите изменение в середине срока (немедленно) до даты продления, все запланированные изменения, которые ранее были запланированы на продление, удаляются.

Необходимые условия

Учетные данные, как описано в аутентификации Центра партнеров. Этот сценарий поддерживает проверку подлинности с помощью автономных учетных данных приложения и учетных данных приложения и пользователя.
Идентификатор клиента (customer-tenant-id). Если вы не знаете идентификатор клиента, вы можете найти его в Центре партнеров, выбрав рабочую область клиентов , затем выбрав клиента из списка, а потом учетную запись. На странице "Учетная запись клиента" найдите идентификатор Майкрософт в разделе Сведения об учетной записи клиента. Идентификатор Майкрософт совпадает с идентификатором клиента (customer-tenant-id).
Идентификатор подписки.
Автоматическое продление в подписке включено.

Метод Центра партнеров

Чтобы запланировать изменения подписки в Центре партнеров, выполните следующее:

Выберите клиента.
Выберите подписку, для которой нужно запланировать изменения.
Включите автоматическое продление.
Выберите Управление продлением.
Внесите изменения в подписку, которые будут выполняться при продлении.
Нажмите кнопку "Ок", чтобы закрыть боковую панель.
Выберите Отправить, чтобы сохранить изменения.

Заметка

Продления обрабатываются после последнего дня срока, начиная с 12:00 в формате UTC на следующий день. Продление обрабатывается в очереди и может занять до 24 часов.

C#

Чтобы запланировать изменения подписки клиента, выполните следующее:

Получите подписку по идентификатору.
получить право на переход для типа запланированного перехода.
Создайте объект ScheduledNextTermInstructions и задайте его свойству подписки.
Вызовите метод Patch(), чтобы обновить подписку с запланированными изменениями.

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

Чтобы запланировать изменения подписки клиента для перехода на другой продукт:

Получить подписку по идентификатору.
получить право на переходные условия для запланированного типа перехода.
Вызовите метод Patch(), чтобы обновить подписку с запланированными изменениями.

Запрос REST

Синтаксис запроса

Метод	URI запроса
PATCH	{baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{subscription-id} HTTP/1.1

Параметр URI

В этой таблице перечислены необходимые параметры запроса для вызова API.

Имя	Тип	Обязательно	Описание
идентификатор арендатора-клиента	guid	Y	GUID, соответствующий данному клиенту.
идентификатор подписки	гайд	Y	GUID, соответствующий подписке.

Заголовки запросов

Дополнительные сведения о заголовках REST Центра партнёров см. в .

Текст запроса

В тексте запроса требуется полный ресурс подписки с определенным свойством scheduledNextTermInstructions. Чтобы запланировать изменения подписки, убедитесь, что для свойства AutoRenewEnabled задано значение true .

Для ID доступности на конец продажи с предложениями о конверсиях (EndofSaleWithConversions):

Метод GetTransitionEligibility возвращает CatalogItemID.

a. Не забудьте задать тип планируемой доступности, иначе по умолчанию будет немедленное.
Используйте CatalogItemID, чтобы извлечь идентификатор доступности.

Заметка

Если вы используете метод GET Availabilities для определения доступности scheduledNextTerm, и если все термины находятся в состоянии EOS, вы получите пустой список. Лучший способ определить допустимые пути — вызвать API GetTransitionEligibilty для возврата допустимых параметров.

Поле	Тип	Обязательно	Описание
scheduledNextTermInstructions	объекта	Y	Определяет инструкции для следующего периода подписки. Свойство содержит объект `product` и поле `quantity`.

Пример запроса

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

Если запрос выполнен успешно, этот метод возвращает обновленные свойства ресурса подписки в тексте ответа.

Коды успешного ответа и коды ошибок

Каждый ответ содержит код состояния HTTP, указывающий на успешность или сбой, а также другие сведения об отладке. Используйте средство трассировки сети для чтения этого кода, типа ошибки и других параметров. Полный список см. в разделе Коды ошибок.

Пример ответа

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

Поделиться через

Планирование изменений для новой коммерческой подписки с помощью API Центра партнеров

Необходимые условия

Метод Центра партнеров

C#

Запрос REST

Синтаксис запроса

Параметр URI

Заголовки запросов

Текст запроса

Пример запроса

Ответ REST

Коды успешного ответа и коды ошибок

Пример ответа

Обратная связь

Дополнительные ресурсы