> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwify.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Eventos de assinatura

> Quando cada evento de assinatura é enviado, como confirmar que uma renovação foi paga e o formato do payload.

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.

```json Renovação paga (subscription_renewed) theme={null}
{
  "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" }]
    }
  }
}
```

```json Renovação recusada (subscription_late) theme={null}
{
  "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"
    }
  }
}
```

```json Cancelamento (subscription_canceled) theme={null}
{
  "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}`](/api-reference/sales/single) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.