Prices and Pricing Models
Each product can have multiple prices, allowing variants by currency, billing interval, or pricing model. Prices are largely immutable after creation — only the name and metadata can be changed. To change values, deactivate the old price and create a new one.
Price Fields
| Field | Description |
|---|---|
| Name | Variant name (e.g., "Standard", "Pro") |
| Currency | ISO 4217 code (default: BRL) |
| Active | Whether the price is available for use |
| Billing Scheme | Pricing model |
| Unit amount | Price per unit, in BRL (up to 4 decimal places) |
| Recurrence interval | month or year |
| Interval count | Repetitions (e.g., 3 months) |
| Usage type | licensed (fixed) or metered (measured) |
Monetary Values — Subcents
Prices are decimal numbers in BRL and accept up to 4 decimal places, which allows fractional unit prices:
| Value | Meaning |
|---|---|
100 | R$ 100.00 |
50.5 | R$ 50.50 |
0.999 | R$ 0.999 |
Important: prices are the only place where all 4 decimals are preserved. Every other monetary value (invoice, payment, credit) is rounded to 2 decimals.
Pricing Models
1. Per Unit (per_unit)
The simplest model: fixed price per unit.
Price: R$ 5.00/user/month
10 users = R$ 50.00/month
2. Graduated (tiered + graduated)
Each tier has a different price, and only the units within each tier are charged at that rate.
Tier 1: 1-10 units → R$ 10.00/unit
Tier 2: 11-50 units → R$ 8.00/unit
Tier 3: 51+ units → R$ 5.00/unit
For 25 units:
(10 x R$ 10.00) + (15 x R$ 8.00) = R$ 220.00
3. Volume (tiered + volume)
When the customer reaches a tier, all units are charged at that tier's rate.
Tier 1: 1-10 units → R$ 10.00/unit
Tier 2: 11-50 units → R$ 8.00/unit
Tier 3: 51+ units → R$ 5.00/unit
For 25 units:
25 x R$ 8.00 = R$ 200.00 (all in tier 2)
4. Package (package)
Fixed price for a defined package of items.
Tier Configuration
Each tier defines:
| Field | Description |
|---|---|
up_to | Upper limit of the tier (null = unlimited, final tier) |
unit_amount | Price per unit in this tier |
flat_amount | Additional flat amount per tier (default: 0) |
Usage Type
| Type | Description |
|---|---|
licensed | Fixed quantity defined in the subscription |
metered | Quantity measured and reported throughout the cycle |