> ## 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 período grátis

> Quando cada evento de período grátis é enviado, o que chega quando o período grátis termina e o formato do payload.

Os gatilhos `subscription_trial_started` e `subscription_trial_canceled` avisam o que aconteceu com uma assinatura durante o período grátis. Esta página explica quem recebe esses eventos, quando cada um é enviado e o que chega quando o período grátis termina.

### Quem recebe

Os eventos de período grátis são só do produtor:

* Valem para webhooks de todos os produtos (`all`) ou de um produto da conta.
* Com `all_affiliations` ou `all_coproductions`, a criação e a edição do webhook respondem 400 (`TRIAL_EVENT_PRODUCER_ONLY`).
* Afiliados e coprodutores não recebem nada durante o período grátis. Eles recebem a primeira cobrança (`compra_aprovada`, com comissão) e depois `subscription_renewed`.

### Não existe pedido no período grátis

O período grátis não gera pedido. O primeiro pedido da assinatura é a primeira cobrança, feita quando o período grátis termina. Por isso, nos eventos de período grátis:

* `order_id` e `order_ref` são `null`.
* `approved_date` é `null`, e `Commissions` é `null`.
* `subscription_id`, na raiz do JSON, identifica a assinatura. É o mesmo valor que chega depois em todas as cobranças.
* `Subscription.trial_start` e `Subscription.trial_end` trazem o início e o fim do período grátis.
* `order_status` é `trial` em `subscription_trial_started` e `canceled` em `subscription_trial_canceled`.

Use o `subscription_id` para ligar o período grátis à primeira cobrança e às renovações.

### Quando cada evento é enviado

| Evento | Quando é enviado | `order_status` | `Subscription.status` |
| - | - | - | - |
| `subscription_trial_started` | O período grátis começou. | `trial` | `trial` |
| `subscription_trial_canceled` | O período grátis foi cancelado antes da primeira cobrança. | `canceled` | `canceled` |

* **Cartão de crédito:** `subscription_trial_started` é enviado quando a verificação do cartão é aprovada e a assinatura em período grátis é criada. Se a verificação for recusada, o período grátis não começa e nenhum evento é enviado.
* **Pix Automático:** `subscription_trial_started` é enviado quando o banco do cliente autoriza o débito automático. Mostrar o QR Code não envia nenhum evento.
* `subscription_trial_canceled` é enviado quando o cliente, o produtor ou a Kiwify cancela a assinatura durante o período grátis. No Pix Automático, o cliente também pode cancelar a autorização no app do banco.
* Os dois eventos são enviados uma vez por assinatura. Mesmo assim, trate cada evento como idempotente, usando a combinação `subscription_id` + `webhook_event_type`: nos eventos de período grátis, `order_id` é `null`.

### O que é enviado quando o período grátis termina

Quando o período grátis termina, a Kiwify faz a primeira cobrança. Ela gera o primeiro pedido da assinatura, com um `order_id` novo, e é anunciada como uma renovação. Cada webhook só chega se o gatilho estiver ativo no seu webhook.

