Evento subscription.created

Evento `subscription.created`

Disparado quando uma assinatura é criada e passa a existir como recurso público. Use este evento para registrar a assinatura no seu sistema e aplicar o controle de acesso a partir do status atual. data.object carrega o objeto subscription completo no estado atual, no mesmo shape de GET /v1/subscriptions/:id.

Uma assinatura criada sem trial pode chegar active quando a primeira invoice foi paga no próprio create, ou incomplete quando a cobrança ficou para recuperação. Se um create com error_if_incomplete falhar, não há subscription.created, porque a assinatura não passou a existir como recurso público.

Quando acontece

Situação	Como aparece no payload
Assinatura criada com cobrança inicial paga	`status: "active"` e `latest_invoice` aponta para a invoice inicial já paga.
Assinatura criada aguardando primeira cobrança	`status: "incomplete"` e `latest_invoice` aponta para a invoice aberta.
Assinatura criada com trial	`status: "trialing"`, `trial_start` e `trial_end` preenchidos.
Assinatura criada por schedule	`schedule` e `schedule_phase_index` identificam o cronograma aplicado.
Assinatura vendida com prazo	`cancel_at` já vem preenchido com a data de término. O prazo é aplicado antes deste evento, então não há um `subscription.updated` logo depois corrigindo a intenção declarada na venda.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Salve data.object.id (sub_*) como a assinatura canônica do cliente.
Use customer, items.data[], current_period_start e current_period_end para montar o acesso inicial.
Verifique status antes de liberar acesso pago: active e trialing costumam liberar; incomplete pede aguardar pagamento.
Use metadata para correlacionar a assinatura com contrato, conta ou workspace no seu sistema.

Campos importantes

Campo	O que observar
`data.object.status`	Estado inicial da assinatura: `active`, `trialing`, `incomplete`, etc.
`customer`	Cliente dono da assinatura.
`items.data[]`	Planos, preços e quantidades recorrentes que serão cobrados por ciclo.
`latest_invoice`	Invoice criada junto da assinatura, quando houver.
`default_payment_method`	Método que será usado para cobranças automáticas.
`trial_start` / `trial_end`	Janela de trial quando a assinatura começa sem cobrança imediata.
`next_billing_at`	Próxima data prevista de cobrança ou renovação.
`metadata`	Dados livres para conciliação com seu sistema.

Exemplo de payload

{
  "id": "evt_FJEY6L8cfbNA6Zz9",
  "object": "event",
  "created_at": "2026-05-19T18:00:00Z",
  "data": {
    "object": {
      "id": "sub_dbuAE4pr9LUHeq3T",
      "object": "subscription",
      "billing_cycle_anchor": "2026-05-19T18:00:00Z",
      "cancel_at": null,
      "cancel_at_period_end": false,
      "canceled_at": null,
      "cancellation_details": {
        "comment": null,
        "feedback": null,
        "reason": null
      },
      "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_aiu9HNZGeV6MHArN",
      "days_until_due": null,
      "default_payment_method": "pm_ySTobDifUmX35LTc",
      "discount": "disc_Rs7pFkgMoBDtQsf8",
      "ended_at": null,
      "items": {
        "object": "list",
        "data": [
          {
            "id": "si_4U5ULTY2FUKXu7MW",
            "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_Rs7pFkgMoBDtQsf8",
            "metadata": {},
            "position": 0,
            "price": "price_f4Myw27xETvvpnsa",
            "price_data": null,
            "product": "prod_fdko3VmrLH2L52uB",
            "quantity": 1,
            "recurring": {
              "interval": "month",
              "interval_count": 1
            },
            "subscription": "sub_dbuAE4pr9LUHeq3T",
            "unit_amount": 9900,
            "updated_at": "2026-05-19T18: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_dbuAE4pr9LUHeq3T"
      },
      "latest_invoice": "inv_2CJrHsSfU1EDxU4c",
      "livemode": true,
      "metadata": {},
      "next_billing_at": "2026-06-19T18:00:00Z",
      "pause_collection": null,
      "payment_settings": {},
      "pending_setup_intent": null,
      "pending_update": null,
      "resumed_at": null,
      "schedule": "subsched_UPA92syyKBs6eK7J",
      "schedule_phase_index": 0,
      "start_date": "2026-05-19T18:00:00Z",
      "status": "active",
      "trial_end": "2026-05-19T18:00:00Z",
      "trial_settings": {
        "end_behavior": {
          "missing_payment_method": "create_invoice"
        }
      },
      "trial_start": "2026-05-05T18:00:00Z",
      "updated_at": "2026-05-19T18:00:00Z"
    }
  },
  "livemode": true,
  "organization": "org_nDctXZyCDWa3tVK2",
  "request": {
    "id": "req_XUXhEvBWMkyyY2d3"
  },
  "type": "subscription.created"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento subscription.created