# About the Auctions API (https://developer.godaddy.com/en/docs/api-users/auctions) *** title: About the Auctions API description: How the Auctions API is structured, what it covers, and how the core resources relate to each other. related: concepts: * title: "How GoDaddy APIs work" href: "/docs/api-users/concepts/how-godaddy-apis-work" guides: * title: "Buy a closeout auction via instant purchase" href: "/docs/api-users/buy-a-domain/instant-purchase" * title: "Place bids on expiring auctions" href: "/docs/api-users/buy-a-domain/bidding" * title: "Set up a payment profile" href: "/docs/api-users/payment-profile" *** ## 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](https://classic-developer.godaddy.com/keys) 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 successfully * `status: "FAILED"`: check `failureReason` for 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](https://developer.godaddy.com/docs/api-users/buy-a-domain/bidding#check-listing-availability). Use [bidding](https://developer.godaddy.com/docs/api-users/buy-a-domain/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](https://developer.godaddy.com/docs/api-users/buy-a-domain/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. | These day counts follow GoDaddy's general gTLD expiration policy. ccTLDs and some other TLDs run different timelines. Go to [the domain lifecycle](https://developer.godaddy.com/docs/api-users/concepts/domain-management-concepts#the-domain-lifecycle) for the broader (non-auction) picture, and GoDaddy's [standard domain expiration timeline](https://www.godaddy.com/help/standard-domain-expiration-timeline-609) for the full day-by-day breakdown. 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](#207-partial-success). ## 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](https://developer.godaddy.com/docs/api-users/buy-a-domain/bidding) | | Place bids | `POST /v1/customers/{customerId}/aftermarket/listings/bids` | [Place bids](https://developer.godaddy.com/docs/api-users/buy-a-domain/bidding) | | Get eligible payment profiles | `GET /v1/customers/{customerId}/paymentProfiles` | [Buy through instant purchase](https://developer.godaddy.com/docs/api-users/buy-a-domain/instant-purchase) | | Preview instant purchase pricing | `POST /v1/customers/{customerId}/auctions/purchases/preview` | [Buy through instant purchase](https://developer.godaddy.com/docs/api-users/buy-a-domain/instant-purchase) | | Execute instant purchase | `POST /v1/customers/{customerId}/auctions/purchases` | [Buy through instant purchase](https://developer.godaddy.com/docs/api-users/buy-a-domain/instant-purchase) |