Recuperar e atualizar uma assinatura

Depois de recuperar uma assinatura, use as informações da resposta bem-sucedida para mudar o status da assinatura ou atualizá-la. Esta página se concentra nas diferentes maneiras de recuperar e atualizar uma assinatura.

Recuperar uma assinatura

Para recuperar uma assinatura solicitada ou transferida, use a solicitação HTTP GET a seguir.

GET https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID

Substitua:

  • CUSTOMER_ID: o nome de domínio principal do cliente ou o identificador exclusivo do cliente.
  • SUBSCRIPTION_ID: o identificador de assinatura exclusivo de cada cliente. Para recuperar esse valor, use o método Recuperar todas as assinaturas de revendedor.

Esta operação não tem parâmetros no corpo da solicitação.

Uma resposta bem-sucedida retorna um código de status HTTP 200 e as configurações da assinatura. No exemplo de resposta a seguir, a propriedade isInTrial é false, mas não há uma propriedade trialEndTime, o que significa que esse cliente nunca esteve em um teste sem custo financeiro de 30 dias com esse plano.

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "billingMethod": "ONLINE",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "RENEW_CURRENT_USERS_MONTHLY_PAY"
  },
  "purchaseOrderId": "example.com_annual_1",
  "status": "ACTIVE",
  "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
  "skuName": "Google Workspace Business Standard"
}

Recuperar todas as assinaturas de um cliente

Para recuperar todas as assinaturas de um cliente revendedor específico que foram pedidas ou transferidas, use a seguinte solicitação HTTP GET e inclua o token de autorização:

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=CUSTOMER_ID value&pageToken=START_DATE&maxResults=MAX_NUMBER

Substitua:

  • CUSTOMER_ID: o nome de domínio principal do cliente ou o identificador exclusivo do cliente.
  • START_DATE: a data de início no formato YYYY-MM-DD.
  • MAX_NUMBER: o número máximo de resultados retornados em uma página de resposta.

Esta operação não tem parâmetros no corpo da solicitação.

Uma resposta bem-sucedida retorna um código de status HTTP 200 e uma lista de assinaturas e configurações do cliente. A lista de assinaturas pode incluir produtos que não são gerenciados nessa versão da API Revendedor.

Se você não gerenciar, esse cliente não será gerenciado, um erro 403 "Forbidden" será retornado.

Recuperar todas as assinaturas transferíveis de um cliente

Para recuperar todas as assinaturas de um cliente que podem ser transferidas para o gerenciamento do revendedor, use a seguinte solicitação HTTP GET e inclua o token de autorização. O customerId é obrigatório e é o identificador exclusivo do cliente retornado ao recuperar a conta de um cliente de revenda. O customerAuthToken é um token de transferência fornecido pelo cliente, específico para seu ID de revendedor. Depois de gerado pelo cliente, ele é válido por 30 dias. Para mais informações sobre como os clientes geram o token, consulte Transferir sua conta do Google Workspace para um revendedor.

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=CUSTOMER_ID&customerAuthToken=AUTH_TOKEN&pageToken=START_DATE&maxResults=MAX_NUMBER

Substitua:

  • CUSTOMER_ID: o nome de domínio principal do cliente ou o identificador exclusivo do cliente.
  • AUTH_TOKEN: um token de transferência fornecido pelo cliente, específico para seu ID de revendedor. Depois de gerado pelo cliente, o valor será válido por 30 dias. Para mais informações sobre como os clientes geram o token, consulte Transferir sua conta do Google Workspace para um revendedor. Se esse valor não for válido ou tiver expirado, a resposta da API retornará um erro 403 "Forbidden".
  • START_DATE: a data de início no formato YYYY-MM-DD.
  • MAX_NUMBER: o número máximo de resultados retornados em uma página de resposta.

Esta operação não tem parâmetros no corpo da solicitação.

Uma resposta bem-sucedida retorna um código de status HTTP 200 e uma lista das assinaturas transferíveis do cliente com a data de validade do token de transferência e o número mínimo de licenças necessárias no pedido de transferência. Um cliente pode ter outras assinaturas intransferíveis.

