Envelope System
Ozzie divides a user's income into six budget envelopes. Two are set by the plan algorithm; four are flexible and weighted by the user's personality type.
The six envelopes
| Key | Type | Description |
|---|---|---|
bills | Fixed | Housing, utilities — calculated by the plan algorithm from fixed expense data |
future | Goal | Savings / debt goal allocation — calculated by the plan algorithm |
daily_living | Flexible | Food, transport — personality-weighted |
health_wellness | Flexible | Health, pharmacy, gym — personality-weighted |
lifestyle | Flexible | Entertainment, clothing — personality-weighted |
people | Flexible | Gifts, family, social — personality-weighted |
The bills and future envelopes are derived from the user's financial intake. The remaining four flexible envelopes are allocated from the remaining income according to the personality weights below.
Personality weight table
After subtracting bills and future, the remaining spendable income is distributed across the four flexible envelopes. The percentage weights vary by personality type:
| Envelope | HOTSHOT | STOCKPILER | GIVER | INDEPENDENT |
|---|---|---|---|---|
daily_living | 30% | 35% | 30% | 25% |
health_wellness | 15% | 20% | 15% | 25% |
lifestyle | 35% | 20% | 20% | 25% |
people | 20% | 25% | 35% | 25% |
STOCKPILER note: Before distributing across flexible envelopes, STOCKPILER receives an additional +5% goal allocation added to the future envelope. The remaining income after both bills and the boosted future is then split using the weights above.
INDEPENDENT note: All four flexible envelopes receive equal 25% weight — the system deliberately avoids prescribing a distribution pattern.
Viewing a user's envelope allocations
Via financial-profile endpoint (allocations only)
The GET /v1/users/:id/financial-profile endpoint returns envelope allocations weighted by the personality_type you pass as a query parameter:
curl "https://api.ozzieapp.com/v1/users/ozz_usr_01HX9K/financial-profile?personality_type=GIVER" \
-H "Authorization: Bearer YOUR_TOKEN"
{
"object": "financial_profile",
"data": {
"user_id": "ozz_usr_01HX9K",
"personality_type": "GIVER",
"envelopes": {
"bills": { "allocated_pct": 30.0 },
"future": { "allocated_pct": 16.0 },
"daily_living": { "allocated_pct": 16.2 },
"health_wellness": { "allocated_pct": 8.1 },
"lifestyle": { "allocated_pct": 10.8 },
"people": { "allocated_pct": 18.9 }
}
}
}
Via plan generate (allocations with amounts)
POST /v1/users/:id/plan/generate returns both allocated_pct and allocated_amount for each envelope, computed from the user's actual intake figures:
"envelopes": {
"bills": { "allocated_pct": 30.0, "allocated_amount": 1500.00 },
"future": { "allocated_pct": 16.0, "allocated_amount": 800.00 },
"daily_living": { "allocated_pct": 16.2, "allocated_amount": 810.00 },
...
}
Transaction to envelope mapping
When transactions are parsed via POST /v1/transactions/parse, each record is automatically assigned an envelope field based on its category:
| Transaction category | Envelope |
|---|---|
housing, utilities | bills |
food, transport | daily_living |
health | health_wellness |
entertainment, education, clothing | lifestyle |
gifts, family, social | people |
Your application uses envelope and amount_cents from parsed transactions to compute spending against each envelope's allocation.
Plan tiers
Ozzie assigns a plan tier based on the ratio of the user's disposable income to total income. The tier label (e.g., "20/80") indicates how much goes to savings vs. spending. Pass plan_tier from the plan response when generating money moves:
POST /v1/money-moves/generate
{
"user_id": "ozz_usr_01HX9K",
"personality_type": "STOCKPILER",
"plan_tier": "30/70"
}
Money move do task amounts are calculated from the future envelope allocation divided by the move cadence.