# eBay Item, Store & Store Category Detail Extractor (`vexaloom-labs/ebay-item-store-and-store-category-detail`) Actor

Extract detailed product data from eBay individual item pages, seller store fronts, and store category pages, or search by keyword across 8 marketplaces, with item specifics, images, seller trust signals and shipping/return terms.

- **URL**: https://apify.com/vexaloom-labs/ebay-item-store-and-store-category-detail.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** E-commerce, Automation, Lead generation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## eBay Item, Store & Store Category Detail Extractor

Open eBay item pages, walk a seller's entire store, or crawl one store category, and get complete item-detail records: item specifics, every high-resolution image, seller and store trust signals, stock and sales counts, shipping terms and return policy.

The actor reads public eBay pages only. No cookie, login, API key or proxy setup is required — paste a URL or a name and run.

### What can it scrape?

| Mode | Start with | What you get |
|------|-----------|--------------|
| **Item details** | Item IDs or `/itm/` links | One full record per listing |
| **Store inventory** | Store names or `/str/` links | The store's active listings, paginated, each opened for full details |
| **Store category** | Store-category links | One category inside a store, paginated, each listing opened for full details |
| **Keyword search** | Plain keywords | Matching listings, paginated, each opened for full details |

All four modes share one result budget (`maxItems`) and one page budget per source (`maxPages`). Discovery is paginated automatically: search pages, store fronts and store categories are walked until the budget is reached, the source runs out of pages, or a page returns no new item IDs.

### Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `mode` | Select | `search` | Item details, Store inventory, Store category, or Keyword search |
| `itemIds` | Array | – | Item IDs (`257633093777`) or full `/itm/` links |
| `storeNames` | Array | – | Store names (`discountcomputerdepot`) or `/str/` links |
| `storeCategoryUrls` | Array | – | Store-category links such as `https://www.ebay.com/str/mystore/Laptops/_i.html?store_cat=1234567890` |
| `searchQueries` | Array | – | Keywords, one search per entry |
| `startUrls` | Array | – | Optional shortcut: paste any eBay URL and it is routed to the right mode |
| `marketplace` | Select | `https://www.ebay.com` | One of 8 country sites (US, UK, DE, FR, IT, ES, CA, AU). The dropdown keeps the legacy full-URL values; API callers may also send `US`, `GB`, etc. |
| `condition` | Select | All | New, Open box, Manufacturer refurbished, Seller refurbished, Used, For parts |
| `buyingFormat` | Select | `""` | Buy It Now only or Auctions only |
| `minPrice` / `maxPrice` | Number | – | Price range in the marketplace currency |
| `sortBy` | Select | `bestMatch` | Best match, price low/high, ending soonest, newly listed |
| `freeShipping` | Boolean | `false` | Keep only free-shipping listings |
| `returnsAccepted` | Boolean | `false` | Keep only listings that accept returns |
| `itemLocation` | Select | Any | Domestic-only or worldwide |
| `maxItems` | Integer | `3` | Total records across every source |
| `maxPages` | Integer | `10` | Listing pages per store, category or search (up to 240 listings each) |
| `includeItemDetails` | Boolean | `true` | Open each discovered listing for the full item record; turn off for faster card-level results |
| `includeItemSpecifics` | Boolean | `true` | Include the item-specifics table and seller notes |

Condition, buying-format, price, sort, shipping, returns and item-location filters apply to **Keyword search** results. Store and Store category modes walk the seller's inventory in its own order.

#### Supported URL shapes

- Item: `https://www.ebay.com/itm/267153498498`
- Item with slug: `https://www.ebay.com/itm/Product-Title-Here/267153498498`
- Store: `https://www.ebay.com/str/thriftbooks`
- Store category: `https://www.ebay.com/str/thriftbooks/Fiction/_i.html?store_cat=261186`
- Search: `https://www.ebay.co.uk/sch/i.html?_nkw=laptop`
- Category browse: `https://www.ebay.com/b/PC-Laptops-Netbooks/177`

