Status de assinatura
Toda assinatura passa por um conjunto definido de status ao longo da sua vida:Planos
Um plano é o modelo que define quanto você cobra e com que frequência. Crie um plano uma vez e anexe a ele quantas assinaturas precisar.id de plano que você passa ao inscrever um cliente.
Criar uma assinatura
Inscrever um cliente é uma Cardholder Initiated Transaction (CIT), e uma CIT pode exigir 3D Secure. Passe o cartão de uma de duas formas:card.nonceData/card.cardData— o Therius executa a CIT + a primeira cobrança aqui. Simples, mas essa CIT não pode fazer um desafio de 3D Secure, então um cartão que exige 3DS falha.card.tokenData— um cartão que já concluiu a sua CIT (com 3DS) via/payment/authorizationou/payment/purchase. O Therius registra o mandato e, para o ciclo 1, cobra um MIT ou — se você passarfirstPaymentId(o id do pagamento dessa CIT) — vincula o pagamento que você já fez. Este é o caminho confiável para cartões com 3DS. Veja a referência do endpoint.
id da assinatura, o seu status inicial (trialing se o plano tiver teste, caso contrário pending até o primeiro pagamento ser compensado), as datas de início e fim do período atual, e o objeto da primeira fatura.
Seja como for que você forneça o cartão — nonce do SDK,
cardData bruto, ou um token vt_... — as regras das bandeiras de cartão exigem que o cliente esteja ativamente presente e consentindo quando o cartão dele é salvo pela primeira vez para cobranças recorrentes. Se você usar um nonce do SDK, ele precisa ser novo; você não pode reutilizar um nonce de uma sessão anterior.Gestão do ciclo de vida
Depois que uma assinatura está ativa, use os endpoints a seguir para gerenciá-la. Todos os endpoints aceitamPOST e exigem a sua chave de API.
Pausar
POST /subscription/{id}/pauseSuspende as renovações imediatamente. Nenhuma cobrança é tentada enquanto a assinatura está pausada. A data de faturamento é recalculada quando você retoma.Retomar
POST /subscription/{id}/resumeRestaura uma assinatura pausada (recalcula a próxima data de faturamento) ou cobra novamente de imediato uma assinatura suspensa para trazê-la de volta a ativa.Cancelar
POST /subscription/{id}/cancelCancela a assinatura de forma permanente. O Therius dispara o evento de webhook subscription.cancelled. Assinaturas canceladas não podem ser reativadas.Mudar de plano
POST /subscription/{id}/change-planMigra o assinante para um plano diferente. Passe "applyAt": "now" para uma troca imediata proporcional, ou "applyAt": "next_billing" para mudar no fim do período atual.Atualizar método de pagamento
POST /subscription/{id}/payment-methodSubstitui o cartão armazenado e o seu mandato. Mudar o cartão é uma CIT e pode precisar de 3D Secure — ou registre um cartão que você já fez a CIT em outro lugar (card.tokenData, sem cobrança, sem 3DS aqui), ou execute uma CIT de valor zero aqui (card.nonceData / card.cardData). Somente o caminho em modo CIT pode reativar uma assinatura suspended. Veja a referência do endpoint.Repetir pagamento
POST /subscription/{id}/retry-paymentEnfileira uma tentativa de gestão de cobranças imediata para uma assinatura past_due sem esperar a próxima nova tentativa programada.Mover o dia de faturamento
POST /subscription/{id}/update-billing-dayDefine o dia do mês em que as renovações são cobradas. Aceita valores de 1 a 28.Faturamento por uso e híbrido
Além doamount fixo de um plano, você pode cobrar pelo consumo medido — um híbrido de tarifa base fixa e tarifa variável por uso. São três peças:
1. Medidores. Um medidor é um contador nomeado, próprio da sua conta de lojista, ex.: api_requests ou data_stored_gb. Cada medidor tem um modo de agregação que decide como os eventos de um período se combinam em uma única quantidade faturável:
2. Precificação por plano. Cada medidor é precificado em um plano com um esquema:
per_unit— um preço fixo por unidade.volume— todas as unidades são precificadas pela taxa da única faixa em que a quantidade total cai.graduated— cada faixa precifica apenas as unidades que caem dentro do seu próprio intervalo.
includedUnits é subtraída antes de precificar cada período.
Os medidores e a precificação por plano são gerenciados no Dashboard, em Assinaturas → Medidores de uso. Não há API para configurar medidores ou preços.
POST /subscription/usage para cada evento de uso:
Idempotency-Key se o seu job de reporte puder repetir — um (meterCode, Idempotency-Key) duplicado devolve o evento original. Um occurredAt opcional define para qual período de faturamento o evento conta (o padrão é agora).
A cada renovação o Therius agrega os eventos do período, aplica a precificação e soma o resultado à fatura. Uma fatura híbrida carrega um array lines — uma linha para a tarifa base mais uma por complemento medido — e o amount da fatura é a soma delas. Consulte Ver faturas.
Gestão de cobranças
Quando uma renovação programada falha — por exemplo, por fundos insuficientes ou um cartão expirado — o Therius move automaticamente a assinatura parapast_due e começa a sequência de gestão de cobranças. As novas tentativas são espaçadas conforme os limites de nova tentativa das bandeiras de cartão e a configuração do seu comércio.
Assim que todas as novas tentativas se esgotam, a assinatura passa para suspended e o Therius dispara um webhook subscription.suspended. Veja o catálogo de eventos de webhook para cada evento de assinatura que você pode assinar. Para reativar uma assinatura suspensa, o cliente precisa fornecer um novo método de pagamento:
active.
Esse caminho de reativação executa a sua própria CIT e não pode concluir um desafio de 3D Secure. Se
o novo cartão exigir 3DS, execute você mesmo uma CIT + cobrança de recuperação com capacidade 3DS via
/payment/purchase, e depois registre o token resultante com card.tokenData — veja a
referência de Atualizar cartão arquivado.Assinaturas pai / filho
Você pode vincular assinaturas entre si passandoparentSubscriptionId ao criar uma filha. Isso é útil para complementos, expansões de assentos, ou qualquer modelo de faturamento onde vários itens de linha devam compartilhar um ciclo de vida.
propagateLifecycle: true para propagar em cascata as mudanças de status — pausar, retomar e cancelar — da assinatura pai para todas as suas filhas automaticamente. Quando propagateLifecycle é false (o padrão), cada assinatura gerencia o seu ciclo de vida de forma independente.