# eBay API — search active listings, research sold prices, and fetch full item detail across 13 eBay marketplaces (no account required)

> active-listing search by `query` -> results[]{item_id,title,price{value,currency},condition,buying_format,shipping,location,image,url,sold_count?,catalog_rating?}. Filters: domain(com/co.uk/de/...), page, max_results(<=240/page), sort(best_match|newly_listed|ending_soonest|price_low|price_high), condition(new|used|refurbished|open_box|for_parts), category, buy_it_now, auction. seller is item-page-only.
> ReefAPI engine `ebay` · 7 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/ebay/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /ebay/v1/search — 1 credit
active-listing search by `query` -> results[]{item_id,title,price{value,currency},condition,buying_format,shipping,location,image,url,sold_count?,catalog_rating?}. Filters: domain(com/co.uk/de/...), page, max_results(<=240/page), sort(best_match|newly_listed|ending_soonest|price_low|price_high), condition(new|used|refurbished|open_box|for_parts), category, buy_it_now, auction. seller is item-page-only.

**Parameters:**
- `query` (string, required) — What to search for (item keywords).
- `sort` (enum, optional, default "best_match") — Result ordering. [one of: best_match, newly_listed, ending_soonest, price_low, price_high, price_asc, price_desc]
- `condition` (enum, optional) — Only items in this condition (empty = all conditions). [one of: new, open_box, refurbished, used, for_parts]
- `category` (string, optional) — eBay category ID to narrow results — the number in an eBay category URL (e.g. 9355 = Cell Phones & Smartphones). Use the `categories` action to look an ID up by name. Empty = all.
- `buy_it_now` (boolean, optional, default false) — Only fixed-price (Buy It Now) listings.
- `auction` (boolean, optional, default false) — Only auction listings.
- `price_min` (number, optional) — Minimum price (eBay _udlo), in the marketplace's currency.
- `price_max` (number, optional) — Maximum price (eBay _udhi), in the marketplace's currency.
- `free_shipping` (boolean, optional, default false) — Only listings with free shipping.
- `returns_accepted` (boolean, optional, default false) — Only listings that accept returns.
- `best_offer` (boolean, optional, default false) — Only listings that accept Best Offers.
- `location` (enum, optional) — Restrict by item location. [one of: us, worldwide, north_america]
- `domain` (enum, optional, default "com") — Which eBay site to query (sets currency and local listings). Dropdown = the 13 live-verified sites; other eBay country sites (e.g. com.sg, com.hk) are also accepted. [one of: com, co.uk, de, com.au, ca, fr, it, es, nl, at, ch, ie, pl]
- `page` (integer, optional, default 1) — Page number (easy paging: 1, 2, 3…).
- `max_results` (integer, optional, default 60) — How many results to return (1–240 per page; larger values are capped at 240).

**Returns:** results[]{item_id, title, price{value,currency}, condition, buying_format, shipping, location, image, url} (meta.pagination for paging)

**Example request body:**
```json
{
  "query": "iphone 13 pro"
}
```

### POST /ebay/v1/sold_search — 2 credits
⭐SOLD/completed search by `query` (LH_Sold=1&LH_Complete=1, bare, NOT login-gated) -> results[]{...,sold_price{value,currency},sold_date} + price_stats{count,min,max,avg,median,stdDev,p10/p25/p75/p90,recommendedPrice(IQR-trimmed),outliers_removed,per_condition{bucket:{count,median,avg,min,max}},velocity{sales_per_day,days_to_sell,recent_sales_per_day,sales_last_7d/30d,span_days},trend{direction,slope_per_day,pct_change}} — ALL derived from the sold-array+sold_date, NO extra fetch (AI-free comps math). Same filters as search. The price-research moat.