#### Example: item details

```json
{
    "mode": "item",
    "itemIds": ["257633093777"],
    "maxItems": 1
}
```

#### Example: store category

```json
{
    "mode": "storeCategory",
    "storeCategoryUrls": [
        "https://www.ebay.com/str/discountcomputerdepot/Laptops/_i.html?store_cat=10748275017"
    ],
    "maxItems": 20,
    "maxPages": 2
}
```

#### Example: keyword search

```json
{
    "mode": "search",
    "searchQueries": ["iphone 15 pro", "pixel 9"],
    "marketplace": "https://www.ebay.co.uk",
    "condition": "used",
    "maxItems": 50,
    "maxPages": 3
}
```

### Output

Every record is an item-detail record when `includeItemDetails` is on. Legacy fields from earlier versions of this actor keep their original names and formats; richer numeric and structured companions sit beside them.

| Field | Type | Description |
|-------|------|-------------|
| `recordType` | String | `item`, or `store` / `storeCategory` for an empty-source summary |
| `id`, `itemId` | String | eBay item ID |
| `url` | String | Canonical item URL |
| `title` | String | Listing title |
| `price` | String | Historical price format, e.g. `US $339.99` |
| `priceValue`, `priceCurrency` | Number, String | Numeric price and ISO currency |
| `originalPrice`, `wasPrice`, `wasPriceValue`, `discountPercent` | Mixed | Comparison price when discounted |
| `condition`, `conditionDescription` | String | Condition label and its longer explanation |
| `brand`, `model`, `mpn`, `gtin`, `color` | String | Product identifiers |
| `seller`, `sellerFeedbackScore`, `sellerFeedbackPercent`, `sellerFeedbackCount` | Mixed | Seller identity and trust |
| `sellerUrl`, `sellerStoreUrl` | String | Seller store link |
| `availableQuantity`, `quantityAvailable` | String, Number | Stock |
| `soldCount`, `quantitySold` | String, Number | Units sold |
| `watchCount`, `watcherCount` | String, Number | Watchers |
| `location`, `itemLocation` | String | Item location |
| `shippingCost`, `shippingCostValue`, `shippingCurrency`, `shippingDestination` | Mixed | Shipping terms |
| `returnPolicy`, `returns`, `returnDays`, `returnFees` | Mixed | Return terms |
| `paymentMethods` | Array | Accepted payment methods |
| `listingStartDate`, `startTime` | String | ISO 8601 listing start |
| `images`, `imageUrl` | Array, String | Full-size gallery |
| `itemSpecifics`, `sellerNotes` | Object, String | Complete specifics table |
| `categories`, `categoryPath` | Array | Breadcrumb path |
| `authenticityGuarantee`, `topRatedSeller`, `businessSeller` | Boolean | Trust badges |
| `listingType`, `bids`, `bidCount`, `timeLeft` | Mixed | Sale format and auction data |
| `vehicle` | Object | VIN, mileage and other eBay Motors fields (only on vehicle listings) |
| `marketplace` | String | Marketplace code |
| `searchUrl`, `storeListingUrl` | String | Page that produced the record |
| `storeName`, `storeUrl`, `storeTagline`, `storeFeedbackPercent`, `storeItemsSold`, `storeFollowers`, `storeListingCount` | Mixed | Store context attached to store-mode records |
| `storeCategoryName`, `storeCategoryUrl`, `storeCategoryId` | String | Category context attached to store-category records |
| `scrapedAt` | String | ISO 8601 scrape time |

#### Example output