{
  "kind": "reseller#subscriptions",
  "subscriptions": [
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-6543",
      "subscriptionId": "432",
      "skuId": "1010020028",
      "billingMethod": "ONLINE",
      "creationTime": "1331647980142",
      "plan": {
        "planName": "ANNUAL",
        "isCommitmentPlan": true,
        "commitmentInterval": {
          "startTime": "1331647980142",
          "endTime": "1363183980142"
        }
      },
      "seats": {
        "kind": "subscriptions#seats",
        "numberOfSeats": 10,
        "maximumNumberOfSeats": 500,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "transferInfo": {
        "transferabilityExpirationTime": "1333183980142",
        "minimumTransferableSeats": "20"
      },
      "purchaseOrderId": "PO_890",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-6543",
      "subscriptionId": "140",
      "skuId": "1010020028",
      "creationTime": "1329389322728",
      "plan": {
        "planName": "FLEXIBLE",
        "isCommitmentPlan": false
      },
      "seats": {
        "kind": "subscriptions#seats",
        "maximumNumberOfSeats": 50
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false,
        "trialEndTime": "1331877480016"
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "transferInfo": {
        "transferabilityExpirationTime": "1333183780159",
        "minimumTransferableSeats": "10"
      },
      "purchaseOrderId": "",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
  ],
  "nextPageToken": "token"
}

Se você planeja transferir essas assinaturas usando a operação em lote, transfira todas as assinaturas. Transferir cada assinatura uma a uma resulta em um erro. Além disso, a operação em lote transfere apenas assinaturas com um status ACTIVE. Para saber mais, consulte Transferir uma assinatura.

Recuperar todas as assinaturas de revendedor

Para recuperar todas as assinaturas solicitadas ou transferidas de um revendedor, use a seguinte solicitação HTTP GET e inclua o token de autorização.

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=PREFIX &pageToken=TOKEN&maxResults=MAX_NUMBER

Substitua:

  • PREFIX: o início do nome do cliente cujas assinaturas você está procurando.
  • TOKEN: um token que identifica uma página específica de resultados que o servidor precisa retornar.
  • MAX_NUMBER: o número máximo de resultados retornados em uma página de resposta.

Esta operação pode usar o escopo de acesso somente leitura do OAuth. customerNamePrefix, pageToken e maxResults são strings de consulta opcionais.

O exemplo a seguir recupera todas as assinaturas de um revendedor que pertencem a clientes com nomes que começam com "exam":

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=exam

{
  "kind": "reseller#subscriptions",
  "subscriptions": [
    {
      "kind": "subscriptions#subscription",
      "customerId": "C0123456",
      "subscriptionId": "123",
      "skuId": "1010020028",
      "creationTime": "1331647980142",
      "billingMethod": "ONLINE",
      "plan": {
        "planName": "ANNUAL",
        "isCommitmentPlan": true,
        "commitmentInterval": {
          "startTime": "1331647980142",
          "endTime": "1363183980142"
        }
      },
      "seats": {
        "kind": "subscriptions#seats",
        "numberOfSeats": 10,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "purchaseOrderId": "PO_135",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-5678",
      "subscriptionId": "1404686",
      "skuId": "1010020028",
      "billingMethod": "ONLINE",
      "creationTime": "1329389322728",
      "plan": {
        "planName": "FLEXIBLE",
        "isCommitmentPlan": false
      },
      "seats": {
        "kind": "subscriptions#seats",
        "maximumNumberOfSeats": 50,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false,
        "trialEndTime": "1331877480016"
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "AUTO_RENEW"
      },
      "purchaseOrderId": "",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
  ],
  "nextPageToken": "token"
}

Atualizar um plano de assinatura

A atualização dos planos do Google Workspace varia de acordo com o plano. Antes de atualizar um plano, considere o seguinte:

  • Quando você cria uma assinatura e o cliente se qualifica, o plano da assinatura pode ser um teste de 30 dias. Os planos de pagamento flexível e anual podem ser testes sem custo financeiro de 30 dias. Durante o teste, é possível mudar o plano de pagamento da assinatura para planos flexíveis ou anuais sempre que necessário. No entanto, após o fim da avaliação e o plano se tornar ativo, a atualização do plano segue as mesmas regras dos planos ativos de outras assinaturas. Para mover imediatamente uma assinatura de teste para um plano ativo, inicie um serviço pago com uma assinatura de teste sem custo financeiro de 30 dias. Para acessar mais informações sobre testes de 30 dias e regras de qualificação do cliente, consulte a Central de Ajuda para administração.

  • Você pode atualizar um plano flexível para um plano anual.

  • Não é possível atualizar um plano com contrato anual.

  • Nem todos os planos funcionam com todos os produtos. Para mais informações sobre quais produtos são usados por esses planos, consulte Produtos e SKUs.

Para atualizar um plano de teste de 30 dias ou de uma assinatura de plano flexível para um plano de compromisso anual, use a seguinte solicitação HTTP POST:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changePlan

Substitua:

  • CUSTOMER_ID: o nome de domínio principal do cliente ou o identificador exclusivo do cliente.
  • SUBSCRIPTION_ID: o identificador de assinatura exclusivo de cada cliente. Para recuperar esse valor, use o método Recuperar todas as assinaturas de revendedor.

O exemplo a seguir atualiza a assinatura com o subscriptionId com um valor de 123. O customerId é C0123456.

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/changePlan

O corpo da solicitação tem o seguinte:

{
  "kind": "reseller#changePlanRequest",
  "planName": "ANNUAL_MONTHLY_PAY",
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10
  },
  "purchaseOrderId": "123_March2012"
}

Uma resposta bem-sucedida retorna um código de status HTTP 201 e retorna as configurações atualizadas do plano de assinatura:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "purchaseOrderId": "123_March2012",
  "status": "ACTIVE",
  "skuName": "Google Workspace Business Standard"
}

Atualizar os assentos de uma assinatura

A atualização da assinatura de um plano de compromisso anual usa propriedades de assinatura diferentes do que a atualização da assinatura de um plano flexível do Google Workspace.

Atualizar licenças por usuário para a assinatura de um plano anual

Para atualizar as configurações de licença de usuário de uma assinatura de plano anual, use a seguinte solicitação HTTP POST:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changeSeats

Substitua:

  • CUSTOMER_ID: o nome de domínio principal do cliente ou o identificador exclusivo do cliente.
  • SUBSCRIPTION_ID: o identificador de assinatura exclusivo de cada cliente. Para recuperar esse valor, use o método Recuperar todas as assinaturas de revendedor.

O exemplo a seguir atualiza a assinatura com o subscriptionId 123. O customerId é C0123456. O corpo da solicitação varia de acordo com o tipo de plano:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/changeSeats

A assinatura de um plano de compromisso anual do Google Workspace usa o corpo da solicitação para atualizar o número de licenças de usuário. O valor de numberOfSeats é um total. Por exemplo, se você já tinha 10 licenças de usuário e tem um pedido de cliente para cinco novas licenças, o total no corpo da solicitação para numberOfSeats é 15, conforme mostrado no exemplo a seguir:

{
    "kind": "subscriptions#seats",
    "numberOfSeats": 15
}

Atualizar licenças por usuário de um plano flexível

A assinatura de um plano flexível do Google Workspace usa o corpo da solicitação para atualizar as licenças de usuário. O valor de maximumNumberOfSeats é o total de licenças atuais e novas. Esse é o número máximo de licenças de usuário que a conta pode provisionar.

{
  "kind": "subscriptions#seats",
  "maximumNumberOfSeats": 15
}

Uma resposta bem-sucedida retorna um código de status HTTP 201 e as configurações atualizadas da licença de assinatura:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "FLEXIBLE",
    "isCommitmentPlan": false
  },
  "seats": {
    "kind": "subscriptions#seats",
    "maximumNumberOfSeats": 15,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "skuName": "Google Workspace Business Standard"
}

Atualizar as configurações de renovação de uma assinatura

Para atualizar as configurações de renovação de uma assinatura de compromisso anual, use a seguinte solicitação HTTP POST:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changeRenewalSettings

Substitua:

  • CUSTOMER_ID: o nome de domínio principal do cliente ou o identificador exclusivo do cliente.
  • SUBSCRIPTION_ID: o identificador de assinatura exclusivo de cada cliente. Para recuperar esse valor, use o método Recuperar todas as assinaturas de revendedor.

Confira a seguir um exemplo de corpo de solicitação:

{
  "kind": "subscriptions#renewalSettings",
  "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
}

O valor da propriedade renewalType pode ser qualquer um destes:

  • AUTO_RENEW_YEARLY_PAY: no final do intervalo de um plano de compromisso anual, renova automaticamente o plano da assinatura como ANNUAL_YEARLY_PAY com o mesmo numberOfSeats.
  • AUTO_RENEW_MONTHLY_PAY: ao final do intervalo de um plano de compromisso anual, renova automaticamente o plano das assinaturas como ANNUAL_MONTHLY_PAY com o mesmo numberOfSeats.
  • RENEW_CURRENT_USERS_YEARLY_PAY: ao final do intervalo de um plano de compromisso anual, renove o plano da assinatura como ANNUAL_YEARLY_PAY, mas use o número total de licenças de usuário ativas atuais. Essa é a configuração padrão para planos de compromisso anuais ativos (pagos anualmente).
  • RENEW_CURRENT_USERS_MONTHLY_PAY: ao final do intervalo de um plano de compromisso anual, renove o plano da assinatura como ANNUAL_MONTHLY_PAY, mas use o número total de licenças de usuário ativas atuais. Essa é a configuração padrão para planos de compromisso anuais ativos (pagos mensalmente).
  • RENEW_ON_PROPOSED_OFFER: ao final do intervalo do plano de compromisso atual, renove na proposta de renovação mais recente com numberOfSeats como número de licenças de usuário ativas atuais ou compromisso da oferta proposta, o que for maior.
  • SWITCH_TO_PAY_AS_YOU_GO: no final do intervalo de um plano de compromisso anual, altere o plano de compromisso anual para um flexível.
  • CANCEL: ao final do intervalo de um plano de compromisso anual, a assinatura é suspensa. Para entender como cancelar uma suspensão, consulte a Central de Ajuda de administração.

Uma resposta bem-sucedida retorna um código de status HTTP 201 e as configurações atualizadas de renovação da assinatura:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 15,
    "licensedNumberOfSeats": 15
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "skuName": "Google Workspace Business Standard"
}

