eBay API · Endpoint

eBay Item Recommendations API

Q: What do I send?

Send item_id. The input fields below list every option with its type and limits.

Q: Can my AI agent call it?

Yes, over MCP: the agent finds ebay.item.promotions, checks its price and runs it with the same credits as the REST API.

Get the recommended listings eBay shows on an item page, with their prices and discounts.

1 credit per call
Failed calls are free
Updated 14 Oct 2026
ebay.item.promotions

Start free, 100 credits API reference

Response completed

{  "modules": [    {      "placement_id": "101878",      "position": 0,      "cards": [        {          "title": "APPLE MACBOOK PRO 15 | 16GB | 128GB SSD | i7 | RETINA | BIG SUR | WARRANTY |",          "price": "$199.00",          "image_url": "https://i.ebayimg.com/thumbs/images/g/fl8AAeSwW4tqf4nU/s-l500.jpg",          "item_id": "168614353575",          "shipping": "Free delivery",          "target_domain": "www.ebay.com",          "target_url": "https://www.ebay.com/itm/168614353575",          "text": [            "$199.00",            "95 sold"          ]        },        {          "title": "Apple MPXQ2LL/A MacBook Pro 13\" 2.3 GHz Core i5 8GB RAM NO SSD",          "price": "$168.00",          "image_url": "https://i.ebayimg.com/thumbs/images/g/ofgAAOSwqXJoB~~g/s-l500.jpg",          "item_id": "306264079646",          "shipping": "Free delivery",          "target_domain": "www.ebay.com",          "target_url": "https://www.ebay.com/itm/306264079646",          "text": [            "$168.00",            "Apple MPXQ2LL/A MacBook Pro 13\" 2.3 GHz Core i5 8GB RAM NO  SSD"          ]        }      ]    },    {      "placement_id": "101879",      "position": 1,      "cards": [        {          "title": "Dell Latitude 14” FHD Core i5 Laptop PC Up To 32GB RAM 1TB SSD Windows 11",          "price": "$289.00",          "image_url": "https://i.ebayimg.com/thumbs/images/g/zCIAAeSw1pxqIGR-/s-l500.jpg",          "item_id": "298041876436",          "shipping": "Free delivery",          "target_domain": "www.ebay.com",          "target_url": "https://www.ebay.com/itm/298041876436",          "text": [            "$289.00",            "20 watchers"          ]        },        {          "title": "Dell Latitude 5410 i5-10310U 1.7GHz 16GB RAM 256GB SSD Win 11 Pro",          "price": "$219.00",          "image_url": "https://i.ebayimg.com/thumbs/images/g/SlEAAeSwZSxpZHhX/s-l500.jpg",          "item_id": "306706076703",          "target_domain": "www.ebay.com",          "target_url": "https://www.ebay.com/itm/306706076703",          "text": [            "$219.00",            "+ $10.00 delivery"          ]        }      ]    }  ]}

2 rows

#	Position	Placement id
1	0	101878
2	1	101879

Try it live, free

Input

What you send

The input object of the request, with every field the endpoint accepts.

Field	Type	Required	What it does	Example
item_id	string	yes	Item identifier.	283987164379

Response

Fields it returns

What each record in the response holds, with the values from the sample above.

Field	Type	What it is	Example
modules[].cards[].title	string	The listing title as the seller wrote it.	APPLE MACBOOK PRO 15 \| 16GB \| 128GB SSD \| i7 \| RETINA \| BIG SUR…
modules[].cards[].text	array	The lines shown on the card, such as price and sold count.	$199.00, 95 sold, ALMOST GONE
modules[].cards[].price	string	The price as eBay shows it, with its currency sign.	$199.00
modules[].cards	array	The listings inside the block.	3 records
modules[].cards[].image_url	string	The listing's picture.	https://i.ebayimg.com/thumbs/images/g/fl8AAeSwW4tqf4nU/s-l500.j…
modules[].cards[].item_id	string	eBay's ID for the listing.	168614353575
modules[].cards[].shipping	string	Delivery terms as eBay shows them.	Free delivery
modules[].cards[].target_domain	string	The site the card links to.	www.ebay.com
modules[].cards[].target_url	string	Where the card links to.	https://www.ebay.com/itm/168614353575
modules[].placement_id	string	eBay's ID for the promotion slot.	101878
modules[].position	integer	The block's place on the page, starting at 0.	0
modules	array	The recommendation blocks shown with the item.	2 records

REST API · MCP server

Call it from your code, or ask your agent

Set UPSCRAPE_API_KEY to your key and copy a working request.

curl --request POST \  --url https://data.upscrape.com/execute \  --header "Authorization: Bearer $UPSCRAPE_API_KEY" \  --header "Content-Type: application/json" \  --header "Prefer: wait=30" \  --data '{  "capability": "ebay.item.promotions",  "input": {    "item_id": "283987164379"  }}'

import jsonimport osimport requestspayload = json.loads(r'''{  "capability": "ebay.item.promotions",  "input": {    "item_id": "283987164379"  }}''')response = requests.post(    "https://data.upscrape.com/execute",    headers={        "Authorization": f"Bearer {os.environ['UPSCRAPE_API_KEY']}",        "Content-Type": "application/json",        "Prefer": "wait=30",    },    json=payload,)response.raise_for_status()print(json.dumps(response.json(), indent=2))

const response = await fetch("https://data.upscrape.com/execute", {  method: "POST",  headers: {    "Authorization": `Bearer ${process.env.UPSCRAPE_API_KEY}`,    "Content-Type": "application/json",    "Prefer": "wait=30",  },  body: JSON.stringify({  "capability": "ebay.item.promotions",  "input": {    "item_id": "283987164379"  }}),});if (!response.ok) {  throw new Error(`Upscrape request failed: ${response.status}`);}console.log(JSON.stringify(await response.json(), null, 2));

In your AI agent Claude · Cursor · any MCP client

1Add the Upscrape MCP server

https://data.upscrape.com/mcp

2Ask for the data in plain words

With Upscrape, get the eBay item recommendations for item id "283987164379". Tell me what it costs before you run it, then show the results as a table.

The agent finds the endpoint, shows you the price, and runs it with your credits.

eBay