Note
Este artigo se aplica somente à publicação de aplicativos do GitHub Marketplace. Para obter mais informações 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 Usar a API do GitHub Marketplace no seu aplicativo.
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 Cobrar dos 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 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 do 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 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.
Note
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 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 o LISTING_PLAN_ID e o ponto de extremidade GET /marketplace_listing/plans/{plan_id}/accounts para obter o CUSTOMER_ACCOUNT_ID.
Note
Se o cliente fizer atualizações 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.