# eBay API guide



## Choose a eBay operation



Start with the object your task needs. The groups below use the current catalogue; open an endpoint to check accepted identifiers, filters, price and availability before retrieving.



### Products and categories



- [Get an eBay listing](https://www.monocrawl.com/docs/endpoints/ebay/product) — Look up one eBay listing by item id or ebay.com/itm URL: full price, condition, seller, item specifics, availability, shipping, returns, and ratings.



### Search and discovery



- [Search eBay listings](https://www.monocrawl.com/docs/endpoints/ebay/search) — Search live eBay listings by keyword: title, price, condition, seller, shipping, and thumbnails, with filters for price, condition, and buying format.



## Check fields and collection limits



Use the endpoint’s declared parameters and returned continuation. Filters from another platform do not automatically apply here. Preserve source identifiers, URLs and warnings; a successful page does not establish complete history. Published response schemas identify whether they come from a reviewed shaper or observed response shapes.



Agents can use `get_endpoint` for the current contract and `get_docs` with topic `platforms/ebay` to read this page. The [coverage guide](https://www.monocrawl.com/docs/data-availability) explains nulls and partial results, and the [production guide](https://www.monocrawl.com/docs/production-checklist) covers budgets and recovery.



## Endpoint reference

## ebay/product

`GET /v1/ebay/product`

Look up one eBay listing by item id or ebay.com/itm URL: full price, condition, seller, item specifics, availability, shipping, returns, and ratings.

*Get an eBay listing*

| Parameter | Required | Description |
| --- | --- | --- |
| `product_id` | yes | eBay item id: a numeric legacy id, a v1\|…\|… RESTful id, or an ebay.com/itm/ URL — e.g. `327256602116` |
| `country` | no | Marketplace: a country code (us, gb, de…) or a raw eBay marketplace id (EBAY_US). Default us. — e.g. `us` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `country`: Select the documented market or country filter. Read this endpoint’s country semantics; filtering and source request location can differ.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/ebay/product?product_id=327256602116" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [
    "example"
  ],
  "additional_image_urls": [
    "example"
  ],
  "adult_only": false,
  "aspects": [
    {
      "name": "example",
      "value": "example"
    }
  ],
  "availability_status": "example",
  "brand": "example",
  "buying_options": [
    "example"
  ],
  "category_id": "example",
  "category_path": "example",
  "condition": "example",
  "condition_id": "example",
  "epid": "example",
  "gtin": "example",
  "id": "example",
  "image_url": "https://example.com/example",
  "item_creation_date": "2026-09-01T12:00:00Z",
  "item_location": {
    "city": "example",
    "country": "example",
    "postal_code": "example",
    "state": "example"
  },
  "legacy_id": "example",
  "marketplace_id": "example",
  "mpn": "example",
  "price": {
    "currency": "example",
    "value": 0
  },
  "quantity_sold": 0,
  "rating": {
    "average": 0,
    "count": 0
  },
  "returns_accepted": false,
  "seller": {
    "feedback_percentage": 0,
    "feedback_score": 0,
    "username": "example"
  },
  "shipping": {
    "cost": {
      "currency": "example",
      "value": 0
    },
    "service": "example",
    "type": "example"
  },
  "short_description": "example",
  "title": "example",
  "top_rated": false,
  "url": "https://example.com/example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/ebay/product#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/ebay/product.json)


## ebay/search

`GET /v1/ebay/search`

Search live eBay listings by keyword: title, price, condition, seller, shipping, and thumbnails, with filters for price, condition, and buying format.

*Search eBay listings*

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Keywords to search listing titles for — e.g. `iphone 11` |
| `country` | no | Marketplace: a country code (us, gb, de, au, ca, fr…) or a raw eBay marketplace id (EBAY_US). Default us. — e.g. `us` |
| `page` | no | 1-based page number (mapped to offset = (page-1)*limit); use cursor to paginate reliably — e.g. `1` |
| `sort_by` | no | Best-effort sort: price_asc, price_desc, newest, or distance (unrecognized values are ignored) Accepted values: price, price_asc, price+shipping, -price, price_desc, newly_listed, newest, new, distance. Case, spaces, hyphens and underscores are interchangeable. — e.g. `price_asc` |
| `condition` | no | Item condition filter, comma-separated: new, used, refurbished, open_box, for_parts Accepted values (comma-separated): new, used, refurbished, open_box, for_parts, seller refurbished. Case, spaces, hyphens and underscores are interchangeable. — e.g. `new` |
| `buying_format` | no | Buying format filter, comma-separated: fixed_price, auction, best_offer, classified_ad Accepted values (comma-separated): fixed, fixed_price, buy_it_now, bin, auction, best_offer, classified, classified_ad. Case, spaces, hyphens and underscores are interchangeable. — e.g. `auction` |
| `show_only` | no | Extra filters, comma-separated: free_shipping, returns_accepted, authenticity_guarantee Accepted values (comma-separated): free_shipping, returns_accepted, authenticity_guarantee. Case, spaces, hyphens and underscores are interchangeable. — e.g. `free_shipping` |
| `min_price` | no | Minimum price in the marketplace currency — e.g. `50` |
| `max_price` | no | Maximum price in the marketplace currency — e.g. `500` |
| `aspects` | no | Raw eBay aspect_filter expression to narrow by item aspects — e.g. `Brand:{Apple}` |
| `cursor` | no | Opaque pagination cursor returned by the previous page (a stringified offset) — e.g. `25` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `country`: Select the documented market or country filter. Read this endpoint’s country semantics; filtering and source request location can differ.
- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 3 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/ebay/search?query=iphone%2011" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [
    "example"
  ],
  "count": 0,
  "cursor": null,
  "dropped": 0,
  "items": [
    {
      "adult_only": false,
      "bid_count": 0,
      "buying_options": [
        "example"
      ],
      "categories": [
        {}
      ],
      "condition": "example",
      "condition_id": "example",
      "current_bid_price": {
        "currency": "example",
        "value": 0
      },
      "epid": "example",
      "id": "example",
      "image_url": "https://example.com/example",
      "item_location": {
        "country": "example",
        "postal_code": "example"
      },
      "legacy_id": "example",
      "marketplace_id": "example",
      "price": {
        "currency": "example",
        "value": 0
      },
      "seller": {
        "feedback_percentage": 0,
        "feedback_score": 0,
        "username": "example"
      },
      "shipping": {
        "cost": {},
        "type": "example"
      },
      "thumbnail_url": "https://example.com/example",
      "title": "example",
      "url": "https://example.com/example"
    }
  ],
  "marketplace_id": "example",
  "query": "example",
  "total": 0
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/ebay/search#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/ebay/search.json)