Process Refund

Deletes eligible domains and security products during the Add Grace Period (AGP) and automatically issues refunds for the associated order items.

Eligibility Requirements

• Product Types: Only registration and whois_privacy product types are eligible for refunds.
• AGP Timing: Items must be within the Add Grace Period (typically 5 days from registration, varies by TLD).
• Order Ownership: All orderItemIds must belong to the specified orderId.

Refund Processing

Refunds are processed in the following order:

1. Domain deletion is attempted for each eligible order item
2. Upon successful deletion, the refund is issued
3. Refunds are sent to the original payment method on file
4. If the original payment method is unavailable, the refund is credited to the account balance

Idempotency

This endpoint supports idempotent requests via the X-Idempotency-Key header. If you retry a request with the same idempotency key, you will receive the same response as the original request. This is useful for safely retrying requests without risk of processing duplicate refunds.

POST /core/v1/refund

cURL

singleItem

curl --request POST \
  --url https://api.dev.name.com/core/v1/refund \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "orderId": 123456,
  "orderItemIds": [
    987654
  ]
}
'

200

successfulRefund

{
  "results": [
    {
      "orderId": 123456,
      "orderItemId": 987654,
      "orderItemStatus": "refunded",
      "refundAmount": 10.99,
      "message": "Domain successfully deleted and refund processed."
    }
  ],
  "totalRefundAmount": 10.99
}

Authorizations

Authorization · string · header · required

Authenticate via HTTP Basic with your account username and API token. Examples use an explicit 'Authorization: Basic <base64(username:token)>' header; 'curl -u username:token' is equivalent. For sandbox, append "-test" to your username and use your sandbox token on api.dev.name.com.

Headers

X-Idempotency-Key · string

A unique string (e.g., a UUID v4) to make the request idempotent. This key ensures that if the request is retried, the operation will not be performed multiple times. Subsequent requests with the same key will return the original result. Idempotency keys are valid for 12 hours.

Example:

"083910ef-04e4-4bd1-a0bf-3737fe005ca8"

Body

application/json

RefundRequest contains the order ID and array of order item IDs to be refunded.

RefundRequest contains the order and order items to be refunded. Only domain registrations and security products purchased within the Add Grace Period (AGP) are eligible for refunds.

orderId · integer<int32> · required

The unique identifier of the order containing the item(s) to be refunded. Use the List Orders endpoint to retrieve order IDs.

Example:

123456

orderItemIds · integer<int32>[] · required

An array of order item IDs to be refunded. All items must belong to the specified order. Use the List Orders endpoint to retrieve order item IDs.

Minimum array length: 1

Example:

[987654, 987655]

Response

200

application/json

Refund processed successfully. The response includes the detailed results for each refunded item.

RefundResponse contains the results of a refund operation, including the individual order item results. Refunds are issued to the original payment method on file. If the original payment method is unavailable, the refund will be credited to the account balance.

results · object[] · required

An array of refund results for each order item that was processed.

Minimum array length: 1

Show child attributes

totalRefundAmount · number<float> · required

The total amount refunded across all order items in USD.

Example:

21.98