Register a domain

The full flow, including the cases you'll hit in production.

1. Find the name

Use search for a name the user has in mind, or suggest for ideas. Show the user the domain and register × min_years as the price.

2. Get the owner's details

The registry needs the domain owner's name, email, phone and address. Send them as contact on the first order; they're saved as your default contact. If the owner isn't you (for example your customer), pass their details as contact each time, or save them with POST /contacts and send contact_id.

For .com.au and .au you also need au_eligibility. See .com.au and .au.

3. Place the order

shell

curl https://plonki.com.au/v1/domains \
  -H "Authorization: Bearer $PLONKI_KEY" \
  -H "Idempotency-Key: signup-8271" \
  -H "Content-Type: application/json" \
  -d '{"domain": "acmecoffee.com", "years": 1, "max_price": 3399, "payment": "auto"}'

4. Handle the result

status	Do this
`completed`	Done. Connect it (step 5).
`awaiting_payment`	Your balance was short (or you chose `payment: "checkout"`). Send the payer to `checkout_url`. When they pay, the domain registers and you get `order.completed`.
`processing`	The registry is slow. Poll the order or wait for the webhook. Don't place another order.
`failed`	Read `error`. Payment went back to your balance.

Payment options

`auto` (default)	Pay from balance; if it's short, return a checkout link.
`balance`	Balance only. Fails with `insufficient_balance` if short.
`checkout`	Always return a checkout link, for when your customer pays.

5. Connect it

Point it at the host, add DNS records, or set nameservers.

Renewing

Domains last for the years you buy. Renew with POST /domains/{domain}/renew beforeexpires_at. Automatic renewal isn't available yet, so track expires_at on your side.