> ## 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. # Preços > Defina valor, moeda e cadência de cobrança — o objeto Price atrelado a um produto. Um **preço** (`price`) descreve **quanto** e **como** você cobra: o valor unitário, a moeda, se é compra única ou recorrente e o comportamento tributário. Ele sempre pertence a um [produto](/features/products) — o produto diz **o que** você vende, o preço diz os termos da cobrança. Essa separação deixa o mesmo produto ter várias formas de cobrança sem duplicar a oferta. **Preços são imutáveis nos campos de valor.** `currency`, `unit_amount`, `type`, `recurring` e o produto vinculado **não se editam** depois que o preço existe — eles precisam ser auditáveis. Para mudar valor, cadência ou trial padrão, você **cria um preço novo** e desativa o antigo. Só `name`, `is_active`, `tax_behavior` e `metadata` são editáveis. ## Modelo conceitual ```mermaid theme={} flowchart LR P[Product] -- default_price --> M[Price mensal · recurring] P --> A[Price anual · recurring] P --> U[Price avulso · one_time] M -. usado em .-> CK[Checkout / Assinatura] ``` | Objeto | Responsabilidade | Campos centrais | | ----------- | ---------------------------------------- | --------------------------------------------------------------------------- | | **Product** | O que você vende (catálogo) | `name`, `description`, `image_url`, `default_price` | | **Price** | Termos da cobrança vinculados ao produto | `unit_amount`, `currency`, `type`, `recurring`, `tax_behavior`, `is_active` | O schema público completo está em [Objeto price](/api-reference/prices). ## Anatomia do preço | Campo | Tipo | Descrição | | -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------ | | `id` | `string` | ID do preço (`price_*`). | | `object` | `string` | Sempre `"price"`. | | `product` | `string` | Produto dono do preço. No create, você informa esse vínculo como `product_id`. | | `name` | `string \| null` | Rótulo interno opcional (`Mensal`, `Anual Early Bird`). | | `type` | `string` | `one_time` (compra única) ou `recurring` (assinatura). Default `one_time`. | | `currency` | `string` | Código ISO 4217 em minúsculas (`brl`). | | `unit_amount` | `integer` | Valor **unitário em centavos**, inteiro ≥ 0. | | `recurring` | `object \| null` | Cadência recorrente (`interval`, `interval_count`, `trial_period_days`, `usage_type`). `null` em `one_time`. | | `tax_behavior` | `string` | `unspecified`, `inclusive` ou `exclusive`. Default `unspecified`. | | `is_active` | `boolean` | `false` tira o preço de novas vendas sem apagar histórico. | | `livemode` | `boolean` | `true` em produção; `false` em ambiente de teste. | | `metadata` | `object` | Pares chave→valor livres, controlados por você. `{}` quando vazio. | | `created_at` | `string` | ISO 8601. | | `updated_at` | `string \| null` | ISO 8601 ou `null`. | ## Tipos de preço Um preço é `one_time` **ou** `recurring`. O tipo define se o objeto carrega `recurring`. ### One-time — compra única Cobrança avulsa, sem renovação. O campo `recurring` fica `null` e **não pode** ser enviado. `unit_amount` pode ser `0` (oferta gratuita). ```json theme={} { "currency": "brl", "recurring": null, "type": "one_time", "unit_amount": 4990 } ``` ### Recurring — assinatura Cobrança que renova na cadência definida por `recurring.interval` × `recurring.interval_count`. `unit_amount` é inteiro ≥ 0; envie `0` para uma assinatura gratuita naquela cadência. ```json theme={} { "currency": "brl", "recurring": { "interval": "month", "interval_count": 1 }, "type": "recurring", "unit_amount": 9990 } ``` Preço recorrente gratuito continua sendo `type: "recurring"` e precisa de `recurring.interval`. Assinaturas compostas só por preços zero geram invoices pagas, sem tentativa de cobrança. ## Cadências suportadas `recurring.interval` combinado com `recurring.interval_count` cobre praticamente qualquer ritmo de cobrança: | Cadência | `interval` | `interval_count` | | ---------- | ---------- | ---------------- | | Diária | `day` | `1` | | Semanal | `week` | `1` | | Quinzenal | `week` | `2` | | Mensal | `month` | `1` | | Bimestral | `month` | `2` | | Trimestral | `month` | `3` | | Semestral | `month` | `6` | | Anual | `year` | `1` | | Bienal | `year` | `2` | `interval_count` é inteiro ≥ 1 (default `1`); enviar valor não-inteiro ou menor que `1` retorna `400`. ## Criar um preço Um preço sempre nasce atrelado a um produto existente, via `product_id`. O preço precisa de um `product_id` válido daquela organização. Crie o produto antes em [Produtos](/features/products), com ou sem preço inicial. Envie `product_id`, `currency`, `unit_amount` e o `type`. Para `recurring`, inclua `recurring.interval`. Use `set_as_default: true` para apontar o `default_price` do produto para este preço logo após a criação. ```bash Compra única theme={} curl -X POST "https://api.chargefy.io/v1/prices" \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "currency": "brl", "name": "Avulso", "product_id": "prod_123", "type": "one_time", "unit_amount": 4990 }' ``` ```bash Recorrente theme={} curl -X POST "https://api.chargefy.io/v1/prices" \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "currency": "brl", "name": "Mensal", "product_id": "prod_123", "recurring": { "interval": "month", "interval_count": 1 }, "type": "recurring", "unit_amount": 9990 }' ``` ```bash Recorrente gratuito theme={} curl -X POST "https://api.chargefy.io/v1/prices" \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "currency": "brl", "name": "Mensal gratuito", "product_id": "prod_123", "recurring": { "interval": "month", "interval_count": 1 }, "type": "recurring", "unit_amount": 0 }' ``` ```bash Recorrente + virar padrão theme={} curl -X POST "https://api.chargefy.io/v1/prices" \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "currency": "brl", "name": "Anual", "product_id": "prod_123", "recurring": { "interval": "year", "interval_count": 1 }, "set_as_default": true, "type": "recurring", "unit_amount": 99000 }' ``` A criação retorna `200 OK` com o objeto `price` completo e dispara o webhook [`price.created`](/api-reference/webhooks/price.created). Contrato completo em [Criar preço](/api-reference/prices/create). ### Preço padrão do produto `product.default_price` é o preço que os fluxos usam quando partem do produto. Há três formas de defini-lo: | Quando | Como | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Na criação do produto | `default_price_index` aponta o índice em `prices[]` (default `0`) quando `prices[]` tem itens. | | Ao adicionar um preço novo | `POST /v1/prices` com `set_as_default: true`. | | A qualquer momento | `POST /v1/products/{id}` com `default_price_id` apontando um preço **daquele** produto. A resposta pública vem como `default_price`. | ## Múltiplos preços no mesmo produto O padrão recomendado para variações de cobrança é **um produto com vários preços**, em vez de produtos duplicados. Casos comuns: * mensal + anual no mesmo plano * compra única + versão recorrente do mesmo item * preço padrão + preço promocional desativado depois * preços com `name` interno como `Mensal`, `Anual Early Bird` ou `Equipe 10+` Para listar os preços de um produto: `GET /v1/prices?product_id=prod_123`. Por padrão a lista traz só `is_active=true`; envie `is_active=false` para ver os arquivados ou `is_active=all` para ambos. ## Quantidade Um `price` é sempre **unitário**. A multiplicação acontece no checkout, pela quantidade: ```text theme={} Total da linha = price.unit_amount × quantidade ``` Se você vende por assento, licença ou unidade, o caminho é esse: preço unitário no catálogo + quantidade no checkout. Não crie um preço por faixa de quantidade. ## Comportamento tributário `tax_behavior` declara como o imposto se relaciona com `unit_amount`: | `tax_behavior` | Significado | | -------------- | --------------------------------------------- | | `unspecified` | Sem comportamento fiscal declarado (default). | | `inclusive` | O imposto já está embutido em `unit_amount`. | | `exclusive` | O imposto é somado por cima de `unit_amount`. | Hoje `tax_behavior` é **declarativo**: faz parte do contrato público do preço, mas não altera sozinho o valor final cobrado. Ele é editável a qualquer momento via `POST /v1/prices/{id}`. ## Atualizar um preço O update é **merge**: você envia só os campos que mudam, via `POST /v1/prices/{id}`. Apenas estes são editáveis: | Campo | Observação | | -------------- | ----------------------------------------------------- | | `name` | Rótulo interno. Envie `null` para limpar. | | `is_active` | `false` arquiva; `true` reativa. Boolean obrigatório. | | `tax_behavior` | `unspecified`, `inclusive` ou `exclusive`. | | `metadata` | Substitui o objeto inteiro quando enviado. | Tentar atualizar `currency`, `unit_amount`, `type`, `recurring` ou `product_id` retorna `400` — esses campos são imutáveis. Enviar `active` também é rejeitado: o campo público é `is_active`. A resposta direta **não** carrega diff; quem precisa do diff lê o webhook [`price.updated`](/api-reference/webhooks/price.updated), que traz o objeto completo em `data.object` e os campos alterados em `data.previous_attributes`. Contrato completo em [Atualizar preço](/api-reference/prices/update). ## Trocar o valor de um preço Como os campos de valor são imutáveis, "mudar o preço" é sempre criar um novo e desativar o antigo: `POST /v1/prices` com o mesmo `product_id` e o valor/cadência atualizados. Use `set_as_default: true` se ele deve virar o padrão do produto. `POST /v1/prices/{id_antigo}` com `is_active: false` (ou `DELETE /v1/prices/{id_antigo}`). Vendas e assinaturas existentes seguem no preço antigo; novos fluxos passam a usar o novo. ## Arquivar e remover `DELETE /v1/prices/{id}` expressa "tirar de uso". O efeito depende do histórico: É removido de fato. A resposta é `{ "id": "price_123", "object": "price", "deleted": true }`. Não pode sumir sem quebrar histórico, então é **desativado** (`is_active = false`) e a resposta é o objeto `price` completo atualizado. Ele sai de novas vendas, mas pagamentos e assinaturas em curso permanecem íntegros. Você também pode arquivar diretamente com `POST /v1/prices/{id}` enviando `is_active: false`, sem tentar a remoção. Para reativar um preço arquivado: `POST /v1/prices/{id}` com `is_active: true`. Arquivar (`is_active: false`) não cancela assinaturas nem vendas que já usam o preço — só impede que ele entre em **novos** fluxos de compra. ## Próximos passos Schema público completo e campos retornados. O catálogo que dá origem aos preços. Contrato do `POST /v1/prices`. Como o preço vira uma cobrança.