Skip to main content

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.

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

CampoTipoDescrição
idstringID único do preço
product_idstringFK obrigatória pra um produto
type'one_time' | 'recurring'Tipo — compra única ou assinatura
currencystringISO 4217 em minúsculas (ex: brl, usd)
unit_amountintegerValor unitário em minor units (centavos)
interval'day' | 'week' | 'month' | 'year' | nullObrigatório se type='recurring'
interval_countintegerQuantidade 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
activebooleanAtivo pra novas vendas. false = arquivado
metadataobjectMetadata livre (chave/valor)
zoop_recurrence_plan_idstring | nullSet pelo backend quando o seller tem cadastro financeiro completo

​
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ênciaintervalinterval_count
Diáriaday1
Semanalweek1
Quinzenalweek2
Mensalmonth1
Bimestralmonth2
Trimestralmonth3
Semestralmonth6
Anualyear1
Bienalyear2
Hoje só interval_count = 1 é honrado na cobrança. Outros valores são aceitos no schema e exibidos na UI, mas caem pro padrão (1) até o 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”. 
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

Estes campos não podem ser alterados depois que o preço existe (campos de valor precisam ser auditáveis):
  • 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 (cria produto e preço em uma chamada): 
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.

​
Provisionamento do plano de recorrência

Quando um preço recurring é criado e o seller tem cadastro financeiro ativo, o backend cria automaticamente um plano de recorrência e persiste o ID em price.zoop_recurrence_plan_id. Esse plano é usado pra cobrar o cliente nos ciclos futuros. Se o seller ainda não tem cadastro completo na criação, o campo fica null e o plano é criado lazy na primeira venda elegível.