Skip to content

Organization API: customer portfolios and order status

Organization credentials are a separate integration mode from personal API keys. They do not automatically migrate personal domains or change existing integrations. An organization key selects one organization; external_customer_id selects a customer portfolio inside it. Neither field is a public customer identity.

Access and customer mapping

An active organization owner can create an organization API key in the organization dashboard. Keep the full key server-side; never put it in client JavaScript, source control or support messages. Use X-API-Key: <hd_org_credential>. Membership, customer state, namespace grants and domain binding are checked by the server. A key alone does not authorize every operation.

Read-only checks:

  • GET /api/v1/reseller/context: authenticated organization and allowed operations.
  • GET /api/v1/reseller/customers: active customers in that organization.
  • GET /api/v1/domains?external_customer_id=<reference>: that customer's managed domains.

Generate a stable opaque reference such as cust_7e95b0e6d7a24acb85ea81497f9b8b63. Use 12–160 letters, digits, underscores or hyphens, beginning with a letter or digit. Do not use names or email addresses. Keep the mapping to your own customer record in your system. Reuse an existing reference instead of creating one for every registration, renewal or retry.

Create a new customer using an owner/admin credential:

POST /api/v1/reseller/customers
X-API-Key: <organization-key>
Content-Type: application/json
Idempotency-Key: customer-create-7e95b0e6d7a24acb

{"external_customer_id":"cust_7e95b0e6d7a24acb85ea81497f9b8b63","holder_mode":"organization_default"}

An exact retry returns the existing customer (200 instead of the initial 201). Changed data with the same key is a 409 conflict. If the reference already exists under a different key, inspect the existing mapping rather than inventing another. Never send internal organization, customer, holder, payer or target-owner IDs to choose authority. Customer creation does not register or transfer a domain.

Registration and renewal

These requests can register/renew a domain and can charge under standard billing. Do not run them as connectivity tests. Agree the domain, term and billing policy before a canary. Examples are request shapes, not authorization to spend.

POST /api/v1/domains/register
X-API-Key: <organization-key>
Content-Type: application/json
Idempotency-Key: registration-7e95b0e6d7a24acb

{"domain":"approved-canary-label","tld":"agent","years":1,"agreed_to_terms":true,"payment_method":"gems","external_customer_id":"cust_7e95b0e6d7a24acb85ea81497f9b8b63"}

Use the domain ID/renewal link returned for the same customer, not an unrelated personal domain ID:

POST /renew/<domain-id>
X-API-Key: <organization-key>
Content-Type: application/json
Idempotency-Key: renewal-7e95b0e6d7a24acb

{"years":1,"payment_method":"gems","external_customer_id":"cust_7e95b0e6d7a24acb85ea81497f9b8b63"}

The organization needs the applicable register, renew, domains:list or dns:write grant. Domain management also requires its current organization/customer binding. A personal key is not interchangeable with an organization key after a move.

As of October 10, 2026 the sponsored registration/renewal implementation is in review, not a promise of live no-charge service. Operators must separately deploy the migration/code and activate an approved organization/namespace policy. There is no client-side sponsored switch and no dashboard policy editor.

When enabled for the authenticated organization and operation, the server records a sponsored order with zero due and payment_status: not_required, without a Wallet debit. Other organizations/namespaces continue using their existing pricing. Without a configured policy, normal billing still applies. With a configured but unavailable/disabled policy, the sponsorship implementation refuses the request instead of silently charging. Do not probe production by submitting an order to discover which billing policy is active. Obtain operator confirmation first.

For sponsored operations use a distinct Idempotency-Key for each intended registration or renewal: 16–128 letters, digits, underscores or hyphens. Persist the key and exact customer/domain/operation/years before sending. Keep both on timeouts/retries; a retry must not become another purchase. Customer creation has its own key and lifecycle. A fresh, intentional renewal needs a new key.

Exact completed replays return the existing order; their JSON shape can differ from the initial response. Store order_id and follow the status URL instead of depending on one success string. In-flight or uncertain sponsored outcomes return 409 and do not repeat registry work. A changed payload with a reused key is also 409: inspect the error, do not blindly retry. These sponsorship guarantees do not extend to every older personal/payment endpoint.

Status and recovery

Use the returned reseller_handoff.order_status_url, or:

GET /api/v1/reseller/orders/<order-id>?external_customer_id=cust_7e95b0e6d7a24acb85ea81497f9b8b63
X-API-Key: <organization-key>

Payment status and fulfillment are separate. For the sponsorship implementation, billing_mode: sponsored and payment_status: not_required mean no payment is needed—not that registration succeeded. Check fulfillment_status, management_ready, the domain status and expiry. Follow next_action and retain the order reference for support. On reconciliation/unknown outcomes, do not pay again, generate another request key or submit a duplicate registration/renewal. If no order ID was received, keep the original key and payload for reconciliation.

Moving existing personal domains

Organization setup/customer creation alone moves nothing. Migration is a separate owner-authorized, readiness-checked workflow. Select/create the intended customer, attach the selected domain, then verify its customer-scoped listing, permissions, expiry and DNS. Do not re-register it. Unmoved personal domains keep their existing path; moved domains need the appropriate organization credential/customer context. There is no automatic whole-account migration or blanket API compatibility promise.