Skip to main content
GET
Esta rota traz a ficha completa de uma assinatura: status atual, período vigente, dados do plano e do cliente, metadata e o histórico de todas as tentativas de cobrança, ciclo a ciclo. É a fonte para conferir o estado real depois de receber um webhook, montar a tela “Minha assinatura” e responder ao atendimento quando o cliente pergunta o que foi cobrado.

Quando usar

Antes de chamar

  • Tenha uma chave secreta gerada por usuário com a permissão visualizar assinaturas. Nos perfis padrão, são Owner, Manager, Operador e Visualizador. Os perfis Desenvolvedor e Financeiro recebem 403 (veja Permissões por perfil).
  • Tenha o id da assinatura, devolvido na criação, na listagem ou no campo data.id dos webhooks de assinatura.
Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em Assinaturas: visão geral.

Parâmetros de caminho

string
required
Identificador único da assinatura. Ex.: 2RhQg9M7ZCg3X3nMb9W1kX8Q.

Respostas

string
Identificador único da assinatura.
string
Status da assinatura:
string | null
Início do período de cobrança atual (formato date-time).
string | null
Fim do período de cobrança atual (formato date-time).
string | null
Data do cancelamento (formato date-time). null se não foi cancelada.
string | null
Tipo de cancelamento: regret (até 7 dias da criação) ou regular (depois de 7 dias). null se não foi cancelada.
boolean
true quando havia cobranças pagas e todas foram estornadas (cancelamento por arrependimento). false no cancelamento regular, no arrependimento sem cobrança paga (ex.: trial grátis) ou quando um estorno não foi concluído.
string
Data de criação (formato date-time).
string
Data da última atualização (formato date-time).
object
Dados do plano assinado.
object
Dados do cliente.
object
Dados do merchant dono da assinatura.
object[]
Histórico de tentativas de cobrança da assinatura. Há uma linha por tentativa: as retentativas recusadas de um ciclo repetem o mesmo billingCycle. A lista vem ordenada por billingCycle decrescente (o ciclo mais recente primeiro).
object | null
Informações suas guardadas na assinatura. Ex.: {"referralCode": "PROMO2024"}.

Onde obter o id da cobrança

charges[].id não serve em GET /v1/charges/{id}. O id da cobrança (o mesmo dos webhooks charge.*) aparece hoje em: A listagem de cobranças do plano exige a mesma permissão desta rota (visualizar assinaturas).
Para o negócio: o plan.price mostra o preço do plano e o charges[].amount mostra o que de fato foi cobrado em cada ciclo. Como editar um plano não muda assinaturas existentes, use o histórico de charges para responder ao cliente quanto ele paga. O failureReason é um texto descritivo, útil para o atendimento explicar uma recusa.

Erros comuns

Veja também

Ciclo de vida

Status, renovação, retentativas e cancelamento.

Visão geral de assinaturas

Fluxo completo, do cliente à cobrança recorrente.

Planos

Recorrência, trial e status do plano.

Webhooks de assinatura

Eventos e correlação com os webhooks de cobrança.

Registrar cartão

Guarde o cartão no cofre antes de criar a assinatura.

Cancelar assinatura

Cancelamento com ou sem estorno.