> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Solução de problemas de upgrades de assinatura
> Correções para problemas comuns dos Upgrades de Assinatura, incluindo alertas de falha de upgrade, problemas de conexão com o provedor e dropdowns de planos de venda vazios.
Correções para os problemas mais comuns dos Upgrades de Assinatura. Se você continuar travado depois de tentar estas soluções, entre em contato com o suporte com os detalhes listados em [Testando e verificando](/pt/aftersell/subscription-upgrades-testing#when-something-looks-wrong).
## Monitorando falhas de upgrade
O Aftersell monitora falhas terminais de upgrade em uma janela móvel de 7 dias. Se o número de falhas ultrapassar o limite de alerta, um **banner de aviso** aparece na sua página inicial descrevendo quantos upgrades falharam e em quantos dias. O mesmo alerta também aparece no painel **Needs attention** da [página inicial](/pt/aftersell/home/needs-attention).
O alerta inclui um botão **Review orders** que leva você diretamente ao navegador de pedidos filtrado por problemas de upgrade de assinatura, para que você possa ver os pedidos afetados e a causa específica de cada falha. Ele desaparece automaticamente quando a contagem de falhas cai abaixo do limite dentro da janela móvel. Se você vir esse alerta, abra o navegador de pedidos, verifique a causa exibida em cada pedido afetado e consulte as etapas de solução de problemas relevantes abaixo.
O template **Subscription Upgrade** nunca fica oculto — ele está sempre listado em **Add Funnel**, seja qual for a configuração do seu provedor. O que bloqueia você é a verificação de conexão da Etapa 1: **Continue** permanece desabilitado até que **Test API key** retorne **API key verified** com uma marca verde.
Dois resultados diferentes exibem o mesmo ícone vermelho de cancelamento, então leia a mensagem ao lado dele:
* **Seu provedor rejeitou a chave.** O token está sem os escopos necessários ou foi revogado, e a mensagem indica o problema específico. Emita um novo token no painel do seu provedor com os escopos listados em [Configuração](/pt/aftersell/subscription-upgrades-setup), cole-o e teste novamente.
* **O Aftersell não conseguiu alcançar seu provedor** — "Could not verify the API key. Please try again." Não há necessariamente nada de errado com o token; a chamada em si falhou. Clique em **Test API key** novamente.
Editar o provedor ou o token limpa o veredito anterior, então teste novamente após qualquer alteração.
Esse é o comportamento esperado. O produto é o produto da oferta, o item de linha placeholder adicionado ao pedido da Shopify como registro do upgrade aceito. Para reduzir a confusão, renomeie o produto da oferta para algo claro e adicione uma descrição no Shopify Admin explicando o que ele representa. Consulte [O que o cliente vê](/pt/aftersell/subscription-upgrades#what-the-customer-sees).
O changeset da Shopify e a chamada de API ao provedor são independentes. Se o produto da oferta foi adicionado ao pedido, mas a assinatura não foi alterada, as causas mais comuns são:
* O token de API do seu provedor está expirado ou não possui as permissões necessárias. Para o Recharge, o token deve ter `read_orders`, `read_subscriptions`, `write_subscriptions` e `read_plans`. Vá para a **Etapa 1: Connect provider**, teste novamente sua chave e verifique a mensagem de erro para identificar os escopos que faltam.
* O produto elegível no funil não corresponde ao que o cliente realmente assinou.
* Para o Loop, o plano de venda alvo não existe no seu painel do Loop para a frequência configurada.
* O fluxo de novas tentativas ainda pode estar seguindo seu cronograma: após uma chamada com falha, ele tenta novamente em +1 hora e depois em +24 horas. Isso é igual para todos os provedores — inclusive o Loop, cujas chamadas de upgrade são síncronas e aparecem no painel imediatamente quando bem-sucedidas.
O Aftersell tenta novamente de forma automática as chamadas ao provedor que falharam em um fluxo de trabalho em segundo plano. O fluxo verifica o estado atual do provedor antes de executar novamente, para que um upgrade bem-sucedido mas lento não seja aplicado duas vezes.
Se uma nova execução não puder corrigir a causa, o fluxo **reembolsa a cobrança** — quando nenhuma mutação no provedor teve sucesso e a linha cobrada era um placeholder — ou marca o upgrade para **reconciliação manual**, deixando o pedido intacto. Assinaturas totalmente novas e upgrades de box nunca são reembolsados automaticamente, porque o comprador recebe produtos reais. Entre em contato com o suporte com os detalhes listados em [Testando e verificando](/pt/aftersell/subscription-upgrades-testing#when-something-looks-wrong).
A opção "Use an existing selling plan" busca os planos diretamente do Recharge, Skio ou Loop. Se o dropdown estiver vazio:
* Confirme se os planos de venda estão configurados no painel do seu provedor.
* Verifique se o seu token de API tem acesso de leitura a Plans (Recharge: escopo `read_plans`) ou os escopos apropriados (Skio, Loop).
* Volte à **Etapa 1: Connect provider**, teste novamente sua chave de API e continue.
Isso é esperado. No Loop, o campo **Billing frequency** não é exibido — apenas **Delivery frequency**, com a observação "Loop syncs billing to delivery — customers are charged on each renewal". O que você definir como frequência de entrega também será a frequência de cobrança.
É também por isso que assinaturas pré-pagas — uma frequência de cobrança maior que a frequência de entrega — não são suportadas no Loop: a integração as rejeita diretamente em vez de oferecer um campo que você não pode usar. Os demais provedores mostram ambos os campos.
O produto da oferta é exclusivo de assinatura — seja o produto em si, seja cada uma de suas variantes — e o checkout do cliente já continha uma assinatura. A Shopify não permite uma segunda assinatura no mesmo pedido, então a oferta foi ignorada.
O painel de detalhes do pedido esclarece qual foi o caso: "The customer's checkout already has a subscription, and the offer product is subscription-only" ou "All variants of the offer product are subscriptions, and the customer's checkout already has one." Ambos são corrigidos da mesma forma — edite a seleção de produto da oferta e troque por um produto de compra única, ou use a opção **Create new** na **Etapa 4: Offer product** para gerar um placeholder.
* Verifique se **Show this funnel for all customers** não está habilitado. Isso sobrepõe todos os outros gatilhos.
* Verifique o gatilho **Variant on subscription**. Ele exibe o funil apenas quando o pedido inclui um dos produtos selecionados *comprado como assinatura*. Em um funil que tem uma oferta de upgrade de assinatura, o assistente é dono desse gatilho e o mantém sincronizado com o produto que está recebendo o upgrade, então ele é somente leitura — o painel exibe "Managed by this funnel's subscription upgrade offer." Se ele estiver visando os produtos errados, corrija o produto gatilho da oferta de upgrade em vez do gatilho em si.
* Verifique a prioridade do funil. Um funil de prioridade mais alta com gatilhos mais amplos pode estar disparando primeiro.
Não tente reproduzir isso com um gatilho de produto separado mais um gatilho de assinatura. Essa combinação é exatamente o que **Variant on subscription** substituiu: os dois eram avaliados de forma independente, então um pedido contendo o seu produto gatilho como compra única *e* um item de assinatura não relacionado satisfazia ambos, disparava o funil, e o upgrade falhava depois. Um único gatilho, que combina produto e estado de assinatura juntos, é a configuração suportada.