Domain Reseller API Reference

1Getting started

1. Your account must be enabled as a domain reseller. Until then the domain endpoints return an authorization error.
2. In your client panel, under Security, issue an API token and narrow its scope to the minimum your integration needs.
3. Add the egress IP of your own server to that token allowlist. A token without an IP restriction is usable from anywhere.
4. Fund the account. Registrations and renewals settle against your credit at call time; there is no post-paid billing.
5. Make a test call to the health endpoint and reconcile the returned tier and balance against the panel.

2Authentication and scope

Authentication uses a bearer token in the Authorization header. There is no session, cookie or CSRF layer; every request is independent and stateless. The token must never appear in a URL path, a query parameter or browser-side code, where it would be recorded in server logs, CDN logs and browser history.

curl -H "Authorization: Bearer sn_xxxxxxxx" \
     https://servernet.cloud/api/v1/ping

Scopes

Write scope implies read scope; the converse never holds. We recommend issuing a separate token per environment — one read-only for reporting, one write and IP-bound for the billing host. A leaked read-only token cannot incur cost.

3Response contract

Every response is a JSON envelope with a fixed shape. Client branching must key on the machine-readable error identifier, never on the message text. Message text is localizable and editable and is not part of the stable contract; identifiers are part of the v1 contract and will not be removed or redefined before a new major version.

{"ok": true,  "data": { ... }}
{"ok": false, "error": "insufficient_credit", "message": "..."}

4Endpoints

Availability and pricing

POST https://servernet.cloud/api/v1/domains/check
{"domain": "example.com", "tlds": ["com", "net"]}

{"ok": true, "data": [{
  "domain": "example.com", "state": "free", "available": true,
  "currency": "IRT",
  "price": {"register": 1150000, "renew": 1250000, "retail": 1320000},
  "discount_pct": 12.88, "price_floored": false
}]}

A true price_floored flag means your tier discount was not fully applied on that extension because the resulting price reached our margin floor. The condition is never hidden; it is described in full in the pricing section.

Registration

POST https://servernet.cloud/api/v1/domains
Idempotency-Key: your-order-12345
{"domain": "example.com", "years": 1,
 "nameservers": ["ns1.you.com", "ns2.you.com"]}

{"ok": true, "data": {
  "domain": "example.com", "status": "pending",
  "order_state": "registered", "registrant": "reseller",
  "charged": 1265000, "currency": "IRT"
}}

5Idempotency and retries

The server accepts requests without an Idempotency-Key header, but in that case **no duplicate protection applies whatsoever**; sending one on every billable operation is therefore a correctness requirement of any integration. The key is at most 80 characters and is claimed on a unique database index before any work is performed, so two concurrent requests carrying the same key can never produce two financial transactions. A replayed response is identical in substance to the original and carries a replayed flag. If the first attempt ends in an error the key is released — idempotency means one operation is not performed twice, not that one error is repeated forever.

sha256("renew|example.com|2027-01-01|1")

Retry with exponential backoff and jitter, reusing the same key; minting a fresh key on retry defeats the entire guarantee. Our official modules construct and persist this key for you.

6Error identifiers

7Pricing and tiers

The price returned by the API is your buying price: retail less the tier discount. The tier is derived from two metrics simultaneously — your trailing twelve month purchase volume and your active portfolio size — and is reviewed daily. A quoted price is not an execution guarantee; settlement is authoritative against the fresh quote taken at order time.

• Upgrades are immediate and apply the moment purchase volume crosses a threshold.
• Downgrades are gradual: a drop in volume first enters a grace period, then moves at most one step. The asymmetry is deliberate.
• Your current tier, the distance to the next threshold and the last review date are available in the reseller panel and in the health endpoint response.

The margin floor

Our margin varies per extension and follows the cost structure of the registry concerned. On thin-margin extensions — in practice also the highest demand ones — your tier discount applies only down to a floor that remains above our landed cost. Wherever that floor engages, the API sets price_floored true and returns the effective applied percentage separately.

Disclosing this constraint is a deliberate choice. An undeclared floor produces a discrepancy the client cannot reconcile, discoverable only by manually auditing invoices — precisely the work a loyalty programme is meant to eliminate.

8Quotas and limits

Exceeding a rate limit returns 429 and must be handled with backoff, not with additional concurrency. Each account additionally carries a daily spend cap, adjustable downward in the reseller panel. This cap is a blast-radius control: in a token compromise scenario it bounds the maximum loss achievable before anyone notices. We recommend setting it to a small multiple of your genuine daily turnover, not higher.

9Deliberately out of scope

The following are not unimplemented; they are deliberately excluded from the token surface. The criterion is explicit: any operation that, with a compromised token, transfers control of an end customer domain is performed only under human authentication in the panel. The transfer lock can be enabled over the API but never disabled — an operation that adds protection is safe, one that removes it is not.

10Official modules

Two reference implementations are maintained against this interface, both downloadable from the reseller panel. If your stack is one of these two, prefer the module over a hand-written integration: the financial safeguards are already implemented in it.

11Roadmap

The following are planned but not yet published in the v1 interface. Until release, calling the corresponding endpoint returns 404. Adding an endpoint is a backward-compatible change and does not increment the interface version; your client must not error on encountering an unknown field in a response.

Dashboard PDF version