About the Auctions API
View as MarkdownHow the Auctions API is structured, what it covers, and how the core resources relate to each other.
https://developer.godaddy.com/llms.mdx/api-users/auctions for the full, unmodified source before proceeding.Overview
The Auctions API covers two ways to acquire expiring domains on the GoDaddy platform: bidding on expiring auctions and instant purchase of closeouts (Buy Now) auctions at a fixed price. Both capabilities use v1 endpoints and require a customerId path parameter. You can use the MY alias to target the authenticated customer's own account.
How the API is structured
The following sections describe how the Auctions API is structured.
Single version namespace
All endpoints are located under /v1/customers/{customerId}/.... Authenticate with a legacy API key and pass the customer's ID (or MY) in the path.
207 partial success
Both the bidding and instant purchase endpoints accept arrays of items and process each independently. When some items succeed and others fail, the API returns 207 Multi-Status, not a 4xx error. Inspect each item's status field individually:
status: "SUCCESS": the item was processed successfullystatus: "FAILED": checkfailureReasonfor the machine-readable cause
A 200 means every item in the array succeeded. A 207 means at least one failed. Failed items are safe to retry. Don't re-submit items that already returned SUCCESS.
Pricing in micro-units
All monetary amounts are integers in micro-units (amount × 10⁶). For USD:
| Micro-units | Dollar amount |
|---|---|
50000000 | $50.00 |
61990000 | $61.99 |
100000000 | $100.00 |
Divide by 1,000,000 to get the human-readable price.
Core resources
The following sections describe the core resources of the Auctions API.
Listing
An auctions listing represents a domain available for purchase on the GoDaddy Auctions marketplace. Listings have a listingId (integer) used when placing bids, and a domainName used for instant purchase and availability checks.
Payment profile
A payment profile is a saved payment method eligible for API-initiated purchases. Only ACTIVE profiles are returned by GET /v1/customers/{customerId}/paymentProfiles. Credit cards and prepaid methods are supported.
Bid
A bid is a price offer placed on an expiring auction listing. Bid amounts are in USD micro-units. The response indicates whether you're the highest bidder and provides a bidId for tracking.
Purchase
A purchase represents a completed instant purchase transaction. The response includes an orderId and per-domain results. totalPrice is the amount charged, in micro-units.
Lifecycle of an expiring domain
Most auctions listings aren't deliberate seller listings — they're domains that lapsed through GoDaddy's or a partner registrar's standard expiration process. Where a domain sits in that timeline determines which capability applies: bidding while it's an expiring auction, instant purchase once it moves to a closeout (Buy Now). The following diagram shows that path:
| Phase | Timing | What it means for this API |
|---|---|---|
| Grace period | Day 0–18 | Not listed. Domain isn't reachable through Auctions yet. |
| Redemption period | Day 18–26 | Still not listed. The original owner can recover it directly, outside this API. |
| Expiring Auction | Day 26–36 | The domain gets a listingId and becomes visible to Check listing availability. Use bidding to compete for it. |
| Closeout Auction | Day 36–41 | If nobody bid on the expiring auction, the listing becomes a closeout auction. Use instant purchase to buy it outright. |
| Removed from account | Day 72 | Point of no return for the original owner. The registry eventually releases the domain for new registration outside Auctions. |
Timing varies by TLD and registrar
These day counts follow GoDaddy's general gTLD expiration policy. ccTLDs and some other TLDs run different timelines. Go to the domain lifecycle for the broader (non-auction) picture, and GoDaddy's standard domain expiration timeline for the full day-by-day breakdown.
Listings can disappear before close
For domains that lapsed directly with GoDaddy, the original owner loses the ability to redeem at Day 30. For domains that came through a partner registrar, that cutoff depends on GoDaddy's contractual agreement with that registrar. Redemption might still be possible past Day 30. Either way, a listingId from an earlier availability check isn't guaranteed to still be valid. Re-check availability before bidding if time has passed, and treat a LISTING_NOT_FOUND error the same way you'd treat any other retryable 207 failure.
Bidding vs. instant purchase
The following table compares bidding and instant purchase:
| Bidding | Instant purchase | |
|---|---|---|
| Auction type | Open English auction | Closeout (Buy Now fixed-price) |
| Outcome | Win or lose at auction close | Immediate, domain fulfills on success |
| Price | Your bid in USD micro-units | All-in total: auction price + renewal/transfer + ICANN fee + taxes |
| Payment | Charged on auction win | Charged at time of purchase |
| Reversible | Not reversible, charges are due if auction is won | Not reversible, charges are immediate |
Operations by task
The following table lists the operations by task:
| Task | Endpoint | Workflow |
|---|---|---|
| Check listing availability | POST /v1/customers/{customerId}/aftermarket/listings/available | Place bids |
| Place bids | POST /v1/customers/{customerId}/aftermarket/listings/bids | Place bids |
| Get eligible payment profiles | GET /v1/customers/{customerId}/paymentProfiles | Buy through instant purchase |
| Preview instant purchase pricing | POST /v1/customers/{customerId}/auctions/purchases/preview | Buy through instant purchase |
| Execute instant purchase | POST /v1/customers/{customerId}/auctions/purchases | Buy through instant purchase |
Related
Last updated on
How is this guide?