> ## 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.
# Como produtos e preços funcionam
> Entenda como Products e Prices formam o catálogo usado em checkouts, Links de pagamento, faturas e assinaturas.
Produtos e preços separam **o que você vende** de **como você cobra**. Um
Product guarda a identidade comercial da oferta; um Price registra o valor e as
condições financeiras que podem ser reutilizados em diferentes fluxos de
pagamento.
Essa separação permite oferecer, por exemplo, o mesmo Plano Pro por R\$ 99 ao
mês ou R\$ 990 ao ano sem duplicar nome, descrição, imagem e destaques do
produto.
## Product e Price
| Recurso | Responde a | Guarda |
| ----------- | ------------------------------- | ----------------------------------------------------------------------------------- |
| **Product** | O que o cliente está comprando? | Nome, descrição, imagem, destaques comerciais, status e preço padrão. |
| **Price** | Quanto e em que ritmo ele paga? | Valor unitário, moeda, compra única ou recorrente, cadência, trial padrão e status. |
Um Product pode existir sem preço enquanto a condição comercial ainda não foi
definida, mas um Price sempre pertence a um Product. O produto pode reunir
vários preços ao mesmo tempo e aponta um deles como `default_price`.
**O preço padrão é uma escolha para novos fluxos.** Trocá-lo não altera
Checkout Sessions, faturas ou assinaturas que já foram criadas com outra
condição.
## Quando criar outro produto ou outro preço
Use esta regra para evitar um catálogo duplicado ou difícil de manter:
| O que mudou | Como modelar |
| ------------------------------------------------ | ----------------------------------------------------------------------- |
| Nome, entrega, público ou conjunto de benefícios | Crie outro Product. |
| Apenas valor, cadência, moeda ou trial padrão | Crie outro Price no mesmo Product. |
| Quantidade comprada, como licenças ou unidades | Reutilize o Price unitário e altere `quantity` no item. |
| Valor calculado para um único pedido | Use `price_data` inline naquele fluxo, sem criar um Price reutilizável. |
### Planos com benefícios diferentes
Se Básico, Pro e Empresa liberam recursos diferentes, cada plano deve ser um
Product. Dentro de cada produto, crie Prices mensal e anual quando apenas a
forma de cobrança variar.
### Mensal e anual da mesma oferta
Mantenha um único Product e vincule dois Prices recorrentes. A página de venda
pode oferecer as duas condições sem repetir a apresentação do plano.
### Por assento, licença ou unidade
Um Price é unitário. A quantidade pertence ao item do checkout, da fatura ou da
assinatura:
```text theme={"theme":"css-variables"}
total da linha = price.unit_amount × quantity
```
Para cobrar R\$ 50 por usuário, crie um Price de R\$ 50 e envie a quantidade
de usuários. Não crie um preço diferente para cada tamanho de equipe.
## Compra única e recorrência
| Tipo | Use quando | O que o Price define |
| ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------- |
| `one_time` | O cliente paga uma vez por um item, serviço ou taxa. | Valor e moeda; `recurring` fica `null`. |
| `recurring` | A cobrança deve renovar em uma cadência. | Valor, moeda, intervalo, quantidade de intervalos e trial padrão opcional. |
O Dashboard oferece os ciclos mensal, trimestral, semestral e anual. Pela API,
`recurring.interval` aceita `day`, `week`, `month` ou `year`, e
`interval_count` forma cadências como quinzenal (`week` + `2`) ou trimestral
(`month` + `3`).
Um preço pode ser gratuito (`unit_amount: 0`). Quando há cobrança, o valor
positivo mínimo é R\$ 5,00.
O trial salvo no Price é o padrão para novas assinaturas que usam aquela
condição. Uma Checkout Session ou Subscription criada pela API pode informar
outro período para aquele fluxo.
## Catálogo ou preço inline
O catálogo é a melhor opção quando a oferta será reutilizada. Um Price
cadastrado recebe um ID `price_*` e pode ser selecionado no Dashboard ou
referenciado pela API em diferentes vendas.
Use preço inline quando o valor pertence somente à operação atual, como uma
proposta negociada ou um carrinho calculado pelo seu sistema. Nesse caso,
`price_data` fica registrado no item da Checkout Session, do Link de pagamento,
da fatura ou da assinatura, mas **não cria um novo Price no catálogo**.
| Escolha | Melhor para | Consequência |
| ------------------- | ----------------------------------------------- | ------------------------------------------------------------ |
| Price do catálogo | Planos, SKUs e serviços vendidos repetidamente. | Reutilização, filtros, preço padrão e gestão pelo Dashboard. |
| `price_data` inline | Valor específico de um pedido ou contrato. | A condição fica restrita ao item que a recebeu. |
Se o mesmo preço inline começar a aparecer em muitas operações, transforme-o
em um Price do catálogo. Isso reduz divergências e facilita a troca da
condição padrão.
## Onde o catálogo é usado
| Fluxo | Papel de Product e Price |
| --------------------- | ------------------------------------------------------------------- |
| **Link de pagamento** | Define a oferta reutilizável compartilhada com vários compradores. |
| **Checkout Session** | Define os itens de uma tentativa de compra criada pelo seu sistema. |
| **Fatura** | Forma as linhas cobradas de um cliente específico. |
| **Assinatura** | Define itens, quantidade, valor e cadência das renovações. |
Quando um fluxo referencia um Price, ele preserva a condição usada naquela
criação. Alterar o preço padrão do Product não reescreve documentos financeiros
ou assinaturas existentes.
## Mudanças e histórico
Valor, moeda, tipo, recorrência, trial padrão e Product relacionado são
imutáveis depois que o Price é criado. Para publicar uma nova condição:
1. crie outro Price no mesmo Product;
2. torne o novo Price padrão quando necessário;
3. arquive o anterior para impedir seu uso em novos fluxos.
O Price antigo continua disponível no histórico de vendas, faturas e
assinaturas. Produtos também podem ser arquivados sem apagar os pagamentos que
já os referenciam.
Arquivar não cancela uma assinatura existente nem troca automaticamente seus
itens. Se clientes atuais também devem migrar, atualize cada assinatura de
forma explícita e revise o comportamento de pró-rata.
## Próximos passos
Crie produtos, adicione condições de cobrança e publique mudanças pelo
Dashboard ou pela API.
Transforme uma oferta do catálogo em uma URL reutilizável.
Monte uma compra com itens definidos pelo seu sistema.
Use Prices recorrentes para iniciar e renovar uma cobrança.