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 (subcents) | Price per unit in subcents (divide by 10,000 to get BRL) |
| Recurrence interval | month or year |
| Interval count | Repetitions (e.g., 3 months) |
| Usage type | licensed (fixed) or metered (measured) |
Monetary Values — Subcents
Prices use subcents with 4 decimal places of precision:
| Value in subcents | Value in BRL |
|---|---|
| 1,000,000 | R$ 100.00 |
| 500,000 | R$ 50.00 |
| 9,990 | R$ 0.999 |
Important: Only the Price, SubscriptionItem, ProposalItem, and PlanChange models use subcents (divide by 10,000). All other monetary fields (Invoice, Payment, Credit, etc.) use cents (divide by 100).
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_subcents | Price per unit in this tier |
flat_amount_subcents | 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 |