```json
{
    "recordType": "item",
    "id": "257633093777",
    "itemId": "257633093777",
    "url": "https://www.ebay.com/itm/257633093777",
    "title": "Lenovo ThinkBook 15-ITL 15.6\" Core i5 16GB RAM 256GB SSD Windows 11 Pro Laptop",
    "price": "US $339.99",
    "priceValue": 339.99,
    "priceCurrency": "USD",
    "condition": "Good - Refurbished",
    "brand": "Lenovo",
    "model": "Lenovo ThinkBook 15 ITL",
    "mpn": "lenovodeals",
    "color": "Gray",
    "seller": "Discount Computer Depot",
    "sellerFeedbackScore": "178796",
    "sellerFeedbackCount": 178796,
    "sellerFeedbackPercent": "99.6%",
    "sellerUrl": "https://www.ebay.com/str/discountcomputerdepot",
    "availableQuantity": "10",
    "quantityAvailable": 10,
    "soldCount": "29",
    "quantitySold": 29,
    "watchCount": "183",
    "watcherCount": 183,
    "location": "Jacksonville, Texas, United States",
    "shippingCost": "Free shipping",
    "returnPolicy": "30 days returns",
    "returnDays": 30,
    "paymentMethods": ["PayPal", "Visa", "Master Card"],
    "listingStartDate": "2026-07-20T20:20:59Z",
    "images": ["https://i.ebayimg.com/images/g/example/s-l1600.jpg"],
    "itemSpecifics": {"Brand": "Lenovo", "Processor": "Intel Core i5-1135G7"},
    "categories": ["eBay", "Electronics", "Computers/Tablets & Networking"],
    "authenticityGuarantee": false,
    "topRatedSeller": true,
    "businessSeller": false,
    "listingType": "Buy It Now",
    "marketplace": "US",
    "scrapedAt": "2026-11-09T10:00:00+00:00"
}
```

### How pagination works

- Search and store listing pages accept 60, 120 or 240 rows per page; the actor right-sizes the page to the remaining `maxItems`.
- `maxPages` caps pages per store, category or search source. When you need more than 240 x 200 rows for one query, split by category or price range.
- Pagination stops on `maxItems`, the last page, a page with no new item IDs, or a repeated page.

### Tips for reliable runs

1. For a handful of listings, use **Item details** with item IDs.
2. For a seller's catalogue, use **Store inventory** and set `maxPages` high enough for the store size.
3. To split a large store, copy category links from the store page into **Store category**.
4. Keep `includeItemDetails` on when you need specifics, images and return terms; turn it off when card-level title/price is enough.
5. `maxItems` is shared by all sources, so size it for the total you want.

### FAQ

#### Do I need cookies, an account or a proxy?

No. The actor reads public pages and selects its network path automatically. There is no proxy field to configure and no credential to paste.

#### Why are some fields missing on a record?

eBay only renders some data for some listings: `originalPrice` appears when discounted, `bids` only on auctions, `vehicle` only on Motors listings, and `returnPolicy` may be absent on as-is vehicle listings. Missing values are omitted rather than emitted as null.

#### Can I use UK, German or Australian eBay?

Yes. Pick the marketplace site for names and keywords, or paste URLs from any of the eight supported country sites. A pasted URL keeps its own domain.

#### Does it support sold or completed listings?

No. eBay puts sold/completed search behind a sign-in wall, and this actor deliberately never uses cookies or logins. Active listings only.

#### Can I get the full store inventory?

Yes, until the store's own pagination ends or `maxItems` is reached. Use `maxPages` to control how deep it walks.

#### What is the difference between Store inventory and Store category?

Store inventory walks the whole store. Store category walks one category inside the store; use it to partition very large stores into smaller runs.

### Limitations

- Sold and completed listings require an eBay sign-in, so they are out of scope.
- eBay caps a single result set at 200 pages; split large sweeps by category or price band.
- A few card fields (rating, watchers, sold count) are only shown by eBay on some listings; they are omitted when absent.
- eBay changes its markup from time to time. The actor supports both the current item-detail schema and the localized marketplace variants it has been verified against.

# Actor input Schema

## `mode` (type: `string`):

Item details opens the item pages you list. Store inventory walks a seller's whole store. Store category walks one category inside a store. Keyword search finds matching listings.

## `itemIds` (type: `array`):

eBay item IDs (for example 257633093777) or full /itm/ links. Used in Item details mode.

## `storeNames` (type: `array`):

