Eventos de período grátis

​

Quem recebe

• 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

• 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.

​

Quando cada evento é enviado

• 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

• 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.

​

Cancelamento

• 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:

​

Campos do objeto Subscription

​

Exemplos de payload

{
  "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"
  }
}

{
  "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"
  }
}