Skip to main content

​
Steps to Refund a Domain

Use this flow to delete eligible domains and security products during the Add Grace Period (AGP) and automatically issue refunds for the associated order items. This endpoint:
  • Enforces ICANN AGP delete limits
  • Applies name.com and reseller-specific refund thresholds
  • Supports domain registrations and security product add-ons only
Refunds are issued to the original payment method on file, with a fallback to account credit if the payment method is unavailable or fails. You can check your order history in account settings at name.com for this information.

​
Supported Products

Refunds are supported for the below purchase types:
  • registration
  • whois_privacy
All other product types are not eligible. Please note: if a registration refund is requested, associated privacy product will also be deleted/refunded

​
High-Level Flow

  1. Use the List Orders or Get Order endpoints to verify refund eligibility and retrieve the order ID and order item ID(s) that can be refunded.
  2. Request the refund using the Refunds endpoint
After submitting a refund request, retrieve the order using the Get Order endpoint to review the updated order details. Once an order item has been officially refunded, its status will be returned as:

​
Step 1: Check Refund Eligibility (List Orders)

Use the List Orders or Get Order endpoints immediately before attempting a refund to validate eligibility and reduce failed refund attempts. If isRefundableis true, you can retrieve the orderIDand associated orderItemIdsrequired for the Refunds request.

​
How to use

  • You can filter listOrders results by:
    • domainName
    • createDate
    • type(e.g. registration,whois_privacy)
    • orderStatus
  • Check the isRefundablefield on each order item. If true, you can initiate a refund via the Refunds endpoint. This field already accounts for ICANN AGP limits, reseller-level thresholds, and name.com refund policies.
Important: Refund eligibility is time-sensitive: Even if isRefundable is true, eligibility may change between this check and the Refund request (for example, if AGP timing expires or refund thresholds are exceeded). The Refunds endpoint is the source of truth and may still reject the request.

​
Step 2: Request a Refund (Refunds Endpoint)

Use the Refunds endpoint to delete the domain(s) and issue refunds for eligible order items.
Send an X-Idempotency-Key with your refund request. Retrying the same request with the same key will not trigger duplicate deletions or refunds.

​
Request Requirements

  • Accepts a JSON body with:
    • orderId (required)
    • orderItemIds (required array, one or more items)
  • Only one orderIdmay be provided per request
  • Multiple orderItemIdsare allowed as long as they belong to the same order
  • Supported product types only:
    • registration
    • whois_privacy
  • If WHOIS privacy was purchased on a domain and the domain is refunded, both will be refunded. It can be an explicit or non-explicit request. (you can submit one item id or two item ids)
Example response: Order with a refunded domain and its associated WHOIS privacy add-on

​
Full endpoint reference

For the full request/response schema (including errors), see Refunds: Process Refund.