Preços e Modelos de Precificação
Cada produto pode ter múltiplos preços, permitindo variantes por moeda, intervalo de cobrança ou modelo de precificação. Os preços são em grande parte imutáveis após criação — apenas nome e metadados podem ser alterados. Para mudar valores, desative o preço antigo e crie um novo.
Campos do Preço
| Campo | Descrição |
|---|---|
| Nome | Nome da variante (ex: "Standard", "Pro") |
| Moeda | Código ISO 4217 (padrão: BRL) |
| Ativo | Se o preço está disponível para uso |
| Billing Scheme | Modelo de precificação |
| Valor unitário (subcents) | Preço por unidade em subcents (÷10.000 para obter reais) |
| Intervalo de recorrência | month ou year |
| Contagem de intervalos | Repetições (ex: 3 meses) |
| Tipo de uso | licensed (fixa) ou metered (medida) |
Valores Monetários — Subcents
Preços utilizam subcents com precisão de 4 casas decimais:
| Valor em subcents | Valor em BRL |
|---|---|
| 1.000.000 | R$ 100,00 |
| 500.000 | R$ 50,00 |
| 9.990 | R$ 0,999 |
Importante: Apenas os modelos Price, SubscriptionItem, ProposalItem e PlanChange usam subcents (÷10.000). Todos os outros campos monetários (Invoice, Payment, Credit, etc.) usam cents (÷100).
Modelos de Precificação
1. Por Unidade (per_unit)
O modelo mais simples: preço fixo por unidade.
Preço: R$ 5,00/usuário/mês
10 usuários = R$ 50,00/mês
2. Escalonado — Graduated (tiered + graduated)
Cada faixa tem um preço diferente, e apenas as unidades dentro de cada faixa são cobradas naquele valor.
Faixa 1: 1-10 unidades → R$ 10,00/un
Faixa 2: 11-50 unidades → R$ 8,00/un
Faixa 3: 51+ unidades → R$ 5,00/un
Para 25 unidades:
(10 × R$ 10,00) + (15 × R$ 8,00) = R$ 220,00
3. Volume (tiered + volume)
Quando o cliente atinge uma faixa, todas as unidades são cobradas pelo valor daquela faixa.
Faixa 1: 1-10 unidades → R$ 10,00/un
Faixa 2: 11-50 unidades → R$ 8,00/un
Faixa 3: 51+ unidades → R$ 5,00/un
Para 25 unidades:
25 × R$ 8,00 = R$ 200,00 (todas na faixa 2)
4. Pacote (package)
Preço fixo para um pacote de itens definido.
Configuração de Faixas (Tiers)
Cada faixa define:
| Campo | Descrição |
|---|---|
up_to | Limite superior da faixa (null = ilimitado, faixa final) |
unit_amount_subcents | Preço por unidade nesta faixa |
flat_amount_subcents | Valor fixo adicional por faixa (padrão: 0) |
Tipo de Uso
| Tipo | Descrição |
|---|---|
licensed | Quantidade fixa definida na assinatura |
metered | Quantidade medida e reportada ao longo do ciclo |