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.

Produto ≠ PreçoNa Chargefy, Product e Price são objetos separados. Um produto descreve o que você vende. Um preço descreve como cobrar. Um produto pode ter múltiplos preços, e products.default_price_id define qual deles é o padrão para fluxos que trabalham em nível de produto.

​
Modelo conceitual

  • Product — entidade de catálogo. Carrega name, description, metadata, is_tax_applicable e o ponteiro default_price_id.
  • Price — entidade de cobrança vinculada a um produto. Carrega unit_amount, currency, type, interval, interval_count, active, tax_behavior, metadata e name opcional como rótulo interno.
  • products.default_price_id — resolve o preço padrão quando o fluxo parte do produto e não de um preço específico.
Ver o objeto em detalhe em Preços.

​
Criar um produto

​
Nome e descrição

O básico do catálogo:
  • Nome — título do produto
  • Descrição — texto do produto

​
Ao menos um preço

Todo produto nasce com pelo menos um preço.
1

Dashboard

A criação no painel começa com um preço base. Se você quiser outras variações, normalmente adiciona depois na gestão de preços do produto.
2

API

A criação via API aceita prices[] inline. O primeiro preço vira products.default_price_id, ou você escolhe outro com default_price_index.

​
Shape do preço inicial

No fluxo atual, o preço criado junto do produto segue este contrato:
  • type = 'one_time' para compra única
  • type = 'recurring' para cobrança recorrente
  • interval em day, week, month ou year quando type = 'recurring'
  • interval_count para cobrar a cada N intervalos
  • unit_amount em centavos
  • unit_amount = 0 apenas para one_time
await chargefy.products.create({
  name: 'Plano Pro',
  prices: [
    {
      currency: 'brl',
      unit_amount: 9990,
      type: 'recurring',
      interval: 'month',
      interval_count: 1,
    },
    {
      currency: 'brl',
      unit_amount: 99900,
      type: 'recurring',
      interval: 'year',
      interval_count: 1,
    },
  ],
  default_price_index: 0,
})

​
Metadata

metadata existe tanto em Product quanto em Price. Use para:
  • tags internas
  • mapeamento com IDs externos
  • flags de catálogo
  • contexto adicional para integrações
Esta página cobre modelagem de catálogo. Comportamento de checkout e cobrança fica nas páginas específicas de checkout, pagamentos e assinaturas.

​
Múltiplos preços no mesmo produto

O padrão recomendado para variações de cobrança é um produto com vários preços. Exemplos comuns:
  • mensal + anual no mesmo plano
  • compra única + versão recorrente do mesmo item
  • preço padrão + preço promocional arquivado depois
  • preços com name interno como Mensal, Anual Early Bird ou Equipe 10+
O products.default_price_id define qual preço aparece como padrão. Esse padrão pode ser trocado de duas formas:
  • criando um novo preço com set_as_default: true
  • marcando outro preço como padrão na gestão de preços do produto
Para adicionar um preço novo em um produto existente, use Criar Preço com product_id.

​
Arquivar um preço sem deletar o produto

O campo canônico para disponibilidade de preço é prices.active. Quando active: false:
  • o preço sai de novos fluxos de compra
  • o produto continua existindo
  • o histórico continua íntegro
Para mudar valor, moeda ou cadência de um preço, siga a regra:
  1. crie um preço novo
  2. troque o padrão se necessário
  3. arquive o antigo
Isso mantém a imutabilidade de cobrança e evita reescrever histórico.

​
Atualizar um produto

No fluxo atual, trate estes campos como editáveis com segurança:
  • name
  • description
  • metadata
  • is_archived
Para alterações de preço, use os endpoints e telas de preço, não o update de produto.

​
Arquivar um produto

Arquivar um produto remove o item do catálogo e dos novos fluxos de compra, mas não apaga histórico. Isso é o caminho certo quando você quer tirar uma oferta de circulação sem destruir:
  • vendas já registradas
  • assinaturas já associadas
  • eventos e auditoria do catálogo

​
Impostos

A modelagem atual separa o tema em dois níveis:
  • products.is_tax_applicable indica se o produto é tributável
  • prices.tax_behavior descreve como o imposto se relaciona com o valor do preço
Valores suportados em tax_behavior:
  • unspecified
  • inclusive
  • exclusive
Hoje esse campo é declarativo. Ele já faz parte do contrato público do preço, mas não muda o cálculo final da cobrança sozinho.

​
Quantidade

Price é unitário. A multiplicação acontece depois, no fluxo de checkout/assinatura, usando quantidade. Em termos de modelo: 
Total = prices.unit_amount × checkouts.quantity
Se você vende por assento, licença ou unidade, o caminho é esse modelo unitário + quantidade. Ver Precificação por Quantidade.