> ## 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.
# Referência de configuração de upgrades de assinatura
Esta página reúne as regras detalhadas por trás do assistente de configuração do Subscription Upgrade: como os preços são derivados, como as opções de momento e de desconto se comportam, o gatilho de elegibilidade e por que o produto da oferta é um placeholder. Para o passo a passo, veja [Configurando upgrades de assinatura](/pt/aftersell/subscription-upgrades-setup).
## Estados de verificação da chave de API
Na Etapa 1, **Test API key** valida o seu token junto ao seu provedor, verificando se ele autentica, se tem todos os escopos necessários e se pertence à sua loja. O resultado mostra um de dois estados:
* **Marca verde, "API key verified".** O token autenticou, todos os escopos necessários estão presentes e o token pertence à sua loja. **Continue** fica habilitado.
* **Ícone vermelho de cancelamento.** A verificação não foi bem-sucedida. A mensagem ao lado do ícone diz qual de duas coisas aconteceu: o seu provedor **rejeitou** o token (revogado ou sem os escopos necessários, e a mensagem indica o problema específico), ou a Aftersell **não conseguiu concluir a verificação** ("Could not verify the API key. Please try again."), o que é uma chamada que falhou, e não um token inválido. Corrija o token se ele foi rejeitado; caso contrário, apenas teste novamente.
Não existe um terceiro estado mais brando, e um resultado de não verificação parece exatamente igual a uma rejeição, então leia a mensagem em vez de se basear no ícone. **Continue** permanece desabilitado até que a verificação fique verde. Editar o provedor ou o token limpa o resultado anterior, então teste novamente após qualquer alteração. Essa barreira existe para evitar falhas de upgrade de assinatura que, de outra forma, só apareceriam depois que um cliente já tivesse sido cobrado.
## O gatilho de elegibilidade: Variant on subscription
O assistente configura automaticamente um único gatilho para você; não é necessário configurá-lo manualmente:
| Gatilho | Configuração |
| - | - |
| **Variant on subscription** | Definido para a sua variante elegível (alvo). Dispara somente quando essa variante está no pedido **em uma linha de assinatura**. |
Todos os gatilhos ativados usam lógica AND: todas as condições precisam ser atendidas para que o funil seja exibido. Você pode adicionar outros gatilhos opcionais na etapa **Triggers** do editor de funil (agrupados em uma seção recolhível **Additional triggers**, que mostra uma contagem e se abre automaticamente quando há gatilhos opcionais definidos).
**Não substitua isso por um gatilho de Product mais um gatilho de Subscription.** Essa combinação antiga é composta por duas condições independentes, então um pedido que contenha o seu produto gatilho como compra *única* junto com um item de assinatura *não relacionado* satisfaz ambas: o funil dispara e o upgrade falha depois, porque não há uma assinatura correspondente para alterar. **Variant on subscription** é uma condição única que não pode se separar dessa forma, e o assistente migra automaticamente os funis antigos que usam essa combinação.
Sem um gatilho específico de produto, um funil pode ser exibido para clientes que não têm o produto de assinatura elegível no pedido. Isso desperdiça impressões e gera uma modificação de assinatura que falha silenciosamente: o produto da oferta é adicionado ao pedido, mas nenhuma assinatura é alterada no Recharge, Skio ou Loop.
Se **Show this funnel for all customers** estiver ativado, ele substitui todos os outros gatilhos e o funil dispara em todos os checkouts. Isso não é recomendado para funis de upgrade de assinatura.
## Qual preço o Recurring subtotal mostra
O **Recurring subtotal** na oferta informa ao cliente quanto custará a próxima renovação. O produto de onde esse preço é obtido depende do tipo de upgrade:
| Tipo de upgrade | O preço vem de |
| - | - |
| Change delivery or billing frequency | O produto **gatilho** |
| Replace with a different subscription product | O produto de **substituição** |
| Both, change frequency and replace subscription product | O produto de **substituição** |
| Add another subscribable item to subscription | O item **adicionado** |
Esta é a fonte de confusão mais comum. Um upgrade somente de frequência mantém o mesmo produto por definição, então o subtotal recorrente dele só pode mostrar o preço do produto gatilho, seja qual for a frequência definida. Se você esperava ver ali o preço de outro produto, provavelmente quer usar **Both, change frequency and replace subscription product**.
A quantidade usada vem de **Override subscription quantity**, que aparece apenas nos tipos de substituição. Em um upgrade somente de frequência, ela é sempre 1.
## Momento do upgrade
Por padrão, um upgrade entra em vigor a partir do **próximo ciclo de cobrança** do cliente, mantendo a data de renovação existente.
Se a opção de momento estiver habilitada para a sua loja, uma caixa de seleção aparece abaixo dos campos de frequência:
> **My fulfillment provider ships the upgraded item on the current order**
Marcá-la inicia o novo intervalo de cobrança imediatamente, em vez de na próxima renovação, e desbloqueia o campo **One-time upgrade price** na Etapa 4.
A Aftersell não altera o pedido que o cliente acabou de fazer. Esta configuração apenas move o intervalo de cobrança. Marque-a somente se o seu provedor de fulfillment estiver configurado para reconhecer o produto placeholder do upgrade e enviar o item com upgrade no pedido atual.
Esta caixa de seleção fica desmarcada por padrão e não está disponível em todas as lojas. Ela aparece apenas nos tipos de upgrade **Change delivery or billing frequency** e **Both, change frequency and replace subscription product**, e somente depois que a opção for habilitada para a sua loja. Entre em contato com o suporte pelo chat no app se precisar dela.
## Desconto recorrente
Um incentivo opcional aplicado a **todas as renovações futuras** da assinatura com upgrade (não apenas ao primeiro ciclo). Não está disponível para o tipo de adicionar item. A forma como o campo aparece depende de o selling plan selecionado ter ou não políticas de preço escalonadas:
* **Quando um selling plan com níveis de desconto é selecionado** (por exemplo, um plano do Loop que aplica \$20 de desconto na primeira cobrança e \$10 de desconto a partir da segunda cobrança), o campo de entrada livre é substituído por uma lista de botões de opção, um por nível. Cada opção mostra o valor do desconto e o intervalo de cobranças ao qual se aplica (por exemplo, "Charge 1" ou "Charge 2 onward"). Selecione o nível a ser aplicado a todas as renovações futuras.
* **Quando nenhum selling plan é selecionado, ou o plano selecionado não tem níveis de desconto**, o campo padrão de entrada livre aparece. Insira o valor e escolha **Percentage** ou **Fixed amount**.
## Preço único de upgrade, por tipo de upgrade
O **One-time upgrade price** é o que o cliente paga neste pedido da Shopify ao aceitar.
* Nos tipos **Change delivery or billing frequency** e **Both**, ele fica bloqueado em `0` por padrão, porque o seu provedor de assinaturas cobra no final do ciclo de cobrança atual e o produto placeholder aparece no pedido da Shopify por \$0.00. Ele só se torna editável quando a [caixa de seleção de momento do upgrade](#upgrade-timing) na Etapa 3 está marcada.
* Em **Replace with a different subscription product** e **Add another subscribable item to subscription**, a caixa de seleção de momento não se aplica, então o campo de preço é sempre editável.
O que colocar nele depende do tipo de upgrade:
* **Frequência, substituição ou ambos:** a *diferença* de preço entre a assinatura original e a assinatura com upgrade. O cliente mantém a assinatura e essa cobrança cobre a diferença.
* **Adicionar outro item assinável:** a cobrança pelo item adicionado neste pedido. Nada está sendo trocado, então não há diferença a calcular: é simplesmente o que o cliente paga agora pelo novo item, que depois se repete com a assinatura. Veja [Adicionando um item a uma assinatura existente](/pt/aftersell/subscription-upgrades-add-item).
**Desconto no primeiro pedido.** Um desconto opcional aplicado apenas a esta compra de upgrade, inserido como porcentagem (`%`) ou valor fixo. Ele fica ao lado de **One-time upgrade price** e aparece sempre que esse campo é editável, tanto na aba **Create new** quanto na aba **Pick existing**. No tipo de adicionar item, o campo ainda aparece, mas é sempre salvo como `0`; ofertas de adicionar item nunca têm desconto, então defina o preço desejado diretamente no produto da oferta.
## Por que o produto da oferta é um placeholder
O produto da oferta é **apenas um placeholder visual**, e não um produto real que o cliente compra. A Shopify não permite que um produto de assinatura seja exibido como upsell pós-compra após um pedido que já contém uma assinatura, então a Aftersell captura o preço entre upgrades com um SKU placeholder que não é de assinatura.
* A imagem, o título e o preço que você define aparecem no card da oferta.
* Ao aceitar, o preço exibido é cobrado no pedido da Shopify e o Recharge, Skio ou Loop aplica o upgrade real à assinatura no próximo ciclo.
* Se você usar **Pick existing** em vez de criar um, o produto precisa suportar compra única; produtos somente de assinatura são filtrados do seletor.