Evento price.created

Evento `price.created`

Disparado quando um preço é criado via POST /v1/prices ou inline em POST /v1/products. Use este evento para sincronizar os termos de cobrança de um produto. Um price fixa valor, moeda e forma de cobrança; quando precisar mudar valor ou cadência, crie outro preço e desative o antigo. data.object carrega o price completo no mesmo formato de GET /v1/prices/:id.

O preço é a referência que checkouts e assinaturas usam para cobrar. Guarde o price_* recebido neste evento e preserve preços antigos para conciliar cobranças que já usaram aqueles termos.

Quando acontece

Situação	Como aparece no payload
Preço criado diretamente	`data.object.product` aponta para o produto dono.
Preço criado inline junto com produto	O evento é o mesmo: `data.object` contém o `price` completo.
Preço de compra única	`type: "one_time"` e `recurring: null`.
Preço recorrente	`type: "recurring"` e `recurring` contém intervalo, contagem e trial padrão.
Preço criado com metadata	`metadata` ecoa o objeto enviado na criação.

Como processar

Registre o id do evento (evt_*) para processar o webhook de forma idempotente.
Use data.object.id (price_*) como chave do preço no seu sistema.
Relacione o preço ao produto usando data.object.product.
Trate unit_amount, currency, type e recurring como os termos fixos daquele preço.
Use type e recurring para diferenciar compra única de cobrança recorrente.
Use is_active para decidir se o preço pode ser oferecido em novos fluxos.
Use metadata para correlacionar o preço com referências internas.

Campos importantes

Campo	O que observar
`data.object.id`	ID do preço criado.
`product`	Produto ao qual o preço pertence.
`unit_amount` / `currency`	Valor em centavos e moeda do preço.
`type`	`one_time` para compra única ou `recurring` para cobrança recorrente.
`recurring`	Configuração de recorrência; vem `null` em preços `one_time`.
`is_active`	Define se o preço pode ser usado em novos checkouts e assinaturas.
`tax_behavior`	Como o imposto se relaciona ao valor.
`metadata`	Ecoa os metadados enviados na criação.

Variações de catálogo

Variação	O que muda
Preço avulso	Use `type: "one_time"` e `recurring: null` para compras únicas.
Preço recorrente	Use `type: "recurring"` e leia `recurring.interval` e `recurring.interval_count` para a cadência.
Novo valor para produto existente	Um novo `price.created` representa o novo valor; o preço anterior continua existindo para histórico.
Preço inline em produto	Quando enviado em `POST /v1/products`, o preço aparece em `product.created` e também pode chegar como `price.created`.

Exemplo de payload

{
  "id": "evt_AXys7Kx5jcBh9Bnm",
  "object": "event",
  "created_at": "2026-05-16T14:09:27Z",
  "data": {
    "object": {
      "id": "price_MYTCmgGbZ1G2QQ4a",
      "object": "price",
      "created_at": "2026-05-16T14:09:27Z",
      "currency": "brl",
      "is_active": true,
      "livemode": true,
      "metadata": {},
      "name": "Mensal",
      "product": "prod_axBWNRDsaB8n2PCM",
      "recurring": {
        "interval": "month",
        "interval_count": 1,
        "trial_period_days": null,
        "usage_type": "licensed"
      },
      "tax_behavior": "unspecified",
      "type": "recurring",
      "unit_amount": 9990,
      "updated_at": null
    }
  },
  "livemode": true,
  "organization": "org_LaYVFjr378XA2P72",
  "request": {
    "id": null
  },
  "type": "price.created"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Evento price.created