eBay API reference

eBay Item Recommendations

ebay.item.promotions

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

eBay Item Recommendations API: overview and live sample

At a glance

Endpoint ID: ebay.item.promotions
Price: 0.5 credits per call; failed calls are free
Runs for up to: 180 seconds
Request: POST /execute; Run an endpoint
MCP tool when pinned: ebay__item__promotions; Pin tools
OpenAPI: openapi.json; Download

Request

Send the endpoint ID as capability and its fields as input. Set UPSCRAPE_API_KEY to your key first.

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));

Input

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

Response

A finished call answers with HTTP 200; the data is in results[0].data, and billing.credits_charged is what it cost. A call still running after the wait answers 202: see jobs and results.

This is results[0].data from a real run:

results[0].data

{  "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"          ]        }      ]    }  ]}

Fields

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

If a call fails

A failed call costs nothing. The response carries an error.code you can branch on; Errors and retries lists every code and which ones to retry.

Other eBay endpoints

Something missing or unclear? Ask the team that builds the eBay endpoints.