Eventos de assinatura

Os gatilhos subscription_renewed, subscription_late e subscription_canceled avisam o que aconteceu com uma assinatura. Esta página explica quando cada um é enviado e quais campos do payload usar para liberar ou remover o acesso do cliente.

Como ligar uma renovação à compra original

Cada cobrança de uma assinatura (a primeira compra e cada renovação) gera um pedido novo, com um order_id novo. O subscription_id, na raiz do JSON, é o mesmo em todas as cobranças. Use o subscription_id para identificar a assinatura e o order_id para identificar cada cobrança. Os eventos de assinatura sempre trazem o pedido mais recente da assinatura. Numa renovação, esse é o pedido da renovação.

O que é enviado em cada renovação

Na renovação, a Kiwify cobra o cliente e envia dois webhooks para o mesmo pedido: um evento de compra e um evento de assinatura. Cada um só chega se o gatilho estiver ativo no seu webhook.

Resultado da cobrança	Evento de compra	Evento de assinatura	`order_status`	`Subscription.status`
Aprovada	`compra_aprovada`	`subscription_renewed`	`paid`	`active`
Recusada	`compra_recusada`	`subscription_late`	`refused`	`waiting_payment`

subscription_renewed só é enviado quando o pagamento da renovação é aprovado. Para liberar o novo período, ele basta sozinho. Não é preciso consultar outro evento nem a API.
Num pagamento aprovado, Subscription.customer_access.access_until passa a ser o fim do novo período pago.
Cada nova tentativa de cobrança que falhar envia de novo compra_recusada e subscription_late. Quando o limite de tentativas acaba, a assinatura é cancelada e chega subscription_canceled.
Se a cobrança for recusada antes do fim do período atual, só compra_recusada é enviado. O período pago continua válido.
Em renovações por Pix ou boleto, chega primeiro pix_gerado ou boleto_gerado. compra_aprovada e subscription_renewed só chegam quando o cliente paga.

Cancelamento

subscription_canceled é enviado quando o cliente, o produtor ou a Kiwify cancela a assinatura. A partir daí ninguém é cobrado de novo. Mesmo assim, o período já pago continua valendo: customer_access.access_until fica na data de fim desse período, e o cliente deve manter o acesso até lá.

Quando o cancelamento é pedido para o fim do período, subscription_canceled pode chegar duas vezes: uma no pedido do cancelamento e outra quando o período termina. Trate o evento como idempotente.
Se o cancelamento vier de um reembolso, order_status é refunded, customer_access.has_access é false e access_until é a data do reembolso.

Campos do objeto `Subscription`

Campo	Descrição
`id`	Id da assinatura (o mesmo valor de `subscription_id`).
`status`	`active`, `waiting_payment`, `canceled` ou `ended`.
`start_date`	Data de início da assinatura.
`next_payment`	Fim do período atual e data da próxima cobrança (UTC).
`customer_access.has_access`	`true` enquanto o cliente deve ter acesso.
`customer_access.active_period`	`true` enquanto o período atual não terminou.
`customer_access.access_until`	Até quando o cliente tem acesso (UTC).
`plan`	`id`, `name`, `frequency` (`weekly`, `monthly`, `bimonthly`, `quarterly`, `semi-annually`, `annually`) e `qty_charges` (`0` = sem limite).
`charges.completed`	Cobranças pagas da assinatura: `order_id`, `amount`, `status`, `installments`, `card_type`, `card_last_digits`, `card_first_digits`, `created_at`.
`charges.future`	Próximas datas de cobrança previstas (`charge_date`).

Datas como created_at, updated_at e approved_date, na raiz do JSON, vêm no horário de Brasília (YYYY-MM-DD HH:mm). As datas dentro de Subscription vêm em UTC.

Exemplos de payload

Exemplos resumidos (campos como Customer, Commissions e TrackingParameters foram omitidos). Para ver o payload completo de um evento, use Testar Webhook e confira em Ver logs o que foi enviado.

{
  "order_id": "9b1c2d3e-0000-4000-8000-000000000002",
  "order_status": "paid",
  "webhook_event_type": "subscription_renewed",
  "payment_method": "credit_card",
  "approved_date": "2026-10-20 09:15",
  "subscription_id": "5f6e7d8c-0000-4000-8000-000000000001",
  "Subscription": {
    "id": "5f6e7d8c-0000-4000-8000-000000000001",
    "status": "active",
    "start_date": "2025-10-20T12:15:00.000Z",
    "next_payment": "2027-10-20T03:00:00.000Z",
    "customer_access": {
      "has_access": true,
      "active_period": true,
      "access_until": "2027-10-20T03:00:00.000Z"
    },
    "plan": { "id": "…", "name": "Anual", "frequency": "annually", "qty_charges": 0 },
    "charges": {
      "completed": [
        { "order_id": "…0001", "status": "paid", "created_at": "2025-10-20T12:15:00.000Z" },
        { "order_id": "…0002", "status": "paid", "created_at": "2026-10-20T12:15:00.000Z" }
      ],
      "future": [{ "charge_date": "2027-10-20T03:00:00.000Z" }]
    }
  }
}

{
  "order_id": "9b1c2d3e-0000-4000-8000-000000000003",
  "order_status": "refused",
  "webhook_event_type": "subscription_late",
  "payment_method": "credit_card",
  "card_rejection_reason": "insufficient_funds",
  "approved_date": null,
  "subscription_id": "5f6e7d8c-0000-4000-8000-000000000001",
  "Subscription": {
    "id": "5f6e7d8c-0000-4000-8000-000000000001",
    "status": "waiting_payment",
    "next_payment": "2026-10-20T03:00:00.000Z",
    "customer_access": {
      "has_access": false,
      "active_period": false,
      "access_until": "2026-10-20T03:00:00.000Z"
    }
  }
}

{
  "order_id": "9b1c2d3e-0000-4000-8000-000000000002",
  "order_status": "paid",
  "webhook_event_type": "subscription_canceled",
  "subscription_id": "5f6e7d8c-0000-4000-8000-000000000001",
  "Subscription": {
    "id": "5f6e7d8c-0000-4000-8000-000000000001",
    "status": "canceled",
    "next_payment": "2027-10-20T03:00:00.000Z",
    "customer_access": {
      "has_access": true,
      "active_period": true,
      "access_until": "2027-10-20T03:00:00.000Z"
    }
  }
}

Consultar pela API

A API pública não tem um endpoint de assinaturas. GET /sales/{id} devolve o status do pedido, mas não traz subscription_id nem a data de fim do período pago. Esses dados só chegam pelo webhook.

API Reference

Autenticação

Conta

Produtos

Vendas

Parcelado

Financeiro

Afiliados

Webhooks

Eventos

Eventos de assinatura

Como ligar uma renovação à compra original

O que é enviado em cada renovação

Cancelamento

Campos do objeto `Subscription`

Exemplos de payload

Consultar pela API

​Como ligar uma renovação à compra original

​O que é enviado em cada renovação

​Cancelamento

​Campos do objeto Subscription

​Exemplos de payload

​Consultar pela API

Como ligar uma renovação à compra original

O que é enviado em cada renovação

Cancelamento

Campos do objeto `Subscription`

Exemplos de payload

Consultar pela API