---
title: "Bid on the Featured spot"
method: POST
path: "/api/feature"
tags: ["Billing"]
---

# Bid on the Featured spot

`POST /api/feature`

## Request

- Base URL: `https://curlship.com`
- URL: `https://curlship.com/api/feature`
- Auth: none declared

Returns a hosted checkout URL for a Featured bid. The listing must already exist; its registered email gets billed. `amount_usd` is optional and defaults to the current minimum (holder's price + $1, or $50 with no holder); a lower bid is refused with 409. Pay and the spot is yours — always dofollow, no subscription — until someone outbids you. **No refund when outbid**: that is the game. Rate limit: 30 checkout requests/hour per IP.

## Request body

- object
  - `url` string, uri, required
  - `amount_usd` number: Your bid in USD, whole cents at most. Omit to bid the current minimum. Ceiling: $100,000.

## Response `200`

Checkout URL created

- object
  - `ok` boolean
  - `checkout_url` string, uri
  - `amount_usd` number
  - `amount_cents` integer
  - `message` string

## Other responses

- `400`: Unreadable URL, non-numeric amount, or a bid above the $100,000 ceiling
- `404`: Listing not found
- `409`: Bid below the current minimum (the response carries required_usd and current_usd), or the listing is not active
- `429`: Rate limit exceeded. Retry-After is the wait in seconds. RateLimit-Policy names the window that was hit. RateLimit repeats that name with r=0 and t equal to Retry-After. Windows: submit 10 per 3600s, verify 30 per 3600s, checkout 30 per 3600s, edit 5 per 3600s per IP, edit-listing 3 per 86400s per listing.
- `503`: Featured product not configured

---

[API](https://skmtc.dev/curlship/apis/curlship-api.md) · [All operations](https://skmtc.dev/curlship/apis/curlship-api/llms.txt) · [OpenAPI document](https://skmtc.dev/curlship/apis/curlship-api/revisions/96fedc05adda?raw)