**Parameters:**
- `query` (string, required) — What to search for (item keywords).
- `condition` (enum, optional) — Only items in this condition (empty = all conditions). [one of: new, open_box, refurbished, used, for_parts]
- `category` (string, optional) — eBay category ID to narrow results — the number in an eBay category URL (e.g. 9355 = Cell Phones & Smartphones). Use the `categories` action to look an ID up by name. Empty = all.
- `price_min` (number, optional) — Minimum price (eBay _udlo), in the marketplace's currency.
- `price_max` (number, optional) — Maximum price (eBay _udhi), in the marketplace's currency.
- `free_shipping` (boolean, optional, default false) — Only listings with free shipping.
- `returns_accepted` (boolean, optional, default false) — Only listings that accept returns.
- `best_offer` (boolean, optional, default false) — Only listings that accept Best Offers.
- `location` (enum, optional) — Restrict by item location. [one of: us, worldwide, north_america]
- `domain` (enum, optional, default "com") — Which eBay site to query (sets currency and local listings). Dropdown = the 13 live-verified sites; other eBay country sites (e.g. com.sg, com.hk) are also accepted. [one of: com, co.uk, de, com.au, ca, fr, it, es, nl, at, ch, ie, pl]
- `page` (integer, optional, default 1) — Page number (easy paging: 1, 2, 3…).
- `max_results` (integer, optional, default 60) — How many results to return (1–240 per page; larger values are capped at 240).

**Returns:** results[]{item_id, title, sold_price{value,currency}, sold_date, condition, url, image} + price_stats{count, min, max, avg, median, stdDev, p10/p25/p75/p90, recommendedPrice, per_condition, velocity, trend} (meta.pagination for paging)

**Example request body:**
```json
{
  "query": "iphone 13 pro"
}
```

### POST /ebay/v1/item_detail — 2 credits
Full eBay item detail by item_id or listing URL: title, price, list price, currency, condition, availability, brand, model, MPN, images, category path, item specifics, seller (name, feedback score, review count), shipping terms, return policy, PLUS auction fields (bids, current_bid, time_left, end_time), watchers, quantity_available/quantity_sold, best_offer flag, and multi-variation SKUs (variations[]{dimension, values[]{value, out_of_stock}}). Set include_description=1 to inline the full seller description text.

**Parameters:**
- `item_id` (string, optional) — eBay item number — the digits in the listing URL after /itm/. Provide item_id OR url (one of the two is required).
- `url` (string, optional) — Full eBay listing URL — alternative to item_id.
- `include_description` (boolean, optional, default false) — Also fetch and inline the full seller description text (one extra request; off by default for speed).
- `domain` (enum, optional, default "com") — Which eBay site to query (sets currency and local listings). Dropdown = the 13 live-verified sites; other eBay country sites (e.g. com.sg, com.hk) are also accepted. [one of: com, co.uk, de, com.au, ca, fr, it, es, nl, at, ch, ie, pl]

**Returns:** item{item_id, title, price{value,currency}, list_price, condition, availability, brand, model, mpn, images[], category_path[], item_specifics{}, seller{name, feedback_pct, feedback_count}, shipping, return_policy, url, bids?, current_bid?, time_left?, end_time?, watchers?, quantity_available?, quantity_sold?, best_offer, variations?[], description?}

### POST /ebay/v1/seller_items — 2 credits
All active listings in a seller's storefront by `seller` username (eBay _ssn) -> results[]{item_id,title,price{value,currency},condition,buying_format,shipping,location,image,url}. Same card shape + filters/pagination as `search`. Use to scan a competitor's full catalog. Page-native paging via meta.pagination.

