Hatched Documentation

1 credit = $0.10 = 1 completed AI job.

Every call to Hatched's generative pipeline authorizes one credit up-front, runs, then commits (success) or rolls back (failure). Preset and cache-hit paths cost zero credits.

Job types

Job	Credits
Onboarding chat turn	1
Website scan	1
Plan generation / regeneration	1
Theme synthesis	1
Integration guide	1
Hatch (creature)	1
Equip / composite edit	1
Evolve (generative)	1
Badge icon	1
Skill icon	1
Marketplace item image	1
Stage asset	1
Preset / cache-hit evolution	0
Automatic asset prompt preparation	0

Three pools

Credits live in three pools, spent in this order:

promo — time-limited bonus credits from top-up bundles. They expire 365 days after purchase (surfaced as promo_expires_at) and are spent first.
welcome — 20 one-time credits granted on signup to the Free plan, never expires while the account exists.
paid — top-ups and subscription grants. Top-up credits persist while the account exists and the payment is not refunded.

A single 1-credit job debits from exactly one pool — no splitting across pools. If the pool with enough balance for the requested cost exists, we use it; otherwise the API returns 402 credit_insufficient.

Monthly subscription grant

Growth grants 50 credits each month on successful invoice.payment_succeeded. Pro grants 250. Granted credits go to the paid pool. Paid credits do not expire until the subscription ends.

Top-up bundles

Bought via Stripe Checkout from the Billing page. The smallest bundle is available on every plan including Free; the larger bundles require Growth or above. Base credits land in the paid pool and never expire; bonus credits land in the promo pool and expire 365 days after purchase. The effective per-credit price below accounts for the bonus.

Bundle	Base	Bonus	Total	Price	Effective per-credit	Plans
100	100	—	100	$10	$0.100	Free+
500	500	+50	550	$50	$0.091	Growth+
1,000	1,000	+150	1,150	$99	$0.086	Growth+
2,500	2,500	+500	3,000	$249	$0.083	Growth+

Reading the balance

GET /api/v1/credits/balance
Authorization: Bearer hatch_live_…

{
  "welcome": 7,
  "paid": 43,
  "promo": 0,
  "promo_expires_at": null,
  "total_spendable": 50
}

Every authenticated response also includes:

X-Credits-Remaining
X-Credits-Welcome-Remaining
X-Credits-Paid-Remaining
X-Credits-Promo-Remaining

Ledger

GET /api/v1/credits/ledger?limit=50 returns the 50 most recent AI usage rows (authorize/commit/rollback) — the same rows the dashboard's Billing page displays.

Onboarding cap

During the very first publish, Hatched generates at most 4 images (creature, one stage preview, one badge, one item). Remaining badge/item icons stay in pending and surface as "Generate now" actions in the dashboard — the operator pays 1 credit per asset they actually need.

Credits