Skip to content

Knowledgebase

Request a settlement refund and track its decision separately from domain status

domain-nexus, development

A refund API request starts a reviewable billing workflow against an eligible settled transaction. It does not itself prove approval, a wallet credit or money returned through an external payment gateway. Keep the refund decision separate from the domain's lifecycle status.

01 Prepare the settlement evidence

Method Resource Scope Idempotency-Key
GET /v2/refunds wallet:read Not required by this route
POST /v2/refunds refunds:write Required
  1. Find the original order and settlement owned by the authenticated account.
  2. Confirm the original payer, currency, settled amount and any previous refunds.
  3. Choose an amount within the remaining refundable settlement and a supported method: wallet_credit, invoice_refund or manual.
  4. Submit settlement_id, decimal amount and a useful reason, with the required HTTP idempotency header.
  5. Save the returned refund ID and follow its recorded state in the refund collection and related billing evidence.

An illustrative body is:

Structured data example
{
  "settlement_id": "OWNED_SETTLEMENT_ID",
  "amount": "10.00",
  "method": "wallet_credit",
  "reason_code": "customer_request",
  "reason_detail": "Review against the original order and settlement."
}

The amount is an example, not a refund entitlement or current price. Use the actual remaining eligible amount and applicable service terms.

Is the body idempotency_key enough?

No. The optional refund workflow reference in the JSON body does not replace the route's required Idempotency-Key HTTP header. Retain the original request identity for an identical retry.

Does a refund cancel the domain?

No. A billing adjustment and a registry action are separate. A refund request should never be used as evidence that a domain was deleted, released or transferred away.

If the external payment status is unclear, reconcile the original settlement and gateway evidence before issuing another request. Do not alter wallet ledger rows or manually mark a gateway payment complete to clear a discrepancy. Provide authorised billing support with the settlement, order and refund references so it can review the actual remaining balance and decision.

Was this answer helpful?

Need a little more help?

Our support team can help you find the next step.

Contact support