Seller store names (for example discountcomputerdepot) or /str/ store links. Used in Store inventory mode.

## `storeCategoryUrls` (type: `array`):

Store-category links copied from a store page, for example https://www.ebay.com/str/mystore/Laptops/\_i.html?store_cat=1234567890. Used in Store category mode.

## `searchQueries` (type: `array`):

Keywords to search on the selected marketplace. One search per entry. Used in Keyword search mode.

## `startUrls` (type: `array`):

Paste item, store, store-category, category-browse or search links and each is routed to the right mode automatically. Ignored when the arrays above already cover that source.

## `marketplace` (type: `string`):

Country site used for names and keywords, and for any input that is not already a full URL. The dropdown carries the legacy full-URL values; short codes (US, GB, DE, FR, IT, ES, CA, AU) are also accepted by API callers.

## `condition` (type: `string`):

Filter keyword-search results by condition. Leave on All conditions for every condition.

## `buyingFormat` (type: `string`):

Show only Buy It Now or auction listings in keyword-search results.

## `minPrice` (type: `number`):

Filter keyword-search results by minimum item price in the marketplace's local currency.

## `maxPrice` (type: `number`):

Filter keyword-search results by maximum item price in the marketplace's local currency.

## `sortBy` (type: `string`):

How to order keyword-search results.

## `freeShipping` (type: `boolean`):

Keep only keyword-search results that advertise free shipping or delivery.

## `returnsAccepted` (type: `boolean`):

Keep only keyword-search results that accept returns.

## `itemLocation` (type: `string`):

Keep keyword-search results located in the marketplace country, or show worldwide results.

## `maxItems` (type: `integer`):

Upper limit on item records across every source.

## `maxPages` (type: `integer`):

Stop after this many listing pages per store, category or search. Each page holds up to 240 listings.

## `includeItemDetails` (type: `boolean`):

When on, every discovered listing is opened and returns the full item record (specifics, images, seller, shipping, returns). Turn off for a faster card-level result from search and store pages.

## `includeItemSpecifics` (type: `boolean`):

Add the full item-specifics table (brand, model, MPN, dimensions, features and other aspects) to item records.

## Actor input object example

```json
{
  "mode": "search",
  "itemIds": [],
  "storeNames": [],
  "storeCategoryUrls": [],
  "searchQueries": [
    "laptop"
  ],
  "startUrls": [],
  "marketplace": "https://www.ebay.com",
  "condition": "",
  "buyingFormat": "",
  "sortBy": "bestMatch",
  "freeShipping": false,
  "returnsAccepted": false,
  "itemLocation": "",
  "maxItems": 2,
  "maxPages": 1,
  "includeItemDetails": true,
  "includeItemSpecifics": true
}
```

# Actor output Schema

## `items` (type: `string`):

Dataset containing detailed eBay item, store and store-category records.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "search",
    "searchQueries": [
        "laptop"
    ],
    "marketplace": "https://www.ebay.com",
    "freeShipping": false,
    "returnsAccepted": false,
    "maxItems": 2,
    "maxPages": 1,
    "includeItemDetails": true,
    "includeItemSpecifics": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/ebay-item-store-and-store-category-detail").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "search",
    "searchQueries": ["laptop"],
    "marketplace": "https://www.ebay.com",
    "freeShipping": False,
    "returnsAccepted": False,
    "maxItems": 2,
    "maxPages": 1,
    "includeItemDetails": True,
    "includeItemSpecifics": True,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/ebay-item-store-and-store-category-detail").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "search",
  "searchQueries": [
    "laptop"
  ],
  "marketplace": "https://www.ebay.com",
  "freeShipping": false,
  "returnsAccepted": false,
  "maxItems": 2,
  "maxPages": 1,
  "includeItemDetails": true,
  "includeItemSpecifics": true
}' |
apify call vexaloom-labs/ebay-item-store-and-store-category-detail --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/ebay-item-store-and-store-category-detail"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/ue8AF0IdZnL8KILaW/builds/2aHfLR6En16iBh6bc/openapi.json