Observação
Este artigo se aplica somente à publicação de aplicativos do GitHub Marketplace. Para saber mais sobre como publicar o GitHub Actions no GitHub Marketplace, confira Publicar ações no GitHub Marketplace.
Para obter mais informações sobre como fazer o upgrade e downgrade no que se refere à cobrança, confira Usando a API do Marketplace GitHub em seu aplicativo.
Etapa 1. Evento de mudança de plano de preços
GitHub envia o webhook marketplace_purchase com a ação changed para o seu aplicativo, quando um cliente realiza qualquer uma dessas alterações no pedido 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.
GitHub enviará o webhook quando a alteração entra em vigor. Por exemplo, quando um cliente faz downgrade de um plano, GitHub envia o webhook no final do ciclo de cobrança do cliente. GitHub envia um webhook para seu aplicativo imediatamente quando um cliente atualiza seu plano para permitir que ele 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 Faturamento de clientes para saber mais sobre quais ações são consideradas um upgrade ou downgrade.
Leia a effective_date, a marketplace_purchase e a previous_marketplace_purchase do webhook marketplace_purchase para atualizar a data de início do plano e fazer alterações no ciclo de cobrança e no plano de preços do cliente. Confira Eventos de webhook para a API do GitHub Marketplace para obter 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 as atualizações do plano de preços, a seat_count (para os planos de preços por unidade) e o ciclo de cobrança no site do aplicativo do Marketplace ou na interface 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 fazer uma sincronização periódica usando GET /marketplace_listing/plans/:id/accounts para garantir que o seu aplicativo tenha as informações do ciclo de cobrança, a contagem de unidades (para o preço por unidade) e o plano corretos para cada conta.
Falha nos pagamentos de atualização
Se um cliente atualizar o plano e o pagamento falhar, o GitHub reverterá a assinatura do GitHub Marketplace para o estado anterior. O GitHub também envia um email ao cliente para informá-lo sobre a falha e permitir que ele tente realizar a compra novamente. 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 usuários da interface do aplicativo para atualizar no GitHub usando um link 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 de atualização leva o cliente para a página de confirmação da atualização do seu plano de listagem.
Utilize o LISTING_PLAN_NUMBER do plano que o cliente deseja comprar. Quando você cria novos planos de preços, eles recebem um LISTING_PLAN_NUMBER, que é único para cada plano na sua listagem, e um LISTING_PLAN_ID, que é único para cada plano no GitHub Marketplace. Encontre esses números ao listar os planos, que identificam os planos de preços da sua listagem. Use o LISTING_PLAN_ID e o ponto de extremidade GET /marketplace_listing/plans/{plan_id}/accounts para obter o CUSTOMER_ACCOUNT_ID.
Observação
Se o cliente atualizar para unidades adicionais (como assentos), você ainda poderá enviá-los ao plano apropriado da compra dele; porém, no momento, não podemos dar suporte a parâmetros unit_count.