Preços

Como modelar valores de cobrança na Chargefy

Price é o objeto canônico de cobrança.

Todo pagamento (único ou recorrente) usa um Price atrelado a um Product. O valor, a moeda, a cadência e o comportamento tributário vivem aqui.

Um produto pode ter vários preços; o checkout escolhe qual usar.

​

Campos

Campo	Tipo	Descrição
id	string	ID único do preço
product_id	string	FK obrigatória pra um produto
type	'one_time' | 'recurring'	Tipo — compra única ou assinatura
currency	string	ISO 4217 em minúsculas (ex: brl, usd)
unit_amount	integer	Valor unitário em minor units (centavos)
interval	'day' | 'week' | 'month' | 'year' | null	Obrigatório se type='recurring'
interval_count	integer	Quantidade de intervalos entre cobranças. null em one_time, default 1 em recurring
tax_behavior	'unspecified' | 'inclusive' | 'exclusive'	Como o imposto se relaciona com unit_amount
active	boolean	Ativo pra novas vendas. false = arquivado
metadata	object	Metadata livre (chave/valor)
zoop_recurrence_plan_id	string | null	Set pelo backend quando o seller tem Zoop configurado

​

Tipos de preço

​

One-time (type = 'one_time')

Cobrança única. Aceita PIX, cartão e boleto. unit_amount pode ser 0 (produto gratuito).

{
  "type": "one_time",
  "currency": "brl",
  "unit_amount": 4990,
  "interval": null,
  "interval_count": null
}

​

Recurring (type = 'recurring')

Assinatura. Requer interval + interval_count. unit_amount precisa ser > 0.

{
  "type": "recurring",
  "currency": "brl",
  "unit_amount": 9990,
  "interval": "month",
  "interval_count": 1
}

​

Cadências suportadas

interval × interval_count dá bastante flexibilidade:

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

Hoje a integração Zoop honra interval_count = 1 apenas. Outros valores são aceitos no schema e exibidos na UI, mas a cobrança cai pro padrão (1) até o ajuste Zoop. Roadmap próximo.

​

Quantidade (licensed)

O unit_amount é unitário. Multiplicação por quantity acontece no checkout / assinatura — não no preço. É o modelo “licensed” da Stripe.

Total cobrado = unit_amount × quantity

quantity é persistido em:

• checkouts.quantity (definido pelo comprador)
• subscription_product_prices.quantity (persistido na assinatura, base de toda renovação)

Isso substitui o que antes era chamado de “seat-based pricing” — ver Precificação por Quantidade.

​

Tax behavior

Declaração de como o imposto se relaciona com unit_amount:

• unspecified (default) — o campo existe mas não afeta cobrança. Use quando não tem posição definida.
• inclusive — imposto já incluso no valor. Ex: unit_amount = 10000 já contém ISS/IVA.
• exclusive — imposto adicional. Ex: unit_amount = 10000 + imposto somado no checkout.

Hoje o campo é declarativo e não afeta o cálculo final da cobrança. Roadmap aplica durante finalização do pagamento quando o módulo de impostos for lançado.

​

Arquivar vs deletar

Prices não são deletáveis — cobranças históricas dependem deles. A operação correta é arquivar via PATCH /v1/prices/:id { active: false }.

• Preço arquivado: some de novos checkouts
• Assinaturas em curso: continuam renovando com o preço original (imutabilidade)
• Pra reativar: PATCH { active: true }

​

Imutabilidade (padrão Stripe)

Estes campos não podem ser alterados depois que o preço existe:

• currency
• unit_amount
• type
• interval
• interval_count
• product_id

Pra mudar qualquer um deles: crie um preço novo e arquive o antigo. O PATCH /v1/prices/:id rejeita os campos acima com 400.

Mutáveis via PATCH:

• active (arquivar/desarquivar)
• metadata
• tax_behavior

​

Criar via API

Inline com o produto (padrão — equivalente ao default_price_data da Stripe):

await chargefy.products.create({
  name: 'Plano Pro',
  prices: [
    { currency: 'brl', unit_amount: 9990, type: 'recurring', interval: 'month' },
  ],
})

Standalone (adicionar preço a produto existente):

curl -X POST "https://api.chargefy.io/functions/v1/create-price" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "product_id": "prod_abc123",
    "currency": "brl",
    "unit_amount": 99000,
    "type": "recurring",
    "interval": "year",
    "set_as_default": false
  }'

Ver Criar Preço e Atualizar Preço.

​

Relação com Zoop (recorrência)

Quando um preço recurring é criado e o seller tem conta Zoop ativa, o backend cria automaticamente um plano de recorrência Zoop e persiste o ID em price.zoop_recurrence_plan_id. Esse plano é o que a Zoop usa pra cobrar o cliente nos ciclos futuros.

Se o seller ainda não tem Zoop configurado na criação, o campo fica null e o plano é criado lazy na primeira venda elegível.