| Resultado da primeira 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_trial_started` e `subscription_trial_canceled` não são enviados de novo depois da primeira cobrança.
* Uma primeira cobrança recusada segue as regras de uma renovação recusada. Quando o limite de tentativas acaba, a assinatura é cancelada e chega `subscription_canceled`, não `subscription_trial_canceled`. Veja [Eventos de assinatura](https://docs.kiwify.com.br/api-reference/webhooks/subscription-events.md).

### Cancelamento

Quando o período grátis é cancelado, o cliente perde o acesso e nenhuma cobrança é feita:

* `Subscription.customer_access.has_access` é `false`, e `access_until` é a data do cancelamento.
* `Subscription.next_payment` é `null`, e `charges.future` vem vazio.
* `Subscription.canceled_at` traz a data do cancelamento e `Subscription.canceled_by` traz a origem:

| `canceled_by` | Quem cancelou |
| - | - |
| `customer` | O cliente. |
| `producer` | O produtor. |
| `superAdmin` | A Kiwify. |
| `customer_bank_app` | O cliente, no app do banco (Pix Automático). |

### Campos do objeto `Subscription`

O objeto `Subscription` tem os mesmos campos dos [eventos de assinatura](https://docs.kiwify.com.br/api-reference/webhooks/subscription-events.md), com estas diferenças:

| Campo | Descrição |
| - | - |
| `status` | `trial` em `subscription_trial_started`, `canceled` em `subscription_trial_canceled`. |
| `start_date` | Início do período grátis. |
| `next_payment` | Fim do período grátis e data da primeira cobrança (UTC). `null` depois do cancelamento. |
| `customer_access.access_until` | Fim do período grátis. No cancelamento, a data do cancelamento. |
| `charges.completed` | Sempre vazio: o período grátis não tem cobrança paga. |
| `charges.future` | Próximas datas de cobrança previstas. A primeira é a data da primeira cobrança. Vazio no cancelamento. |
| `trial_start` | Início do período grátis (UTC). |
| `trial_end` | Fim do período grátis (UTC). |
| `canceled_at` | Data do cancelamento (UTC). Só em `subscription_trial_canceled`. |
| `canceled_by` | Origem do cancelamento. Só em `subscription_trial_canceled`. |

Na raiz do JSON, `created_at` é o início do período grátis. Em `subscription_trial_canceled`, `updated_at` é a data do cancelamento. Essas datas 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`, `Product` e `TrackingParameters` foram omitidos). Para ver o payload completo de um evento, confira em **Ver logs** o que foi enviado.

```json Período grátis iniciado (subscription_trial_started) theme={null}
{
  "order_id": null,
  "order_ref": null,
  "order_status": "trial",
  "webhook_event_type": "subscription_trial_started",
  "payment_method": "credit_card",
  "created_at": "2026-11-10 09:15",
  "approved_date": null,
  "Commissions": null,
  "subscription_id": "5f6e7d8c-0000-4000-8000-000000000001",
  "Subscription": {
    "id": "5f6e7d8c-0000-4000-8000-000000000001",
    "status": "trial",
    "start_date": "2026-11-10T12:15:00.000Z",
    "next_payment": "2026-11-18T03:00:00.000Z",
    "customer_access": {
      "has_access": true,
      "active_period": true,
      "access_until": "2026-11-18T03:00:00.000Z"
    },
    "plan": { "id": "…", "name": "Mensal", "frequency": "monthly", "qty_charges": 0 },
    "charges": {
      "completed": [],
      "future": [
        { "charge_date": "2026-11-18T03:00:00.000Z" },
        { "charge_date": "2026-12-18T03:00:00.000Z" }
      ]
    },
    "trial_start": "2026-11-10T12:15:00.000Z",
    "trial_end": "2026-11-18T03:00:00.000Z"
  }
}
```

```json Período grátis cancelado (subscription_trial_canceled) theme={null}
{
  "order_id": null,
  "order_ref": null,
  "order_status": "canceled",
  "webhook_event_type": "subscription_trial_canceled",
  "payment_method": "credit_card",
  "created_at": "2026-11-10 09:15",
  "updated_at": "2026-11-12 16:40",
  "approved_date": null,
  "Commissions": null,
  "subscription_id": "5f6e7d8c-0000-4000-8000-000000000001",
  "Subscription": {
    "id": "5f6e7d8c-0000-4000-8000-000000000001",
    "status": "canceled",
    "start_date": "2026-11-10T12:15:00.000Z",
    "next_payment": null,
    "customer_access": {
      "has_access": false,
      "active_period": false,
      "access_until": "2026-11-12T19:40:00.000Z"
    },
    "plan": { "id": "…", "name": "Mensal", "frequency": "monthly", "qty_charges": 0 },
    "charges": { "completed": [], "future": [] },
    "trial_start": "2026-11-10T12:15:00.000Z",
    "trial_end": "2026-11-18T03:00:00.000Z",
    "canceled_at": "2026-11-12T19:40:00.000Z",
    "canceled_by": "customer"
  }
}
```


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