Skip to main content

Gerenciar mudanças de plano

O upgrade ou o downgrade de um aplicativo do GitHub Marketplace dispara o webhook do evento marketplace_purchase com a ação changed, o que inicia o fluxo de upgrade ou downgrade.

Para obter mais informações sobre como fazer upgrade e downgrade no que diz respeito à cobrança, confira "Integração à API do GitHub Marketplace".

Etapa 1. Evento de mudança de plano de preços

O GitHub envia o webhook marketplace_purchase com a ação changed para seu aplicativo quando um cliente faz uma dessas alterações no pedido do GitHub Marketplace:

  • Faz a atualização para um plano de preços mais caro ou para um plano de preços mais barato.
  • Adiciona ou remove estações para seu plano existente.
  • Altera o ciclo de cobrança.

O GitHub enviará o webhook quando a alteração entrar em vigor. Por exemplo, quando um cliente faz o downgrade de um plano, o GitHub envia o webhook no final do ciclo de cobrança do cliente. O GitHub envia um webhook para o seu aplicativo imediatamente quando um cliente atualiza seu plano para permitir que acesse o novo serviço imediatamente. Se um cliente mudar de um ciclo de cobrança mensal para anual, isso é considerado uma atualização. Confira "Como cobrar os clientes no GitHub Marketplace" para saber mais sobre as ações que são consideradas um upgrade ou um downgrade.

Leia a effective_date, a marketplace_purchase e a previous_marketplace_purchase no webhook marketplace_purchase para atualizar a data de início do plano e fazer alterações no período de cobrança e no plano de preços do cliente. Confira "Eventos de webhook do GitHub Marketplace" para ver um exemplo da carga do evento marketplace_purchase.

Se o aplicativo oferecer avaliações gratuitas, você receberá o webhook marketplace_purchase com a ação changed quando a avaliação gratuita vencer. Se o teste grátis do cliente expirar, faça a atualização do cliente para a versão paga do plano grátis de teste.

Etapa 2. Atualizar as contas dos clientes

Você precisará atualizar as informações da conta do cliente para refletir as alterações no ciclo de cobrança e no plano de preços que o cliente fez em seu pedido do GitHub Marketplace. Exiba os upgrades para o plano de preços, a seat_count (para os planos de preços por unidade) e o período de cobrança no site do aplicativo do Marketplace ou na interface do usuário do aplicativo quando você receber o webhook de ação changed.

Quando um cliente faz o downgrade de um plano, recomenda-se revisar se o cliente excedeu os limites do seu plano e interagir diretamente com ele na sua interface de usuário ou entrando em contato por telefone ou e-mail.

Para incentivar as pessoas a fazer a atualização, você pode exibir uma URL de upgrade na interface do usuário do seu aplicativo. Confira "Sobre as URLs de upgrade" para obter mais detalhes.

Observação: recomendamos executar uma sincronização periódica usando GET /marketplace_listing/plans/:id/accounts para garantir que o seu aplicativo tenha as informações do período de cobrança, a contagem de unidades e o plano corretos (para o preço por unidade) para cada conta.

Falha nos pagamentos de atualização

No caso em que um cliente atualiza seu plano e o pagamento falhar, o GitHub reverte sua assinatura de GitHub Marketplace ao seu estado anterior. O GitHub também envia um e-mail ao cliente para informá-lo sobre a falha e permitir que ele tente novamente sua compra. Você receberá um webhook com a ação changed solicitando que você reverta para o plano anterior.

Sobre as URLs de atualização

Você pode redirecionar os usuários da interface de usuário do seu aplicativo no GitHub, usando uma URL de atualização:

https://www.github.com/marketplace/<LISTING_NAME>/upgrade/<LISTING_PLAN_NUMBER>/<CUSTOMER_ACCOUNT_ID>

Por exemplo, se você notar que um cliente está em um plano de 5 pessoas e precisa passar para um plano de 10 pessoas, você poderia exibir um botão na interface do usuário do seu aplicativo que diz "Aqui está como atualizar" ou exibir um banner com um link para a URL de atualização. A URL atualização leva o cliente para a página de confirmação de confirmação da atualização do seu plano da listagem.

Use o LISTING_PLAN_NUMBER do plano que o cliente deseja comprar. Quando você cria planos de preços, ele recebe um LISTING_PLAN_NUMBER, que é exclusivo de cada plano na listagem, e uma LISTING_PLAN_ID, que é exclusiva de cada plano no GitHub Marketplace. Encontre esses números ao listar os planos, que identificam os planos de preços da sua listagem. Use a LISTING_PLAN_ID e o ponto de extremidade "Listar as contas de um plano" para obter a CUSTOMER_ACCOUNT_ID.

Observação: se o cliente fizer upgrades para unidades adicionais (como estações), você ainda poderá enviá-las ao plano apropriado da compra dele, porém, no momento, não podemos dar suporte a parâmetros unit_count.