Skip to main content
GET
Esta rota devolve as assinaturas cadastradas, página por página, com um resumo do plano e do cliente de cada uma. Ela atende o painel interno do seu time (quem está ativo, quem cancelou, quem expirou) e a área “Minha assinatura” do cliente, filtrando pelo customerId.

Quando usar

Antes de chamar

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 consulta

string
Filtra pelas assinaturas de um merchant específico.
string
Filtra pelas assinaturas de um cliente. Ex.: 2RhQg9M7ZCg3X3nMb9W1kX8Q.
string
Filtra pelo status da assinatura: pending_activation, active, cancelled ou expired.
Busca por nome ou e-mail do cliente, ou pelo nome do plano. Ex.: joao.
integer
default:"1"
Número da página. A contagem começa em 1.
integer
default:"10"
Quantidade de assinaturas por página.

Respostas

object[]
Assinaturas da página atual.
object
Dados da paginação.
Para o negócio: a listagem mostra o retrato atual da base. Uma assinatura com cobrança de renovação falhando continua active enquanto houver retentativas; ela só vira expired quando o limite de tentativas do ciclo se esgota (veja Ciclo de vida). Para agir antes disso, como avisar o cliente de que o pagamento falhou (a troca de cartão exige cancelar e criar outra assinatura), use o webhook subscription.payment_failed, enviado a cada tentativa que falha.
Para o desenvolvedor: a listagem traz só o resumo de plano e cliente (sem IDs) e não inclui metadata nem o histórico de cobranças. Para esses dados, chame Consultar assinatura com o id.

Erros comuns

Veja também

Visão geral de assinaturas

Fluxo completo, do cliente à cobrança recorrente.

Planos

Recorrência, trial e status do plano.

Ciclo de vida

Status, renovação, retentativas e cancelamento.

Webhooks de assinatura

Eventos enviados a cada etapa da assinatura.

Registrar cartão

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

Consultar assinatura

Detalhes e histórico de cobranças.