Buying domains

Itoka sells .com, .net and .org in Naira. The first year of a registration is priced from the registry's register cost, and every year after it at the renewal price, which search results and quotes always show as renewal_kobo. Renewing and transferring (which adds a year) cost the renewal price times the years. .ng and .com.ng are coming. Amounts are in kobo.

The flow

1. Search: GET /domains/search?q=ojaara. No key needed.
2. A registrant contact: the person or organisation that legally owns the domain. POST /contacts once; reuse its id.
3. A quote: POST /quotes. The price is held for 15 minutes.
4. An order: POST /orders with the quote, the contact and an Idempotency-Key header. If a promo code or your Itoka credit covers it, it's paid at once; otherwise send the buyer to checkout_url to pay by card or bank transfer.
5. Wait: poll GET /orders/{id} every few seconds while it's paid, or listen for the order.completed webhook.

const { results } = await itoka.domains.search('ojaara');
const pick = results.find((r) => r.available); // { name: 'ojaara.com', price_kobo: 2000000, renewal_kobo: 2850000, … }

const contact = await itoka.contacts.create({
  first_name: 'Ada', last_name: 'Obi', company_name: 'Ojaara Ltd', email: 'ada@ojaara.ng', phone: '08031234567',
  street: 'Herbert Macaulay Way', number: '12', city: 'Yaba', state: 'Lagos', zipcode: '101212', country: 'NG',
});

// Quote + order in one call. promoCode, or useCredit: true, pay at once when they cover it all.
const { order, checkoutUrl } = await itoka.domains.buy({ name: pick.name, contactId: contact.id, years: 1 });
if (checkoutUrl) console.log('Pay here:', checkoutUrl);

const done = await itoka.orders.wait(order.id, { timeoutMs: 15 * 60_000 });
console.log(done.status, done.status_text);

Search results

Without an extension, q checks every extension on sale; with one (ojaara.net) it puts that first. Each result has available, price_kobo (null while prices aren't set) and a reason when it isn't available. Premium-priced names aren't sold yet. Searching is limited to 30 a minute per IP address.

Contacts

Required: first_name, last_name, email, phone (Nigerian numbers like 0803… are fine), street, city, zipcode (the postcode; Nigerian ones are 6 digits), country (two letters, NG). Optional: company_name, number, state. The registry keeps these details; they're not shown publicly. Use the real owner's details: changing the registrant later can mean confirmation emails and a 60-day transfer lock.

Promo codes

A promo code (like HACK-7K3M9P) pays the whole price of a registration it covers, typically one .com for one year. Send it as promo_code on the order; the order comes back paid with checkout_url: "". Check one first without using it:

curl https://api.itoka.ng/api/v1/promo-codes/check -H "Authorization: Bearer $ITOKA_API_KEY" \
  -H "Content-Type: application/json" -d '{"code": "HACK-7K3M9P", "quote_id": "QUOTE_ID"}'
# {"promo": {"code": "HACK-7K3M9P", "discount_kobo": 2000000, "due_kobo": 0, "renewal_kobo": 2850000, …}}

Each code works once and each account can use one per promotion. Trying codes is limited to 10 a minute per account. If the registration fails, nothing is charged, the order ends cancelled and the code works again. Renewals are at the normal price.

Itoka credit

Send use_credit: true to pay what your account's Itoka credit covers; Bachs collects the rest. Credit comes from orders that couldn't be completed and were paid by bank transfer (which can't be refunded automatically).

Orders

Every order has a status_text: a sentence you can show as is. GET /orders/{id} also returns its timeline and, once paid, its invoice.

Buying for a client

Add client_email to a registration order, with the client's details as the registrant. When it completes, the client is emailed an invitation to take ownership; you stay on as a manager until they remove you. In the dashboard you can also send your client a pay link so they pay directly.

Managing domains

• GET /domains lists yours and those shared with you; GET /domains/{name} shows one, with its expiry, lock, nameservers and whether it uses Itoka's DNS.
• PATCH /domains/{name} with nameservers (2 to 6 hostnames), locked: true or auto_renew. Pointing a domain at ns1/ns2.itoka.ng creates its zone first if it has none. Unlocking and the transfer code are dashboard-only.
• Renewing: POST /quotes with kind: "renew", then POST /orders without a contact. Nothing renews by itself yet; Itoka emails reminders 30, 7 and 1 days before the deadline, each with a pay link anyone can use.
• Transferring in: POST /quotes with kind: "transfer", then POST /orders with the contact and the transfer_code from your current registrar. It usually completes in 5 to 7 days.