Preços

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_b8NCTpGCSqFAdDqY",
  "object": "price",
  "created_at": "2026-05-16T14:09:27Z",
  "currency": "brl",
  "is_active": true,
  "livemode": true,
  "metadata": {},
  "name": "Mensal",
  "product": "prod_RG7RCGeQ9E8ZxJDr",
  "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"
}

string

Identificador do preço. Usa o prefixo price_*.

string

Sempre "price".

string

Data de criação em ISO 8601.

string

Moeda em código ISO de 3 letras minúsculas, como brl.

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.

boolean

true em produção; false em ambiente de teste.

object

Objeto livre para correlacionar o preço com o seu sistema. Quando vazio, retorna {}.

string | null

Nome interno do preço, como Mensal ou Anual. Vem null quando não foi informado.

string

ID do produto (prod_*) ao qual este preço pertence.

object | null

Configuração de recorrência. Vem null em preços one_time.

Show Campos de recurring

string

Intervalo de recorrência.

Valor	Descrição
`day`	Cobrança diária.
`week`	Cobrança semanal.
`month`	Cobrança mensal.
`year`	Cobrança anual.

integer

Número de intervalos entre cada cobrança. interval=month com interval_count=3 cobra a cada três meses. Na criação, o máximo por unidade é day=1460, week=208, month=48 e year=4.

integer | null

Trial padrão desse preço recorrente. Quando um checkout de assinatura não envia subscription_data.trial_period_days nem subscription_data.trial_end, esse valor pode ser usado para criar a assinatura em trial.

string

Sempre licensed.

string | null

Como o imposto se relaciona ao valor.

Valor	Descrição
`unspecified`	Comportamento de imposto não definido.
`inclusive`	Imposto já incluso no valor.
`exclusive`	Imposto somado ao valor.

string

Forma de cobrança do preço.

Valor	Descrição
`one_time`	Compra única.
`recurring`	Cobrança que se repete em um intervalo definido.

integer

Valor cobrado, em centavos da moeda. 9990 equivale a R$ 99,90.

string | null

Data da última atualização em ISO 8601. Vem null enquanto o preço nunca foi atualizado.

Operações

Eventos

Mudanças nesse objeto disparam os seguintes eventos:

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.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Data Object

Operações

Eventos

​Data Object

​Operações

​Eventos

Data Object

Operações

Eventos