> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brew.new/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits

> Credit-metered operations on the Brew Public API v1 — usage-metered AI generation vs fixed per-operation media costs, X-Credit-Cost / X-Credits-Remaining headers, checking balance with GET /v1/usage, INSUFFICIENT_CREDITS (402) and SERVICE_UNAVAILABLE (503) semantics.

Some operations consume **credits** — the unit Brew meters AI generation and media rendering with. Each credit is worth \$0.01 of underlying spend. Every credit-metered operation charges only on success.

There are **two metering modes**:

* **Usage-metered** — email generation, email import, AI email edits, semantic brand-image search, and image generation charge the **actual model usage** (token input/output for the email agent; embedding/image-gateway cost for search + image generation). The cost scales with the work, so there is **no fixed number** and **no `X-Credit-Cost` header**. The call still gates: an empty balance is rejected up front.
* **Fixed** — every other media/render operation charges a **flat, published per-operation cost**, reported via the `X-Credit-Cost` response header.

## Which operations cost credits

| Operation                                             | Route                                                              | Metering          |
| ----------------------------------------------------- | ------------------------------------------------------------------ | ----------------- |
| Generate an email                                     | `POST /v1/emails`                                                  | Usage (tokens)    |
| Import an email (HTML / MJML / JSX → editable design) | `POST /v1/emails/import`                                           | Usage (tokens)    |
| Edit an email (AI prompt edit)                        | `PATCH /v1/emails/{emailId}`                                       | Usage (tokens)    |
| Semantic brand-image search                           | `GET /v1/brand/images?q=…`                                         | Usage (embedding) |
| Generate an image                                     | `POST /v1/content/generate-image`                                  | Usage (image)     |
| Preview an email across real inboxes/devices          | `POST /v1/emails/{emailId}/client-previews`                        | Fixed             |
| Generate / animate a GIF                              | `POST /v1/content/gif` (`from: "prompt" \| "image" \| "video"`)    | Fixed             |
| Optimize / resize an image                            | `POST /v1/content/transform` (`operation: "optimize" \| "resize"`) | Fixed             |
| Render HTML to a PNG                                  | `POST /v1/content/html-to-png`                                     | Fixed             |
| Add an image (saves to the brand image library)       | `POST /v1/content/add-image`                                       | Fixed             |

Everything else is **free**: all reads (including the no-`q` browse of `GET /v1/brand/images`), the accessibility audit (`GET /v1/emails/{emailId}/accessibility-audit`), and contact validation (`POST /v1/contacts/validate`).

For **fixed** operations the cost is published and does not vary with output size — the authoritative number for a call is its `X-Credit-Cost` response header. For **usage-metered** operations the charge equals the real token/image cost the work incurred (no header). The full per-operation metering table is available machine-readably at **`GET /v1/help`** → `credits.operations`.

<Note>
  The client-preview render is **value-aligned**: the fixed cost is charged only when at least one client actually produces a screenshot. A batch where zero clients finish in time (or a preview-provider outage) returns a retryable `503 SERVICE_UNAVAILABLE` and is **not** billed.
</Note>

## Check your balance — `GET /v1/usage`

There is no dry-run cost preview. Credit-metered calls just charge on success; if you want to know what you can afford before you call, read your balance from the billing surface:

```bash theme={null}
curl "https://brew.new/api/v1/usage" \
  -H "Authorization: Bearer brew_…"
```

```jsonc theme={null}
{
  "plan": "pro",
  "credits":    { "limit": 500, "used": 260, "remaining": 240 },
  "emailSends": { "limit": 50000, "used": 1200, "remaining": 48800 },
  "period":     { "start": "2026-06-01T00:00:00.000Z", "end": "2026-07-01T00:00:00.000Z" }
}
```

A `null` `limit` / `remaining` means **unlimited**. `credits` is the AI/media balance; `emailSends` is your monthly delivery allowance. Both reset at the `period.end` boundary. `GET /v1/usage` requires the `emails` scope.

## What a real (charged) call reports

A successful **fixed**-cost call charges the published cost **exactly once** and returns two headers:

| Header                | Meaning                        |
| --------------------- | ------------------------------ |
| `X-Credit-Cost`       | Credits charged for this call. |
| `X-Credits-Remaining` | Balance after the charge.      |

**Usage-metered** calls (email generate/edit, image generation) bill the actual model usage to your account and do **not** return these headers — read your balance from `GET /v1/usage` before and after to see the delta.

Charging is idempotent: a retry with the same `Idempotency-Key` replays the original response and is **not** charged again.

## Errors

| Code                   | Status | When                                                                                                                                                                                                                                                                                       |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `INSUFFICIENT_CREDITS` | `402`  | Your balance is too low — below the fixed cost (fixed ops) or empty (usage-metered ops). `details` carries `{ cost, remaining, planKey }`. Top up / upgrade — there's no `Retry-After` because credits reset at the billing-period boundary (read it from `GET /v1/usage`'s `period.end`). |
| `SERVICE_UNAVAILABLE`  | `503`  | The credit balance could not be **verified** (a transient billing-backend outage). The gate **fails closed** — it refuses rather than do paid work it can't meter. Retryable: a `Retry-After` header tells you when.                                                                       |

`402` is a confirmed empty balance; `503` is "can't check right now, try again shortly" — branch on the `code`, never on the message.

## Need Help?

Our team is ready to support you at every step of your journey with Brew. Choose the option that works best for you:

<Tabs>
  <Tab title="Self-Service Tools">
    <CardGroup cols="2">
      <Card title="Search Documentation" icon="magnifying-glass" color="#c44925">
        Type in the "Ask any question" search bar at the top left to instantly find relevant documentation pages.
      </Card>

      <Card title="ChatGPT/Claude Integration" icon="robot" color="#c44925">
        Click "Open in ChatGPT" at the top right of any page to analyze documentation with ChatGPT or Claude for deeper insights.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Talk to Our Team">
    <CardGroup cols="2">
      <Card title="Schedule a Call" icon="calendar" color="#c44925" href="https://calendar.google.com/calendar/u/0/appointments/schedules/AcZssZ1iYoRUG1J792XQpbuQLjSRRDupr7MwraFK-HQRCtTYdBmrQi8nZu2qXfzKQigb8gbKJK3KN3-R">
        Book time with our founders for personalized guidance on strategy, best practices, or complex implementation questions.
      </Card>

      <Card title="Call Us Directly" icon="phone" color="#c44925">
        Need immediate assistance? Reach us at **+1-(332)-203-2145** for urgent issues or time-sensitive questions.
      </Card>

      <Card title="Slack Channel" icon="slack" color="#c44925">
        Our preferred support channel. You'll receive an invite after signup for direct founder support and fast responses.
      </Card>

      <Card title="Email Support" icon="envelope" color="#c44925" href="mailto:support@brew.new">
        Contact us at **[support@brew.new](mailto:support@brew.new)** for detailed inquiries or if you prefer not to use Slack.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>