nexscope-ai/nexscope-ecommerce-skills / ecommerce-ebay-search
ecommerce.ebay-search
VerifiedSearch and browse product listings across multiple eBay international sites. Trigger when user mentions eBay product search, eBay listing query, eBay price comparison, eBay market browsing, eBay sold items, eBay auction search, eBay product research, eBay products, eBay pricing, eBay competitors, eBay auctions, eBay market analysis — even if "eBay" is not explicitly mentioned, as long as the need involves searching products on eBay, comparing eBay prices, finding sold listings, or analyzing eBay market data.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.6 KB |
| manifest.json | config | 239 B |
| references/api.md | markdown | 8.5 KB |
| scripts/ebay_search.py | script | 6.5 KB |
references/api.md
View on GitHub# eBay Product Search API Reference
## API Specification
- **Endpoint**: `${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/ebay/search`
- **HTTP Method**: POST, Content-Type: application/json
- **Authentication**: Header `Authorization: <api_key>`, read api_key from environment variable `NEXSCOPE_API_KEY` or `NEXSCOPE_API_KEY` (if not configured, follow **## Resolving Authentication and Credit Issues** in SKILL.md)
## Request Parameters
POST Body (JSON):
| Parameter | Type | Required | Description |
|------|------|------|------|
| keyword | string | Conditional | Search keyword, max 1024 characters; required unless `categoryId` is supplied |
| ebayDomain | string | No | eBay site domain, default `ebay.com`. Options: ebay.com (United States), ebay.co.uk (United Kingdom), ebay.de (Germany), ebay.fr (France), ebay.it (Italy), ebay.es (Spain), ebay.ca (Canada), ebay.com.au (Australia), ebay.nl (Netherlands), ebay.at (Austria), ebay.ch (Switzerland), ebay.pl (Poland), ebay.ie (Ireland), ebay.com.hk (Hong Kong, China), ebay.com.my (Malaysia), ebay.com.sg (Singapore) |
| page | integer | No | Page number for pagination, default `1` |
| pageSize | integer | No | Maximum results per page, default `50`. Options: 25, 50, 100, 200 |
| orderBy | string | No | Sort order, default `12` (Best Match). Options: 1 (Ending soonest), 2 (Price lowest), 3 (Price highest), 7 (Distance nearest), 10 (Newly listed), 12 (Best Match), 15 (Price + shipping lowest), 16 (Price + shipping highest), 18 (New first), 19 (Used first) |
| priceMin | number | No | Minimum price filter |
| priceMax | number | No | Maximum price filter |
| itemCondition | string | No | Item condition code, multiple separated by `\|`. Options: 1000 (New), 1500 (New other), 1750 (New with defects), 2000 (Manufacturer refurbished), 2010 (Excellent refurbished), 2020 (Good refurbished), 2030 (Fair refurbished), 2500 (Seller refurbished), 2750 (Like new), 3000 (Used/Pre-owned), 7000 (For parts or not working) |
| buyingFormat | string | No | Buying format. Options: Auction, BIN (Buy It Now), BO (Best Offer) |
| showOnly | string | No | Filter conditions, comma-separated for multiple values. Options: Complete (Ended), FR (Free returns), RPA (Returns accepted), AS (Authorized seller), Savings (Discounts), SaleItems (Sale items), Lots (Lots), Charity (Charity), AV, FS (Free shipping), LPickup (Local pickup) |
| location | integer | No | Country/region code of item location (e.g., 1=United States, 2=Canada, 3=United Kingdom, 45=China, 77=Germany) |
| prefLoc | string | No | Preferred location scope. Options: 1 (Domestic), 2 (Regional), 3 (Worldwide) |
| zipCode | string | No | ZIP or postal code for filtering shippable items by region |
| categoryId | integer | Conditional | eBay category ID for category-specific search; required unless `keyword` is supplied |
| noCache | boolean | No | Whether to bypass cache, default `false` |
The upstream provider requires at least one of `keyword` or `categoryId`. A request with neither is rejected; category-only success has not been verified end to end.
## Nexscope response envelope
These research endpoints return a platform object with numeric `code`, nullable `msg`, and business `data`. Only outer `code: 0` means success; `200`, string codes, missing codes, and HTTP 200 alone do not. A nonzero code is a platform error: show `msg` and do not interpret the payload as a successful result.
`msg` preserves the upstream message when available; Chinese messages are translated to English by Nexscope. A successful response without a message has `msg: null`. Do not infer success or retry behavior from the message text. On both success and failure, the direct fields `code`, `errcode`, `errorCode`, `msg`, `errmsg`, `message`, and `errorMsg` are removed from public `data`. Read the message only from outer `msg`; deeper business fields are preserved, including nested `code` and `status`.
Business field tables and abbreviated business examples below describe `data`, unless explicitly labeled as a complete platform response. For example, a business `products` field is at HTTP `data.products`, and a business `data` array is at HTTP `data.data`. The research endpoints already had this outer envelope; no additional wrapper is added.
```json
{"code":0,"msg":null,"data":{}}
```
Metadata includes string `ts` (epoch milliseconds), string `cost` (elapsed milliseconds, not credits), `time`, and nullable `traceId`. Handle network/HTTP failures before the platform code; gateway failures may not be platform JSON. Keep the existing billing-header guidance separate from elapsed time.
## Response Structure
| Field | Type | Description |
|------|------|------|
| total | integer | Total matching results |
| products | array | Product list array (see product fields below) |
| columns | array | Rendered column definitions |
| type | string | Render style identifier |
| costToken | integer | Token consumption |
### Product Fields
| Field | Type | Description |
|------|------|------|
| productId | string | eBay product ID |
| title | string | Product title |
| subtitle | string | Product subtitle |
| price | number | Current price / transaction price |
| minPrice | number | Price range start value (for multi-SKU items) |
| maxPrice | number | Price range end value (for multi-SKU items) |
| oldPrice | number | Original price before discount |
| currency | string | Currency unit (e.g., USD, GBP, EUR) |
| condition | string | Item condition description |
| link | string | eBay product detail page link |
| imageUrl | string | Product thumbnail URL |
| shipping | string | Shipping information |
| location | string | Item location |
| sellerName | string | Seller name |
| sellerReviews | integer | Seller feedback count |
| positiveFeedbackInPercentage | number | Seller positive feedback percentage |
| salesQuantity | integer | Optional provider-reported quantity sold; period, source, and rounding are unspecified |
| bidsCount | integer | Bid count (for auction items) |
| returns | string | Return information |
| promotion | string | Promotion information |
| sponsored | boolean | Whether sponsored/promoted item |
| sourceType | string | Source platform identifier (`ebay`) |
| sourceTool | string | Source tool identifier |
## curl Example
```bash
curl -X POST ${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/ebay/search \
-H "Authorization: Bearer ${NEXSCOPE_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"keyword": "wireless earbuds", "ebayDomain": "ebay.com", "pageSize": 50, "orderBy": "12"}'
```
### Search for Completed Items
`Complete` includes ended listings that may not have sold. The upstream provider rejects `Sold`.
```bash
curl -X POST ${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/ebay/search \
-H "Authorization: Bearer ${NEXSCOPE_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"keyword": "iPhone 15 Pro", "showOnly": "Complete", "orderBy": "10"}'
```
### Filter by Price Range and Condition
```bash
curl -X POST ${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/ebay/search \
-H "Authorization: Bearer ${NEXSCOPE_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"keyword": "laptop", "ebayDomain": "ebay.co.uk", "priceMin": 500, "priceMax": 1000, "itemCondition": "1000"}'
```
## Error Codes
HTTP 200 does not prove business success. Read only the numeric outer platform `code`: `0` succeeds and any other value fails. Show outer `msg`; never test removed provider codes or nested business `code` as the platform status. Authentication, permissions, balance, and validation failures may be platform errors even with HTTP 200; also handle non-2xx HTTP and non-JSON responses.
### Recovery guidance
| Condition | Action |
|---|---|
| Authentication failed | HTTP 401 or authorized error: follow **## Resolving Authentication and Credit Issues** in SKILL.md. |
| Insufficient credits | HTTP 402: follow **## Resolving Authentication and Credit Issues** in SKILL.md. |
## API Key request rate and retries
All API Keys of one Nexscope user share the public API execution request-rate allowance, measured in any rolling 1-second window. The allowed RPS depends on that user's entitlements; it is not a universal 1 RPS. One Skill operation may issue multiple public API requests, each of which uses the allowance.
HTTP 429 with Nexscope outer code `13012` means request-rate exhaustion: honor the response's `Retry-After`. Outer code `13013` means concurrent-request exhaustion, not rate exhaustion; honor `Retry-After` when supplied. Check the HTTP status and outer JSON code separately. Do not automatically replay writes or requests with uncertain outcomes; first reconcile the operation's state.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |