# Register a domain end-to-end

A safe registration flow for an autonomous agent: check price, confirm the TLD is registerable, rehearse, then commit idempotently.

## 1. Check availability and price

```bash
curl -X POST https://api.porkbun.com/api/json/v3/domain/checkDomain/example.com \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_..."}'
```

The response includes availability and the registration price. **Prices are in USD; `/domain/create` wants the cost in integer US cents and rejects a mismatch** — so carry the quote forward.

## 2. Confirm the TLD is registerable via the API

Some TLDs have registry eligibility rules the API can't submit (e.g. `.us`, `.ca`, `.eu`, `.au`) and are website-only. Check first instead of discovering this from a failed call:

```bash
curl 'https://api.porkbun.com/api/json/v3/domain/getRegistrationRequirements/com' \
  -H 'X-API-Key: pk1_...' -H 'X-Secret-API-Key: sk1_...'
```

Look at `apiRegisterable`. If `false`, register on the website. If `true`, `requestSchema` is the JSON Schema for the create body, and `registrationDurationYears` is the fixed term used.

## 3. Rehearse with a dry run

Pass `dryRun: true` to run every pre-flight check (availability, price match, eligibility, funds, spend limit) **without charging or creating anything** — it doesn't even consume your create rate-limit budget:

```bash
curl -X POST https://api.porkbun.com/api/json/v3/domain/create/example.com \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...","cost":1000,"agreeToTerms":"yes","dryRun":true}'
```

The preview returns `wouldSucceed`, `cost`, `costDisplay`, `balance`, `sufficientFunds`, and (if a cap is set) `withinMonthlySpendLimit`. Only commit if `wouldSucceed` is true.

## 4. Register (for real, and safely)

Send an **`Idempotency-Key`** header — a retry within 24h replays the original result instead of registering (or charging) twice.

```bash
curl -X POST https://api.porkbun.com/api/json/v3/domain/create/example.com \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...","cost":1000,"agreeToTerms":"yes"}'
```

- `cost` — integer US cents, must match the current quote from step 1.
- `agreeToTerms` — must be `"yes"`; you're accepting the registration agreement, ToS, privacy policy, and auto-renew terms.
- Your account email and phone must be verified before the first registration.

## 5. Verify

```bash
curl 'https://api.porkbun.com/api/json/v3/domain/get/example.com' \
  -H 'X-API-Key: pk1_...' -H 'X-Secret-API-Key: sk1_...'
```

## Guardrails worth setting

- **Spend controls** — a monthly API spend cap, low-balance alerts, and auto top-up (on the [API settings page](https://porkbun.com/account/api)). A registration that would exceed the cap is blocked with `MONTHLY_SPEND_LIMIT_EXCEEDED`.
- **Per-key scoping** — restrict the key to the domains/IPs it needs.

## Related

- [Getting started](https://porkbun.com/llms/guides/getting-started) · [Dynamic DNS](https://porkbun.com/llms/guides/dynamic-dns)
- Domain endpoints: https://porkbun.com/llms/domain


---

## More

- Guides (how-tos): https://porkbun.com/llms/guides
- Topic index: https://porkbun.com/llms
- Full reference (one file): https://porkbun.com/llms-full.txt
- OpenAPI spec (full schemas): https://porkbun.com/api/json/v3/spec
- Short overview: https://porkbun.com/llms.txt
- Official MCP server: https://github.com/oborseth/Porkbun-MCP (`npx -y @porkbunllc/mcp-server`)
- Create API keys: https://porkbun.com/account/api