# eBay (/docs/ebay)



eBay [#ebay]

eBay listings and their sellers behind the same unified envelope and canonical commerce schema
as Amazon, Walmart, Target and Google Shopping, so one parser handles all of them. 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/...`

<Callout>
  `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.
</Callout>

Getting started [#getting-started]

Every endpoint is a `GET` with query parameters and an `x-api-key` header. Listings are
identified by **item id**, the number in a listing URL — `ebay.com/itm/327256602116` is item id
`327256602116`. Every row returned by search carries one.

```bash
# 1. Scan the marketplace, sixty listings per page
curl "https://www.socialcrawl.dev/v1/ebay/search?query=airpods%20pro&sort_by=price_low&condition=new" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 2. One listing in full, including who is selling it
curl "https://www.socialcrawl.dev/v1/ebay/product?product_id=327256602116" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

Both endpoints are 5 credits.

Search [#search]

`GET /v1/ebay/search` returns sixty listings per page — more rows per call than any other
listing endpoint here — each with the item id, title, price, condition, image, seller handle,
feedback score and units sold. That density is what makes eBay the cheapest marketplace on this
API to scan at depth.

The filters map directly onto eBay's own refinements:

* `sort_by` — `best_match` (default), `price_low`, `price_high`, `newly_listed`,
  `ending_soonest`
* `condition` — `new`, `opened_box`, `refurbished`, `used`
* `buying_format` — `auction`, `buy_it_now`, `accepts_offers`
* `min_price` / `max_price` — a price band
* `show_only` — `sold_items` (ended in a sale), `completed_items` (all ended
  listings), `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 [#sold-and-completed-listings]

eBay's public sold search now 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
curl "https://www.socialcrawl.dev/v1/ebay/search?query=airpods%20pro&show_only=sold_items" \
  -H "x-api-key: $SOCIALCRAWL_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 [#listing-detail]

`GET /v1/ebay/product?product_id=…` returns the listing in full — title, brand, price,
condition, MPN and UPC, quantity available, and watcher count. What sets it apart from the other
commerce platforms here is the **seller** block: feedback score, top-rated status, join date,
and four detailed sub-ratings. When you are evaluating who is selling as much as what is being
sold, this is the endpoint that answers it.

Marketplaces [#marketplaces]

`country` selects the national marketplace, and it sets the listing pool, the language and the
currency together — not 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. Pass the same `country` on `product` that you used on `search`, because an
item id resolves within its own marketplace.

Endpoints [#endpoints]

<PlatformEndpoints platform="ebay" />

Read this before you build [#read-this-before-you-build]

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

**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, not a stable set.

Notes [#notes]

* All endpoints use `GET` with query parameters
* Authentication via the `x-api-key` header
* Responses follow the unified SocialCrawl schema, shared with the other commerce platforms
* Search is page-paginated starting at `page=1`
* Prices are returned in the marketplace's own currency