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.

Modelo licensedUm price tem valor unitário fixo, e a multiplicação por quantidade acontece no checkout (campo quantity) e na assinatura (subscription_product_prices.quantity). Isso cobre o caso “por assento” sem precisar de um tipo especial de preço.

​
Visão Geral

No modelo licensed + quantity, cada price tem um unit_amount estável, e o total da cobrança é unit_amount × quantity. Conforme o cliente adiciona ou remove assentos, o quantity da assinatura é atualizado — o unit_amount do price nunca muda. 
Total = unit_amount × quantity

Exemplo: R$ 49,90/assento × 10 assentos = R$ 499,00/mês

​
Vantagens do modelo

VantagemDescrição
PrevisibilidadeCliente sabe exatamente unit_amount × quantity
EscalabilidadeAjuste de quantity não recria o price
AuditabilidadeCada cobrança registra quantity no momento
Modelo do mercadoMesmo modelo “licensed” usado por outras plataformas

​
Modelagem no banco

prices
├── id
├── type           = 'recurring'
├── currency       = 'brl'
├── unit_amount    = 4990      (R$ 49,90 por assento)
├── interval       = 'month'
├── interval_count = 1
└── ...

checkouts / subscription_product_prices
└── quantity       = 10         (definido no checkout, persiste na assinatura)
A Price é criada uma vez com o valor por assento. Todos os checkouts e assinaturas reusam essa mesma price; o que varia é o quantity.

​
Criar produto com preço por assento

import { Chargefy } from '@chargefy/sdk';
const chargefy = new Chargefy({ accessToken: process.env.CHARGEFY_ACCESS_TOKEN });

await chargefy.sdk.organizations.createProduct('org_01j9abc333', {
  name: 'Team Plan',
  description: 'Assinatura mensal por assento',
  prices: [
    {
      currency: 'brl',
      unit_amount: 4990,        // R$ 49,90 por assento/mês
      type: 'recurring',
      interval: 'month',
      interval_count: 1,
    },
  ],
});

​
Criar checkout com quantidade

No corpo do checkout (hosted ou programático), informe quantity junto com o product_price_id: 
const session = await chargefy.checkouts.create({
  product_price_id: 'price_01j9xyz998',
  quantity: 10,
});
// session.amount = 4990 * 10 = 49900 (R$ 499,00)

​
Atualizar assinatura (aumentar/reduzir assentos)

await chargefy.subscriptions.update('sub_01j9xyz123', {
  quantity: 15,
});
// Próxima cobrança usa quantity=15; período atual é pro-rateado conforme política

​
Boas práticas

  • Valide o quantity no backend antes de processar pagamentos — números negativos ou 0 devem rejeitar.
  • Não edite unit_amount pra representar outra faixa — crie um novo price (ex: price_team_starter_5 vs price_team_pro_50) e migre a assinatura se necessário.
  • Proration de mudanças de quantity é política da plataforma; a Chargefy recalcula unit_amount × quantity no próximo ciclo por padrão.
  • Quantidade em faturas/comprovantes: o quantity é persistido em subscription_product_prices e usado pra calcular cada fatura.

​
Diferença vs “seat-based” legado

A Chargefy não tem mais um amount_type='seat_based' ou flag is_seat_based. O modelo licensed + quantity substitui integralmente essa categoria. Qualquer produto que você queira comercializar “por assento” vira simplesmente:
  • Um price com type='recurring'
  • Um cliente chama o checkout com quantity
Nenhuma configuração especial em nível de produto.