Iniciar o serviço pago com uma assinatura de teste sem custo financeiro

Para mover imediatamente uma assinatura de teste sem custo financeiro de 30 dias para uma assinatura de serviço pago, se um plano de pagamento já tiver sido configurado para a assinatura de teste, use a seguinte solicitação HTTP POST.

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/startPaidService

Substitua:

  • CUSTOMER_ID: o nome de domínio principal do cliente ou o identificador exclusivo do cliente.
  • SUBSCRIPTION_ID: o identificador de assinatura exclusivo de cada cliente. Para recuperar esse valor, use o método Recuperar todas as assinaturas de revendedor.

O exemplo a seguir tem C0123456 como customerId e o valor subscriptionId de 123:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/startPaidService

Esta operação não tem parâmetros no corpo da solicitação.

Uma resposta bem-sucedida retorna um código de status HTTP 201 e as configurações de assinatura atualizadas:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 15,
    "licensedNumberOfSeats": 15
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "skuName": "Google Workspace Business Standard"
}

Fazer upgrade ou downgrade de uma assinatura

Não é possível fazer downgrade de planos anuais no meio da vigência nem programar um downgrade usando as configurações de renovação. Recomendamos que você defina as configurações de renovação para FLEXIBLE e, em seguida, faça downgrade após o momento da renovação.

Para fazer upgrade ou downgrade, crie uma nova assinatura com o skuId para o qual você quer fazer upgrade ou downgrade.

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions

Substitua:

  • CUSTOMER_ID: o nome de domínio principal do cliente ou o identificador exclusivo do cliente.

Esta chamada encerra a assinatura anterior e cria uma nova.

Encontre mais informações sobre upgrades e downgrades na página "Produtos e SKUs".