# eBay (/docs/ebay)

eBay listing search across nineteen marketplaces and full listing detail with seller reputation, in the shared commerce schema

eBay listings and their sellers behind the same canonical commerce schema as Amazon, Walmart, Target and Google Shopping. Two endpoints: a deep keyword search across any of nineteen national marketplaces, and a full listing record that carries the seller's reputation alongside the item.

Base URL: `/v1/ebay/...`

Listings are keyed on the **item id**, the number in a listing URL. In `ebay.com/itm/327256602116` the item id is `327256602116`, and every search row carries one.

  `min_price` and `max_price` are applied by eBay, not by us, so the boundary
  rows are approximate. Filter on `product.price.current` in the response when
  you need a hard bound.

## Quickstart

### Scan the marketplace

`search` returns 60 listings a page, more rows per call than any other listing endpoint here, which is what makes eBay the cheapest marketplace on this API to scan at depth.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/ebay/search?query=airpods%20pro&sort_by=price_low&condition=new" \
  -H "x-api-key: YOUR_API_KEY"
```

### Read one listing, including who is selling it

Pass the same `country` you searched with, because an item id resolves within its own marketplace.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/ebay/product?product_id=327256602116" \
  -H "x-api-key: YOUR_API_KEY"
```

## Search

| Endpoint              | Credits | What it returns                                                                                                                                                            | Key parameters                                                                                                                   |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `GET /v1/ebay/search` | 5       | 60 listings a page with item id, title, price, original price, currency, condition, image, seller handle, feedback score and count, units sold, buying format, listing URL | `query` (required), `country`, `page`, `sort_by`, `condition`, `buying_format`, `show_only`, `min_price`, `max_price`, `aspects` |

The filters map directly onto eBay's own refinements:

- `sort_by`: `best_match` (default), `price_low`, `price_high`, `newly_listed`, `ending_soonest`
- `condition`: `new`, `refurbished`, `used`
- `buying_format`: `auction`, `buy_it_now`, `accepts_offers`
- `show_only`: `sold_items`, `completed_items`, `free_shipping`, or a comma-joined pair such as `sold_items,completed_items`
- `aspects`: a category-specific item aspect from a previous response, such as `Brand:Apple`

### Sold and completed listings

eBay's public sold search requires a signed-in browser session. This endpoint does not: you never pass an eBay login, cookie, or session. Call `show_only=sold_items` and read the realised sale on `product.price.current` and the sold date on `product.ext.sold_at`.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/ebay/search?query=airpods%20pro&show_only=sold_items" \
  -H "x-api-key: YOUR_API_KEY"
```

`completed_items` returns every ended listing, including those that did not sell. Combine the two tokens when you want that full ended set with sold dates still stamped on the rows that sold. eBay itself only exposes about ninety days of sold history through search.

## Listing detail

| Endpoint               | Credits | What it returns                                                                                                                                             | Key parameters                     |
| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `GET /v1/ebay/product` | 5       | Title, brand, price, original price, currency, condition and condition notes, MPN and UPC, units available, units sold, watchers, and the full seller block | `product_id` (required), `country` |

The seller block is the reason to call this rather than search. `product.ext.seller_reputation` carries lifetime feedback percentage and count, top-rated status, items sold, join date, and four detailed sub-ratings for description accuracy, shipping cost, shipping speed, and communication. When you are evaluating who is selling as much as what is being sold, this is the endpoint that answers it.

## Marketplaces

`country` selects the national marketplace, and it sets the listing pool, the language and the currency together rather than just a display preference. `US` (ebay.com) is the default. `GB`, `AU`, `CA`, `DE`, `FR`, `IT`, `ES`, `IE`, `AT`, `CH`, `NL`, `BE`, `PL`, `SG`, `MY`, `PH`, `HK` and `MX` are the rest.

## All endpoints

## Platform notes

**Price filters are approximate.** `min_price` and `max_price` are applied by eBay, not by us, and the boundary rows are not exact. Filter on `product.price.current` in the response if you need a hard bound.

**`image_urls` is null on listing detail.** eBay's detail response currently returns a corrupt image array, so the field nulls out rather than carrying a broken URL. Use the image on the matching search row, which is unaffected.

**There is no category-browse endpoint.** Unlike Target or Walmart, eBay's tree is not exposed here. Keyword search plus `aspects` refinement is the path from nothing to a set of item ids.

**Auction listings are moving targets.** A `buying_format=auction` row's price is the current bid, so a listing fetched twice legitimately reports two different numbers. Read `sort_by=ending_soonest` results as a snapshot rather than a stable set.

**Paginate until a page comes back empty.** eBay's own result total is an estimate that changes between pages, so it is not returned here. Search is page-paginated starting at `page=1`, and prices come back in the marketplace's own currency.

## Next steps

- [Pagination](/docs/pagination.md): The universal cursor, and how to walk a search to the end.
- [Credits](/docs/credits.md): What each tier costs, and which failures are refunded.
- [API reference](/docs/api-reference.md): Every eBay parameter and response field.
- [Amazon](/docs/amazon.md): The same shapes for amazon.com, plus competing seller offers.
- [Google Shopping](/docs/google_shopping.md): The cross-retailer view: every store selling one product.