Skip to main content
Um price representa quanto e como um produto é cobrado. Ele sempre pertence a um produto e fixa o valor (unit_amount), a moeda (currency) e a forma de cobrança — uma compra única (one_time) ou uma cobrança recorrente (recurring) com intervalo e frequência definidos. Um mesmo produto pode ter vários preços ao mesmo tempo: mensal, anual, promocional ou em moedas diferentes. É o price que checkouts e assinaturas referenciam na hora de cobrar — ele guarda os termos da cobrança para que o valor seja sempre o mesmo, independentemente de quantas vendas ele origina. Por isso campos como unit_amount, currency, type e recurring são imutáveis: para mudar o valor de um produto, você cria um preço novo e desativa o antigo com is_active=false, preservando o histórico das cobranças que já usaram o preço anterior.

​
Data Object

Este é o formato completo retornado em create, get, update, itens de list e em data.object dos webhooks price.*. 
{
  "id": "price_123",
  "object": "price",
  "created_at": "2026-05-16T14:09:27Z",
  "currency": "brl",
  "is_active": true,
  "livemode": true,
  "metadata": {
    "reference_id": "id_456"
  },
  "name": "Mensal",
  "product": "prod_123",
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "trial_period_days": null,
    "usage_type": "licensed"
  },
  "tax_behavior": "unspecified",
  "type": "recurring",
  "unit_amount": 9990,
  "updated_at": "2026-05-16T15:02:10Z"
}
​
id
string
Identificador do preço. Usa o prefixo price_*.
​
object
string
Sempre "price".
​
created_at
string
Data de criação em ISO 8601.
​
currency
string
Moeda em código ISO de 3 letras minúsculas, como brl.
​
is_active
boolean
true enquanto o preço pode ser usado em novos checkouts e assinaturas. false desativa o preço sem afetar cobranças que já o utilizaram.
​
livemode
boolean
true em produção; false em ambiente de teste.
​
metadata
object
Objeto livre para correlacionar o preço com o seu sistema. Quando vazio, retorna {}.
​
name
string | null
Nome interno do preço, como Mensal ou Anual. Vem null quando não foi informado.
​
product
string
ID do produto (prod_*) ao qual este preço pertence.
​
recurring
object | null
Configuração de recorrência. Vem null em preços one_time.
​
tax_behavior
string | null
Como o imposto se relaciona ao valor: unspecified, inclusive (imposto já incluso no valor) ou exclusive (imposto somado ao valor).
​
type
string
Forma de cobrança: one_time para compra única ou recurring para cobrança que se repete em um intervalo.
​
unit_amount
integer
Valor cobrado, em centavos da moeda. 9990 equivale a R$ 99,90.
​
updated_at
string | null
Data da última atualização em ISO 8601. Vem null enquanto o preço nunca foi atualizado.

​
Operações

​
Webhooks

Mudanças nesse objeto disparam os seguintes eventos de webhook: O payload sempre carrega o objeto price completo em data.object; eventos de update também incluem data.previous_attributes com os valores anteriores dos campos alterados.