# Pricing

> Fixed platform fee + metered AI credits. Four plans (Free, Growth, Pro, Enterprise).

Source: https://docs.hatched.live/docs/billing/pricing

Hatched separates **platform fee** from **AI usage**.

- The platform fee covers everything that's free to run at scale: events,
  rules engine, widgets, analytics, SDK, webhooks, dashboard, config versions.
- AI usage — image generation, onboarding chat, plan/theme/guide generation —
  is metered in **credits** at a flat rate: **1 credit = $0.10 = 1 completed AI job**.

## Plans

| Plan         | Monthly | Events / mo | Credits included / mo | Welcome credits |
| ------------ | ------- | ----------- | --------------------- | --------------- |
| Free         | $0      | 10,000      | 0                     | 20 (one-time)   |
| Growth       | $149    | 500,000     | 50                    | —               |
| Pro          | $499    | 5,000,000   | 250                   | —               |
| Enterprise   | custom  | contract    | contract              | —               |

Billing is monthly via Stripe. Annual billing is available on Growth/Pro at
~17% discount (`$1,490/yr` and `$4,990/yr`).

## Feature gates

The capability matrix below is the runtime `PLAN_MATRIX` in
[`packages/shared/src/pricing.ts`](https://github.com/Flalingo/hatched/blob/main/packages/shared/src/pricing.ts).
That file is the single source of truth — if anything below disagrees with
the API guard, the API wins. (See Codex review fix #28.)

| Capability                        | Free | Growth | Pro     | Enterprise |
| --------------------------------- | ---- | ------ | ------- | ---------- |
| Skills, coins, badges, streaks    | ✓    | ✓      | ✓       | ✓          |
| Tokens (secondary currency)       | ✓    | ✓      | ✓       | ✓          |
| Leaderboards, webhooks, SDK, keys | ✓    | ✓      | ✓       | ✓          |
| Gamification Planner              | ✓    | ✓      | ✓       | ✓          |
| Wardrobe / Cause counter / Kudos  | ✓    | ✓      | ✓       | ✓          |
| Teams / SeeSaw Bump               | ✓    | ✓      | ✓       | ✓          |
| Marketplace                       | —    | ✓      | ✓       | ✓          |
| Evolution                         | —    | ✓      | ✓       | ✓          |
| Evolution — generative art        | —    | ✓      | ✓       | ✓          |
| Generative media                  | —    | ✓      | ✓       | ✓          |
| Mystery Box / Boosters            | —    | ✓      | ✓       | ✓          |
| Group Quest                       | —    | ✓      | ✓       | ✓          |
| Leagues / Lottery                 | —    | ✓      | ✓       | ✓          |
| Profile Pages v2                  | —    | ✓      | ✓       | ✓          |
| Paths                             | —    | —      | ✓       | ✓          |
| Multi-audience                    | —    | —      | up to 3 | contract   |
| Advanced analytics (cohorts)      | —    | —      | ✓       | ✓          |
| Mentorship                        | —    | —      | ✓       | ✓          |
| Founding Cohort / Profile Pages   | —    | —      | ✓       | ✓          |
| Council (endgame elitism)         | —    | —      | —       | ✓          |

When a plan-locked endpoint is called, the API returns `403 plan_feature_locked`
with `details.required_plan` so the caller can prompt an upgrade.

## Widget availability by plan

Hatched ships **14 mountable widgets**. The plan a widget needs is derived from
the same `PLAN_MATRIX` capabilities above — this table just maps each widget's
public mount name to its minimum plan. Each widget's data attributes, scopes and
endpoints live in the [widget reference](/docs/reference/widgets).

| Widget (`data-hatched-mount`) | Token  | Free | Growth | Pro | Enterprise |
| ----------------------------- | ------ | ---- | ------ | --- | ---------- |
| `buddy`                       | embed  | ✓    | ✓      | ✓   | ✓          |
| `badges`                      | embed  | ✓    | ✓      | ✓   | ✓          |
| `streak`                      | embed  | ✓    | ✓      | ✓   | ✓          |
| `tokens`                      | embed  | ✓    | ✓      | ✓   | ✓          |
| `leaderboard`                 | embed  | ✓    | ✓      | ✓   | ✓          |
| `kudos`                       | session| ✓    | ✓      | ✓   | ✓          |
| `feed`                        | embed  | ✓    | ✓      | ✓   | ✓          |
| `hexad-survey`                | session| ✓    | ✓      | ✓   | ✓          |
| `marketplace`                 | session| —    | ✓      | ✓   | ✓          |
| `group-quest`                 | session| —    | ✓      | ✓   | ✓          |
| `mystery-box`                 | session| —    | ✓      | ✓   | ✓          |
| `league`                      | embed  | —    | ✓      | ✓   | ✓          |
| `path`                        | embed  | —    | —      | ✓   | ✓          |
| `council`                     | session| —    | —      | —   | ✓          |

The **Token** column is the token a *write*-capable widget needs: `session`
widgets perform writes (purchase, send, join, open, submit) and must be mounted
with a server-minted session token, while `embed` widgets are read-only. Where
the table and `PLAN_MATRIX` ever disagree, `PLAN_MATRIX` wins.

## Event quota enforcement

Each plan has a monthly event ingestion quota. Requests include
`X-Event-Quota-*` response headers; crossing 80% triggers a dashboard banner
and a `usage.threshold_reached` webhook; crossing 100% returns
`402 event_quota_exceeded` until the monthly reset (first of the next UTC month)
or a plan upgrade.

## Related

- [Credits](/docs/billing/credits)
- [Stripe portal](/docs/billing/stripe-portal)
- [Handling 402](/docs/billing/handling-402)