Para equipe ilarika
Assinatura: o que é plano, add-on, crédito e fatura
- Super AdminAssinaturasCobrança automática
Como o iLarika cobra uma loja e o que cada estado da assinatura permite. É a base das outras docs: assinar, minha assinatura, atraso e bloqueio, fatura e pagamento e Super Admin › Assinaturas.
Os quatro nomes
- Plano: o pacote de recursos da loja (Starter, Essencial, Pro, Rede). Por dentro, um
produto do tipo
planque aponta para o catálogo de capacidades que a loja recebe. Tem preço mensal e, se quiser, anual. - Add-on: um recurso vendido à parte. Um produto do tipo
addonque liga ou eleva chaves do catálogo enquanto está na assinatura. Hoje nenhum está à venda: a atendente com IA vem no plano (Essencial e Pro), e o único add-on do catálogo é o interno de excedente de IA, que só dá nome à linha da fatura. - Crédito de IA: um pacote de atendimentos comprado à parte, que não vence.
Um produto do tipo
credit_pack; não entra como item da assinatura, é compra avulsa. - Fatura: o documento que a loja paga. Cada fatura tem linhas (plano,
add-on, excedente de IA, ajuste), um número legível por ano (
2026-000123) e um vencimento. Depois de aberta, não muda: corrigiu algo, emite um ajuste ou anula e abre outra.
Os estados da assinatura
| Estado | A loja consegue | O que o painel mostra |
|---|---|---|
Em teste (trialing) |
tudo do plano escolhido | “X dias de teste” |
Ativa (active) |
tudo | nada de especial |
Atrasada (past_due) |
tudo, durante a carência (7 dias por padrão) | faixa vermelha persistente |
Suspensa (suspended) |
só a tela de Assinatura, Conta e Suporte | “sua loja foi pausada; pague para voltar na hora” |
Cancelada (canceled) |
o mesmo que suspensa; volta só pelo Reativar do Super Admin | os dados ficam 90 dias para reativação (Termos do lojista, item 14); apagar é a limpeza manual do Super Admin (Estabelecimentos › Zona de perigo) |
Pagar em qualquer ponto volta a assinatura para ativa na hora. Ninguém volta para “em teste”. Só suspensa e cancelada travam a loja: é o que o cardápio público, o marketplace, o bot e o acesso por IA leem para responder “indisponível”.
O que a assinatura faz na loja
Os recursos que a loja tem são derivados do que está na assinatura: o
plano vira o plano da loja, e cada add-on vira uma exceção automática no
catálogo (marcada addon:<produto>). Trocar de plano é trocar o item e
recalcular; nenhuma tela de recurso muda. As exceções manuais do Super Admin
continuam valendo e ganham das automáticas.
- Subir de plano ou adicionar add-on aplica na hora e cobra o proporcional dos dias que faltam no período (crédito do antigo menos custo do novo).
- Descer de plano ou trocar entre mensal e anual agenda para o fim do período: a fatura desse vencimento já sai no plano novo e, na data, o plano entra. Em teste, qualquer troca vale na hora, sem cobrança.
- Mês comercial: quem assinou dia 31 vence no último dia de cada mês e volta ao 31 quando o mês tem.
De onde vieram as assinaturas
- Toda loja que existia antes da cobrança ganhou uma assinatura cortesia
ativa no plano atual, sem fatura e sem cobrança. A chave
billing.enabledemPlatformSettingnasce desligada. - As faturas antigas de excedente de IA viraram faturas
legacy, com o número gerado e o excedente como linha, sem perder nada. GET /platform/billing/statusmostra se a cobrança está ligada, quantas assinaturas há por estado, a carência e a suspensão em dias e o provedor padrão; é o que o painel Cobrança automática lê.
Ligar a cobrança
O interruptor Cobrança automática ligada fica em Super Admin ›
Assinaturas › Cobrança automática (só superadmin; PUT /platform/billing/cobranca, auditado). O painel mostra também o provedor
padrão, o link para o Asaas e a carência / suspensão em dias. Ligada, a régua
passa a emitir a fatura do ciclo seguinte, avisar, marcar atraso e suspender,
só para assinaturas com preço: as lojas migradas como cortesia continuam
sem fatura até ganharem um plano com preço. O roteiro completo, com a loja de
teste, o Asaas em sandbox e a virada das lojas reais, está em
docs/runbooks/ligar-cobranca-em-producao.md.
O que depende de billing.enabled
Ligada ou desligada, funciona: a vitrine, o checkout (cadastro, código, cobrança da primeira fatura no cartão, Pix à vista no anual ou Pix Automático quando liberado), o webhook do Asaas que libera a loja paga, a compra de pacotes de IA e o “Já paguei”.
Só com ela ligada (é a régua, de hora em hora):
- o teste de 7 dias com cartão: sem a régua ninguém cobraria o cartão no fim do teste, então com ela desligada a vitrine não oferece teste e o cartão é cobrado na contratação;
- a fatura do ciclo seguinte (renovação mensal ou anual) e a cobrança automática no cartão salvo;
- o aviso de 2 dias antes do fim do teste;
- atraso, pausa e cancelamento por falta de pagamento;
- trocas de plano agendadas e cancelamentos agendados;
- o excedente de IA (ele entra na fatura de ciclo).
Com ela desligada, uma loja paga renova sem fatura (fica ativa) e uma loja de Pix (ou Pix Automático) que não pagou fica esperando o primeiro pagamento sem prazo.
Perguntas comuns
Uma loja pode ter duas assinaturas? Não: uma assinatura viva por loja. Rede com várias unidades ganha depois uma conta que agrupa lojas, sem mudar isto.
O Super Admin ainda consegue dar um recurso de graça? Sim, como hoje, pela exceção manual no catálogo. Ela ganha do que a assinatura diz.
Onde ficam os valores? Sempre em centavos, em UTC, nas tabelas
subscriptions, subscription_items, invoices, invoice_lines,
payment_attempts, billing_payments, subscription_events.
