Agendar alterações para uma nova assinatura de comércio usando APIs do Partner Center

se aplica a: Partner Center

Este artigo descreve como você pode usar a API do Partner Center para agendar alterações para um novo de assinatura dede comércio , que só ocorrem na renovação. Esta API suporta novas subscrições de software e baseadas em licenças comerciais.

A criação de alterações agendadas permite-lhe modificar a sua subscrição, automaticamente, quando ocorrer a próxima renovação. Ao agendar alterações, você pode optar por aumentar ou diminuir o número de licenças, modificar o prazo e a frequência de cobrança e até mesmo optar por atualizar o SKU. O agendamento de alterações permite que você faça modificações em sua assinatura na renovação, em vez de imediatamente durante o período atual.

Pré-requisitos

• Credenciais conforme descrito na autenticação no Partner Center . Este cenário oferece suporte à autenticação com credenciais autônomas de Aplicativo e Aplicativo+Usuário.

• Um ID de cliente (customer-tenant-id). Se não souber o ID do cliente, pode procurá-lo no do Partner Center selecionando espaço de trabalho Clientes, depois o cliente da lista de clientes e, em seguida, Conta. Na página Conta do cliente, procure o ID da Microsoft na seção Informações da Conta do Cliente. A ID da Microsoft é a mesma que a ID do cliente (customer-tenant-id).

• Um ID de subscrição.

• A renovação automática está ativada na subscrição.

Método do Partner Center

Para agendar alterações para uma assinatura no Partner Center:

1. Selecione um cliente.

2. Selecione a subscrição para a qual pretende agendar alterações.

3. Habilite a renovação automática.

4. Selecione Gerenciar renovação.

5. Faça modificações na assinatura para que entrem em vigor na renovação.

6. Selecione Ok para fechar o painel lateral.

7. selecione Enviar para salvar as alterações.

C#

Para agendar alterações para a assinatura de um cliente:

1. Obtenha a subscrição por ID.
2. Obter a elegibilidade de transição para o tipo de elegibilidade de transição agendada.
3. Crie um objeto ScheduledNextTermInstructions e associe-o à propriedade da assinatura.
4. Chame o método Patch() para atualizar a assinatura com as alterações agendadas.

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

Para agendar alterações para a assinatura de um cliente, onde a alteração agendada desejada é para um produto diferente:

1. Obtenha a subscrição por ID.
2. Obter a elegibilidade de transição para o tipo de elegibilidade de transição agendada.
3. Chame o método Patch() para atualizar a assinatura com as alterações agendadas.

Pedido REST

Sintaxe da solicitação

Parâmetro URI

Esta tabela lista os parâmetros de consulta necessários para chamar a API.

Cabeçalhos de solicitação

Para obter mais informações, consulte cabeçalhos REST do Partner Center.

Corpo do pedido

É necessário um recurso completo de Subscrição de no corpo do pedido, com a propriedade scheduledNextTermInstructions definida. Para agendar alterações para sua assinatura, verifique se a propriedade AutoRenewEnabled está definida como true.

Para o ID de disponibilidade no fim da venda com conversões, as ofertas do EndofSaleWithConversions são:

1. GetTransitionEligibility para retornar CatalogItemID.

   um. Certifique-se de definir o tipo de elegibilidade Programado, senão o padrão será imediato.

2. Utilize o CatalogItemID para então extrair o availabilityID.

Se você estiver usando GET Availabilities para determinar a disponibilidade para as instruções agendadas NextTerm e se todos os termos estiverem no estado EOS, você receberá uma lista vazia. A melhor maneira de determinar caminhos válidos é chamar a API GetTransitionEligibilty para retornar as opções válidas.

Usar ScheduledActions para definir instruções de próximo período (alterações agendadas)

Os termos de serviço prolongado introduzem uma nova forma de definir instruções de fim de mandato. O novo construto scheduledActions permite aos parceiros uma única forma de definir as atualizações do próximo mandato, incluindo cancelamento, renovação para períodos de serviço estendidos ou renovação para outras metas de fim de mandato. Os parceiros podem definir as instruções RenewToNewTerm de scheduledActions em vez das anteriores scheduledNextTermInstructions. Mais informações sobre a utilização de ScheduledActions para definir instruções de próximo prazo podem ser encontradas na documentação do prazo de serviço estendido.

Os parceiros que utilizam o ScheduledActions devem evitar também passar o scheduledNextTermInstructions ao fazer atualizações para subscrições elegíveis para prazos de serviço prolongados. Os parceiros podem optar por passar ambos devem perceber que apenas as Ações Programadas são consideradas. Os parceiros podem continuar a passar apenas scheduledNextTermInstructions para definir as instruções para o próximo período.

Pedido usando ações agendadas

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

Resposta usando ações agendadas

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

Utilizar scheduledActions para definir transições no aniversário

Alguns SKUs selecionados de três anos com equipas podem ser agendados para a transição no aniversário do mandato.

Pedido usando ações agendadas

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

Pedido usando instruções agendadas para o próximo período

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

Resposta REST

Se a solicitação for bem-sucedida, esse método retornará as propriedades atualizadas do recurso Subscription no corpo da resposta.

Códigos de sucesso e erro de resposta

Cada resposta vem com um código de status HTTP que indica sucesso ou falha e outras informações de depuração. Use uma ferramenta de rastreamento de rede para ler esse código, tipo de erro e outros parâmetros. Para obter a lista completa, consulte Códigos de erro.

Resposta usando instruções agendadas para o próximo período

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