# Buy a domain through instant purchase (https://developer.godaddy.com/en/docs/api-users/buy-a-domain/instant-purchase)

***

title: Buy a domain through instant purchase
description: End-to-end workflow — confirm your payment method, preview all-in pricing, and purchase closeout auction domains.
agentNotes:
permissions: \["Aftermarket", "Payment Profile"]
scopes: \[]
rateLimit: "Rate-limited per credential per window. Go to /docs/api-users/rate-limits for current values."
idempotent: false
destructive: true
failureRecovery: "Check per-domain status in 207 responses. Domains with status FAILED are safe to retry. Do not re-submit domains that already returned status SUCCESS. If totalPrice changed between preview and purchase, the domain fails with PRICE\_MISMATCH — re-run the preview step to get the updated price before retrying."
related:
apis:

* title: "Instant Purchase reference"
  href: "/docs/references/rest/auctions/instant-purchase"
  guides:
* title: "About the Auctions API"
  href: "/docs/api-users/auctions"
* title: "Set up a payment profile"
  href: "/docs/api-users/payment-profile"
* title: "Place bids on auction listings"
  href: "/docs/api-users/buy-a-domain/bidding"

***

## Overview

Instant purchase lets you buy closeout (Buy Now) auction domains at a fixed price without bidding. The workflow is synchronous. You preview the all-in cost, then execute the purchase. Domains fulfillment begins immediately on success. The following diagram shows the workflow for instant purchase:

Instant purchase charges your payment profile immediately and is not reversible. Always run the preview step first and verify `totalPrice` before executing.

The following article provides a workflow for buying domains through instant purchase.

## Prerequisites

The following prerequisites are required before you can buy domains through instant purchase:

* a GoDaddy account with a [payment profile](https://developer.godaddy.com/docs/api-users/payment-profile) configured
* a [legacy API key](https://classic-developer.godaddy.com/keys), exported as `GODADDY_API_KEY` in your environment
* one or more domain names that have active closeout auction listings on GoDaddy Auctions

## Get eligible payment profiles

The following procedure retrieves the payment profiles on your account that are eligible for instant purchase. Note the `paymentProfileId` (you'll use it to [execute the purchase](#execute-purchase).

* List eligible payment profiles:

  ```bash
  curl -s "https://api.godaddy.com/v1/customers/MY/paymentProfiles" \
    -H "Authorization: sso-key $GODADDY_API_KEY"
  ```

The following is an example response:

```json
{
  "paymentProfiles": [
    {
      "paymentProfileId": 377693,
      "currencyId": "USD",
      "label": "6341",
      "category": "CREDIT_CARD",
      "status": "ACTIVE",
      "subCategory": "Visa",
      "expMonth": 7,
      "expYear": 2030
    }
  ]
}
```

Only `ACTIVE` profiles are returned. If the list is empty, go to [Set up a payment profile](https://developer.godaddy.com/docs/api-users/payment-profile) before continuing.

## Preview pricing

The following procedure retrieves the all-in price for up to 10 domains before you commit to purchasing. You can preview and purchase up to 10 domains per request.

`totalPrice` includes the auction price, renewal or transfer fee, ICANN fee, and applicable taxes. All prices are in micro-units. Divide by `1,000,000` for the dollar amount (for example, `61990000` = $61.99).

* Request a pricing preview:

  ```bash
  curl -s -X POST "https://api.godaddy.com/v1/customers/MY/auctions/purchases/preview" \
    -H "Authorization: sso-key $GODADDY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "domains": ["example.com", "mybrand.net"]
    }'
  ```

The following is an example response (207 — one domain priced, one not found):

```json
{
  "currencyId": "USD",
  "auctions": [
    {
      "domainName": "example.com",
      "status": "SUCCESS",
      "auctionId": 690467872,
      "auctionPrice": 50000000,
      "totalPrice": 61990000
    },
    {
      "domainName": "mybrand.net",
      "status": "FAILED",
      "failureReason": "AUCTION_NOT_FOUND"
    }
  ]
}
```

Only pass domains with `status: "SUCCESS"` to the purchase step. Note the `totalPrice` for each. You'll need the exact value to [execute the purchase](#execute-purchase).

## Execute purchase

The following procedure purchases the domains you previewed. Pass the `totalPrice` from the preview pricing step exactly. If the price has changed since the preview, the domain fails with `PRICE_MISMATCH` and you'll need to re-run the preview.

This step charges your payment profile. Verify all domain names and prices before submitting.

* Execute the purchase:

  ```bash
  curl -s -X POST "https://api.godaddy.com/v1/customers/MY/auctions/purchases" \
    -H "Authorization: sso-key $GODADDY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "currencyId": "USD",
      "paymentProfileId": 377693,
      "domains": [
        {
          "domainName": "example.com",
          "totalPrice": 61990000,
          "acceptTos": true
        }
      ]
    }'
  ```

`paymentProfileId` is optional. If omitted, the API charges the customer's most recently used supported payment method.

The following is an example response (200 — all purchased):

```json
{
  "currencyId": "USD",
  "orderDetails": {
    "orderId": "4028591294"
  },
  "auctions": [
    {
      "domainName": "example.com",
      "status": "SUCCESS",
      "auctionId": 690467872,
      "totalPrice": 61990000
    }
  ]
}
```

If the response is 207, inspect each domain's `status` and `failureReason`. Domains with `status: "SUCCESS"` were purchased and charged. Domains with `status: "FAILED"` wern't charged.

## Error reference

| HTTP status      | Error code                    | Cause                                                                           | Note                        |
| ---------------- | ----------------------------- | ------------------------------------------------------------------------------- | --------------------------- |
| `400`            | `NO_ELIGIBLE_PAYMENT_PROFILE` | No active payment profiles found, or specified `paymentProfileId` not eligible. |                             |
| `400`            | `UNSUPPORTED_CURRENCY`        | The requested `currencyId` isn't supported.                                     |                             |
| `422`            | `PAYMENT_FAILED`              | Payment profile was declined.                                                   |                             |
| `207` per-domain | `AUCTION_NOT_FOUND`           | Domain doesn't have an active closeout auction.                                 |                             |
| `207` per-domain | `PRICE_MISMATCH`              | `totalPrice` doesn't match current pricing.                                     | Re-run preview and resubmit |
| `207` per-domain | `PRICING_UNAVAILABLE`         | Pricing couldn't be retrieved for this domain.                                  |                             |
| `207` per-domain | `TOS_NOT_ACCEPTED`            | `acceptTos` wasn't set to `true`.                                               |                             |
| `401`            | —                             | Missing or invalid API key.                                                     |                             |
| `403`            | —                             | API key doesn't have access to this customer's account.                         |                             |
| `429`            | —                             | Rate limit exceeded.                                                            |                             |