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

# NameGrid Credits: Prepaid Billing for Domain Operations

> NameGrid uses a credit-based billing model where 1 credit equals $1. Credits are debited atomically when you register or renew domains.

NameGrid uses a prepaid credit system to keep billing simple and predictable. Instead of managing invoices or payment methods per transaction, you maintain a credit balance in your workspace and spend from it as you register and renew domains. Every operation that costs money tells you exactly how many credits were charged.

## What are credits?

Credits are the currency of the NameGrid platform. The conversion is straightforward: **1 credit = \$1 USD**.

* **Registration** — spending credits registers a new domain under your workspace.
* **Renewal** — spending credits extends your domain's expiry date.
* **Atomic deduction** — credits are debited in a single atomic operation. If your balance is too low, the entire request fails immediately and no credits are deducted. Credits are never partially reserved or oversold.

<Info>
  Because debits are atomic, you will never end up with a partially registered domain and a negative balance. Either the full cost is available and the operation proceeds, or it isn't and nothing changes.
</Info>

## Checking your balance

Call `GET /v1/account` at any time to see your current credit balance.

```bash theme={null}
curl https://api.namegrid.org/v1/account \
  -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx"
```

The `credits` object in the response reflects your real-time balance:

```json theme={null}
{
  "credits": {
    "balance": 42.50
  }
}
```

Build balance checks into your workflows before bulk operations to avoid hitting the insufficient-credits error mid-run.

## When credits are charged

Credits are charged at two points in the domain lifecycle:

**Domain registration** — credits are debited when you call `POST /v1/domains`. The response includes a `creditsCharged` field so you know exactly what was spent:

```json theme={null}
{
  "domain": "example.com",
  "status": "active",
  "creditsCharged": 12.00
}
```

**Domain renewal** — credits are debited when you call `POST /v1/domains/{domain}/renew`. The same `creditsCharged` field appears in the renewal response.

If your balance is insufficient at the time of either request, the API returns a `402 Payment Required` error with details about the shortfall:

```json theme={null}
{ "error": "Insufficient credits", "required": 12, "balance": 5 }
```

<Warning>
  Registration and renewal fail **immediately** with a `402` error if your credit balance is too low — no partial operations occur. Top up your balance in the dashboard before kicking off registrations or bulk renewals to avoid interruptions.
</Warning>

<Note>
  The `required` field in the `402` response tells you exactly how many credits you need. Use it to calculate the top-up amount before retrying.
</Note>

## Topping up credits

Purchase additional credits through the NameGrid dashboard at [https://app.namegrid.org](https://app.namegrid.org). Credits are added to your workspace balance instantly after payment and are available for use immediately.