Skip to main content
Este evento é publicado quando uma assinatura transiciona para o status PAST_DUE porque uma ou mais tentativas de pagamento falharam. Este é um evento crítico do ciclo de vida de faturamento que tipicamente dispara ações downstream como envio de notificações de lembrete de pagamento, restrição de acesso a funcionalidades ou início de um fluxo de cobrança (dunning). O campo pastDueReason indica o que especificamente falhou — pode ser o pagamento da assinatura do plano (PLAN), o pagamento da taxa baseada em uso (FEE), ou ambos (PLAN_FEE). Essa distinção ajuda consumidores downstream a aplicar a estratégia de recuperação apropriada.
Uma assinatura pode se tornar inadimplente por três razões distintas: PLAN (a fatura fixa do plano falhou), FEE (a fatura de taxa baseada em uso falhou), ou PLAN_FEE (ambas falharam). Cada razão pode requerer uma abordagem diferente de notificação e recuperação.
Ao tratar este evento, considere implementar um período de carência antes de restringir o acesso ao serviço. Use o timestamp pastDueAt para calcular há quanto tempo a assinatura está inadimplente e aplique medidas graduais — por exemplo, avisos suaves primeiro, depois restrições de funcionalidades, depois suspensão total.

​
Detalhes do Evento

PropriedadeValor
Typesubscription.past_due

​
Schema do Payload

​
subscriptionId
string (UUID v7)
required
Identificador da assinatura.
​
organizationId
string (UUID v7)
required
FK para Organization.
​
planId
string (UUID v7)
required
FK para Plan.
​
planIntervalId
string (UUID v7)
required
FK para PlanInterval.
​
externalPlanRef
string
Referência externa da assinatura (plano).
​
externalFeeRef
string
Referência externa da assinatura (taxas).
​
currency
string
required
Moeda da assinatura (USD, BRL, EUR).
​
status
string
required
Status da assinatura.
​
pastDueReason
string
required
Motivo da inadimplência: PLAN, FEE ou PLAN_FEE.
​
pastDueAt
string (ISO 8601)
required
Quando a assinatura se tornou inadimplente.
​
pausedBy
string (UUID)
Quem pausou a assinatura.
​
pausedAt
string (ISO 8601)
Quando a assinatura foi pausada.
​
cancelledBy
string (UUID)
Quem cancelou a assinatura.
​
cancelledAt
string (ISO 8601)
Quando a assinatura foi cancelada.
​
createdBy
string (UUID)
required
Usuário que criou a assinatura.
​
createdAt
string (ISO 8601)
required
Timestamp de criação.
​
updatedBy
string (UUID)
required
Usuário que atualizou a assinatura por último.
​
updatedAt
string (ISO 8601)
required
Timestamp da última atualização.
{
  "specversion": "1.0",
  "type": "subscription.past_due",
  "id": "evt_0195f3a2-8c00-7d4e-b802-2b3c4d5e6f7a",
  "time": "2026-03-25T14:00:00Z",
  "datacontenttype": "application/json",
  "data": {
    "subscriptionId": "0195f3a2-8c00-7d4e-b802-2b3c4d5e6f7a",
    "organizationId": "0195f3a2-8c00-7d4e-b801-1a2b3c4d5e6f",
    "planId": "0195f3a2-1234-7567-89ab-cdef01234567",
    "planIntervalId": "0195f3a2-abcd-7ef0-1234-56789abcdef0",
    "externalPlanRef": "sub_abc123",
    "externalFeeRef": "sub_def456",
    "currency": "BRL",
    "status": "PAST_DUE",
    "pastDueReason": "PLAN",
    "pastDueAt": "2026-03-25T14:00:00Z",
    "pausedBy": null,
    "pausedAt": null,
    "cancelledBy": null,
    "cancelledAt": null,
    "createdBy": "0195f3a2-8c00-7d4e-b806-6f7a8b9c0d1e",
    "createdAt": "2026-01-15T10:00:00Z",
    "updatedBy": "0195f3a2-8c00-7d4e-b806-6f7a8b9c0d1e",
    "updatedAt": "2026-03-25T14:00:00Z"
  }
}