Evento subscription.canceled - Chargefy

Evento `subscription.canceled`

Disparado quando uma subscription passa para canceled, seja por cancelamento imediato ou por um cancelamento agendado que chegou ao fim do período. Use este evento para encerrar acesso recorrente, registrar o motivo de churn e parar qualquer automação interna ligada à assinatura.

canceled é estado terminal. Uma assinatura cancelada não renova, não agenda novos ciclos e não volta para active; para reativar o cliente, crie uma nova assinatura.

Quando acontece

Situação	Como aparece no payload
Cancelamento imediato	`status: "canceled"`, `ended_at` e `canceled_at` preenchidos.
Cancelamento no fim do período executado	`cancel_at_period_end: false` depois da transição final e `ended_at` preenchido.
Cancelamento por política de lifecycle	`cancellation_details.reason` identifica o motivo público normalizado.
Cancelamento solicitado pelo cliente ou pela plataforma	`cancellation_details.comment` e `feedback` podem trazer contexto adicional.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use data.object.id (sub_*) para marcar a assinatura como encerrada no seu sistema.
Remova ou degrade acesso recorrente quando status for canceled.
Salve ended_at, canceled_at e cancellation_details para auditoria e métricas de churn.
Não tente cobrar novos ciclos dessa assinatura após receber este evento.

Campos importantes

Campo	O que observar
`data.object.status`	Sempre vem como `canceled` neste evento.
`ended_at`	Momento em que a assinatura chegou ao estado final.
`canceled_at`	Momento em que o cancelamento foi solicitado ou concluído.
`cancellation_details`	Motivo, feedback e comentário do cancelamento.
`cancel_at_period_end` / `cancel_at`	Indicam se havia cancelamento agendado antes da conclusão.
`customer`	Cliente afetado pelo encerramento.
`metadata`	Dados livres para conciliação com contrato ou conta no seu sistema.

Exemplo de payload

{
  "id": "evt_N6RfBhQSJuaMqu1D",
  "object": "event",
  "created_at": "2026-05-20T12:00:00Z",
  "data": {
    "object": {
      "id": "sub_Asay71QMrNmtJqAQ",
      "object": "subscription",
      "billing_cycle_anchor": "2026-05-19T18:00:00Z",
      "cancel_at": null,
      "cancel_at_period_end": false,
      "canceled_at": "2026-05-20T12:00:00Z",
      "cancellation_details": {
        "comment": "Cliente solicitou cancelamento imediato pelo portal.",
        "feedback": "too_expensive",
        "reason": "cancellation_requested"
      },
      "collection_method": "charge_automatically",
      "created_at": "2026-05-19T18:00:00Z",
      "currency": "brl",
      "current_period_end": "2026-06-19T18:00:00Z",
      "current_period_start": "2026-05-19T18:00:00Z",
      "customer": "cus_HXUQFZeK6ye19uEL",
      "days_until_due": null,
      "default_payment_method": "pm_393spp9qpB9qGBQt",
      "discount": "disc_nZUHwr6Xdq5iZCM9",
      "ended_at": "2026-05-20T12:00:00Z",
      "items": {
        "object": "list",
        "data": [
          {
            "id": "si_7dCGPzeCX9oEDbp5",
            "object": "subscription_item",
            "aggregate_usage": "sum",
            "amount_discount": 0,
            "amount_subtotal": 9900,
            "amount_tax": 0,
            "amount_total": 9900,
            "created_at": "2026-05-19T18:00:00Z",
            "currency": "brl",
            "discount": "disc_nZUHwr6Xdq5iZCM9",
            "metadata": {},
            "position": 0,
            "price": "price_2HaHRy6soCkc6AAV",
            "price_data": null,
            "product": "prod_4zFKNsNRTc9h62K1",
            "quantity": 1,
            "recurring": {
              "interval": "month",
              "interval_count": 1
            },
            "subscription": "sub_Asay71QMrNmtJqAQ",
            "unit_amount": 9900,
            "updated_at": "2026-05-20T12:00:00Z",
            "usage_period_end": "2026-06-19T18:00:00Z",
            "usage_period_start": "2026-05-19T18:00:00Z",
            "usage_type": "metered"
          }
        ],
        "has_more": false,
        "url": "/v1/subscription-items?subscription=sub_Asay71QMrNmtJqAQ"
      },
      "latest_invoice": "inv_VHsTCzQJYq4A3E75",
      "livemode": true,
      "metadata": {},
      "next_billing_at": null,
      "pause_collection": null,
      "payment_settings": {},
      "pending_setup_intent": null,
      "pending_update": null,
      "resumed_at": null,
      "schedule": "subsched_gsuV9LpePBHdjNNu",
      "schedule_phase_index": 0,
      "start_date": "2026-05-19T18:00:00Z",
      "status": "canceled",
      "trial_end": null,
      "trial_settings": {
        "end_behavior": {
          "missing_payment_method": "create_invoice"
        }
      },
      "trial_start": null,
      "updated_at": "2026-05-20T12:00:00Z"
    }
  },
  "livemode": true,
  "organization": "org_733SRiLQNonoGmMB",
  "request": {
    "id": null
  },
  "type": "subscription.canceled"
}