**Parameters:**
- `seller` (string, required) — eBay seller username (store/usr name) — the handle in /usr/{seller} or the 'Sold by' link on a listing.
- `sort` (enum, optional, default "best_match") — Result ordering. [one of: best_match, newly_listed, ending_soonest, price_low, price_high]
- `condition` (enum, optional) — Only items in this condition (empty = all conditions). [one of: new, open_box, refurbished, used, for_parts]
- `category` (string, optional) — eBay category ID to narrow results — the number in an eBay category URL (e.g. 9355 = Cell Phones & Smartphones). Use the `categories` action to look an ID up by name. Empty = all.
- `price_min` (number, optional) — Minimum price (eBay _udlo), in the marketplace's currency.
- `price_max` (number, optional) — Maximum price (eBay _udhi), in the marketplace's currency.
- `free_shipping` (boolean, optional, default false) — Only listings with free shipping.
- `returns_accepted` (boolean, optional, default false) — Only listings that accept returns.
- `best_offer` (boolean, optional, default false) — Only listings that accept Best Offers.
- `location` (enum, optional) — Restrict by item location. [one of: us, worldwide, north_america]
- `domain` (enum, optional, default "com") — Which eBay site to query (sets currency and local listings). Dropdown = the 13 live-verified sites; other eBay country sites (e.g. com.sg, com.hk) are also accepted. [one of: com, co.uk, de, com.au, ca, fr, it, es, nl, at, ch, ie, pl]
- `page` (integer, optional, default 1) — Page number (easy paging: 1, 2, 3…).
- `max_results` (integer, optional, default 60) — How many results to return (1–240 per page; larger values are capped at 240).

**Returns:** results[]{item_id, title, price{value,currency}, condition, buying_format, shipping, location, image, url} (meta.pagination for paging)

### POST /ebay/v1/seller_profile — 3 credits
Seller reputation by `seller` username -> seller_profile{store_name, feedback_score, feedback_positive_pct, positive_pct_12mo, items_sold_display, followers_display, member_since, location, business_seller, top_rated, feedback_ratings{positive/neutral/negative:{m1,m6,m12}}}. From the public storefront + feedback pages (logged-out, no account).

**Parameters:**
- `seller` (string, required) — eBay seller username (store/usr name) — the handle in /usr/{seller} or the 'Sold by' link on a listing.
- `domain` (enum, optional, default "com") — Which eBay site to query (sets currency and local listings). Dropdown = the 13 live-verified sites; other eBay country sites (e.g. com.sg, com.hk) are also accepted. [one of: com, co.uk, de, com.au, ca, fr, it, es, nl, at, ch, ie, pl]

**Returns:** seller_profile{store_name, feedback_score, feedback_positive_pct, positive_pct_12mo, items_sold_display, followers_display, member_since, location, business_seller, top_rated, feedback_ratings{}}

### POST /ebay/v1/deals — 1 credit
eBay Daily Deals grid (/deals) -> results[]{item_id,title,price{value,currency},was_price{value,currency},shipping,deal_badge,image,url}. Current promoted discounts site-wide for the marketplace. No query needed.

**Parameters:**
- `domain` (enum, optional, default "com") — Which eBay site to query (sets currency and local listings). Dropdown = the 13 live-verified sites; other eBay country sites (e.g. com.sg, com.hk) are also accepted. [one of: com, co.uk, de, com.au, ca, fr, it, es, nl, at, ch, ie, pl]
- `max_results` (integer, optional, default 60) — How many results to return (1–240 per page; larger values are capped at 240).

**Returns:** results[]{item_id, title, price{value,currency}, was_price{value,currency}, shipping, deal_badge, image, url}

### POST /ebay/v1/categories — 1 credit
eBay category tree / ID lookup (/n/all-categories) -> categories[]{category_id,name,slug} + groups[] (top-level departments). Pass `query` to filter by name so you can resolve a category name (e.g. 'cell phones') to the numeric ID used by search's `category` param — no need to know '9355' in advance.

**Parameters:**
- `query` (string, optional) — Filter categories by name/slug substring (case-insensitive). Empty = the full top-level tree.
- `domain` (enum, optional, default "com") — Which eBay site to query (sets currency and local listings). Dropdown = the 13 live-verified sites; other eBay country sites (e.g. com.sg, com.hk) are also accepted. [one of: com, co.uk, de, com.au, ca, fr, it, es, nl, at, ch, ie, pl]
- `max_results` (integer, optional, default 60) — How many results to return (1–240 per page; larger values are capped at 240).

**Returns:** categories[]{category_id, name, slug}, groups[]

## More
- Try it live, no code: https://reefapi.com/playground?engine=ebay
- Human docs page: https://reefapi.com/docs/ebay
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt