# Credits

> How the credit pool works, which jobs cost credits, and the spend order.

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

**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:

1. **promo** — time-limited (30-day expiry), spent first.
2. **welcome** — 20 one-time credits granted on signup, never expires while
   the account exists.
3. **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. Available on every plan,
including Free:

| Bundle    | Price | Effective per-credit |
| --------- | ----- | -------------------- |
| 100       | $10   | $0.100               |
| 500       | $50   | $0.100               |
| 1,000     | $99   | $0.099               |

## Reading the balance

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

```jsonc
{
  "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.