> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> O objeto Price

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.*`.

```json theme={}
{
  "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"
}
```

<ResponseField name="id" type="string">
  Identificador do preço. Usa o prefixo `price_*`.
</ResponseField>

<ResponseField name="object" type="string">
  Sempre `"price"`.
</ResponseField>

<ResponseField name="created_at" type="string">
  Data de criação em ISO 8601.
</ResponseField>

<ResponseField name="currency" type="string">
  Moeda em código ISO de 3 letras minúsculas, como `brl`.
</ResponseField>

<ResponseField name="is_active" type="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.
</ResponseField>

<ResponseField name="livemode" type="boolean">
  `true` em produção; `false` em ambiente de teste.
</ResponseField>

<ResponseField name="metadata" type="object">
  Objeto livre para correlacionar o preço com o seu sistema. Quando vazio,
  retorna `{}`.
</ResponseField>

<ResponseField name="name" type="string | null">
  Nome interno do preço, como `Mensal` ou `Anual`. Vem `null` quando não foi
  informado.
</ResponseField>

<ResponseField name="product" type="string">
  ID do produto (`prod_*`) ao qual este preço pertence.
</ResponseField>

<ResponseField name="recurring" type="object | null">
  Configuração de recorrência. Vem `null` em preços `one_time`.

  <Expandable title="Campos de recurring">
    <ResponseField name="interval" type="string">
      Intervalo de recorrência: `day`, `week`, `month` ou `year`.
    </ResponseField>

    <ResponseField name="interval_count" type="integer">
      Número de intervalos entre cada cobrança. `interval=month` com
      `interval_count=3` cobra a cada três meses.
    </ResponseField>

    <ResponseField name="trial_period_days" type="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.
    </ResponseField>

    <ResponseField name="usage_type" type="string">
      Sempre `licensed`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="tax_behavior" type="string | null">
  Como o imposto se relaciona ao valor: `unspecified`, `inclusive` (imposto já
  incluso no valor) ou `exclusive` (imposto somado ao valor).
</ResponseField>

<ResponseField name="type" type="string">
  Forma de cobrança: `one_time` para compra única ou `recurring` para cobrança
  que se repete em um intervalo.
</ResponseField>

<ResponseField name="unit_amount" type="integer">
  Valor cobrado, em centavos da moeda. `9990` equivale a R\$ 99,90.
</ResponseField>

<ResponseField name="updated_at" type="string | null">
  Data da última atualização em ISO 8601. Vem `null` enquanto o preço nunca foi
  atualizado.
</ResponseField>

## Operações

* [Listar preços](/api-reference/prices/list)
* [Criar preço](/api-reference/prices/create)
* [Consultar preço](/api-reference/prices/get)
* [Atualizar preço](/api-reference/prices/update)
* [Remover preço](/api-reference/prices/delete)

## Webhooks

Mudanças nesse objeto disparam os seguintes eventos de webhook:

* [`price.created`](/api-reference/webhooks/price.created)
* [`price.updated`](/api-reference/webhooks/price.updated)

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.