{ "openapi": "3.1.0", "info": { "title": "eBay API", "version": "1.0.0", "description": "Public eBay listings, bulk price checks, seller feedback and product reviews, as a US buyer sees them, exposed through FetchLayer as structured JSON." }, "servers": [ { "url": "https://api.fetchlayer.dev/ebay" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key." } } }, "paths": { "/search-listings": { "post": { "operationId": "search-listings", "tags": [ "Listings" ], "summary": "Search live listings", "description": "Search eBay's live listings by keyword, category or seller, as a US buyer sees them. Each listing comes back with its item number, title, condition, price in US dollars, struck-through original price, auction or fixed price, bid count and time left, shipping cost to the United States, where it ships from, units sold, watchers, and the seller's username, feedback score and positive percentage. Filter by condition, buying format, price range, free shipping, returns or offers, and sort by best match, price plus shipping, ending soonest or newly listed. At least one of query, categoryId or seller is required. Only active listings are searchable: sold and completed listings are shown by eBay to signed-in members only, and are not available here.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Keywords to search for, 1-350 characters. Required unless categoryId or seller is given." }, "categoryId": { "type": "string", "description": "Restrict to one eBay category by its numeric id, for example \"112529\" for headphones." }, "seller": { "type": "string", "description": "Restrict to one seller's listings, by username." }, "condition": { "type": "array", "items": { "type": "string" }, "description": "Any of new, open_box, refurbished, used, for_parts." }, "buyingFormat": { "type": "string", "description": "all, auction or buy_it_now.", "example": "all" }, "acceptsOffers": { "type": "boolean", "description": "Only listings that accept offers.", "example": "false" }, "minPrice": { "type": "number", "description": "Minimum price in US dollars." }, "maxPrice": { "type": "number", "description": "Maximum price in US dollars." }, "freeShipping": { "type": "boolean", "description": "Only listings with free shipping to the United States.", "example": "false" }, "returnsAccepted": { "type": "boolean", "description": "Only listings that accept returns.", "example": "false" }, "sort": { "type": "string", "description": "best_match, price_lowest, price_highest, ending_soonest or newly_listed. The two price orders sort on price plus shipping, as eBay does.", "example": "best_match" }, "limit": { "type": "number", "description": "Maximum listings returned (max 1000), or -1 for the maximum.", "example": "60" }, "pages": { "type": "number", "description": "Pages to collect in one request (max 50), or -1 for the maximum allowed. Defaults to as many as limit needs. Each page counts as one request." }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor. A cursor is bound to the request that produced it, so send the same filters with it — a cursor replayed against different filters is a 400." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "format": { "type": "string", "description": "json or markdown. Markdown returns the same result rendered for a model to read.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Time limit for each eBay page read, in milliseconds (max 120000)." } }, "additionalProperties": false }, "examples": { "default": { "value": { "query": "anker usb c charger", "condition": [ "new" ], "limit": 20 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "resultType": { "type": "string", "description": "Which shape this response is: search-listings, listing-details, price-check, seller-feedback or product-reviews." }, "requestedUrl": { "type": "string", "description": "The eBay page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was read." }, "transport": { "type": "string", "description": "The upstream source. Always \"ebay\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result — converted prices, a walk that stopped early, a continuation that may repeat listings. Read it on every call: it is where an incomplete answer announces itself." }, "query": { "type": "string", "description": "The keywords searched, or null." }, "totalResults": { "type": "number", "description": "eBay's displayed result count, for example 2500." }, "totalResultsIsLowerBound": { "type": "boolean", "description": "True when eBay shows the count with a plus, as in \"2,500+\"." }, "listings": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "itemId": { "type": "string", "description": "The item number — what listing-details and price-check take." }, "title": { "type": "string", "description": "Listing title." }, "url": { "type": "string", "description": "Listing URL." }, "imageUrl": { "type": "string", "description": "Main image URL." }, "condition": { "type": "string", "description": "Condition as eBay shows it, for example \"Pre-Owned\" or \"Brand New\"." }, "price": { "type": "object", "additionalProperties": true, "description": "Price as { amount, currency }, in US dollars." }, "priceMax": { "type": "object", "additionalProperties": true, "description": "Upper bound for a listing with variations at different prices, or null." }, "originalPrice": { "type": "object", "additionalProperties": true, "description": "A struck-through earlier or list price, or null." }, "buyingFormat": { "type": "string", "description": "fixed_price or auction." }, "acceptsOffers": { "type": "boolean", "description": "Whether the listing accepts offers." }, "buyItNowPrice": { "type": "object", "additionalProperties": true, "description": "An auction's Buy It Now price, or null." }, "bidCount": { "type": "number", "description": "Bids on an auction, or null." }, "timeLeft": { "type": "string", "description": "Time left as shown, for example \"2d 22h left\", or null." }, "shippingCost": { "type": "object", "additionalProperties": true, "description": "Shipping cost to the United States, or null when free or not stated." }, "freeShipping": { "type": "boolean", "description": "Whether shipping is free." }, "shippingText": { "type": "string", "description": "The shipping line as shown." }, "location": { "type": "string", "description": "Country or region the listing ships from." }, "soldCount": { "type": "number", "description": "Units sold, where eBay shows it." }, "watcherCount": { "type": "number", "description": "Watchers, where eBay shows it." }, "seller": { "type": "object", "additionalProperties": true, "description": "username, feedbackScore and positivePercent. On search results feedbackScore is eBay's rounded figure (\"282K\" becomes 282000); listing-details returns the exact one." } } }, "description": "The listings, in the order eBay returned them." }, "listingCount": { "type": "number", "description": "Length of listings." }, "pagesScraped": { "type": "number", "description": "Pages actually collected. Each page counts as one request against your plan." }, "pagesRequested": { "type": "number", "description": "Pages this request asked for." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue, or null when there is nothing further." }, "hasNextPage": { "type": "boolean", "description": "Whether more results are available beyond this response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "search-listings", "requestedUrl": "https://www.ebay.com/sch/i.html?_nkw=anker+usb+c+charger&LH_ItemCondition=1000&_fcid=1&_ul=US", "transport": "ebay", "notes": [], "query": "anker usb c charger", "totalResults": 4600, "totalResultsIsLowerBound": true, "listings": [ { "itemId": "334140575100", "title": "Anker Nano Pro 20W USB C Charger PIQ 3.0 Fast Charging for iPhone 14 13 iPad Pro", "url": "https://www.ebay.com/itm/334140575100", "imageUrl": "https://i.ebayimg.com/images/g/n4AAAOSwsOthODVm/s-l500.jpg", "condition": "Brand New", "price": { "amount": 11.99, "currency": "USD" }, "priceMax": null, "originalPrice": null, "buyingFormat": "fixed_price", "acceptsOffers": false, "bidCount": null, "timeLeft": null, "shippingCost": null, "freeShipping": true, "shippingText": "Free delivery", "location": "United States", "soldCount": 405, "watcherCount": null, "seller": { "username": "ankerdirect", "positivePercent": 99.8, "feedbackScore": 282000 } } ], "listingCount": 20, "pagesScraped": 1, "pagesRequested": 1, "nextCursor": "eyJ2IjoxLCJwIjoxLCJvIjoyMCwicyI6NjAsImIiOiIyZjRiZGY1MzkxZWMifQ", "hasNextPage": true } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/listing-details": { "post": { "operationId": "listing-details", "tags": [ "Listings" ], "summary": "Get one listing in full", "description": "Everything one listing publishes: title, status, price in US dollars and in the seller's own currency, original price, availability and the exact quantity where eBay states a number, units sold, condition, the seller with their exact feedback score and store URL, shipping cost and service to the United States, where it ships from, the return policy, auction state (current bid, bid count, end time, whether there is a reserve), item specifics, the category path, full-size image URLs, brand, MPN and GTIN, accepted payment methods and when it was listed. An ended listing is a 200 with status ended and its final prices; a listing that does not exist is a 404.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listing": { "type": "string", "description": "eBay item number (for example 334140575100), or any eBay listing URL." }, "format": { "type": "string", "description": "json or markdown. Markdown returns the same result rendered for a model to read.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Time limit for each eBay page read, in milliseconds (max 120000)." } }, "additionalProperties": false, "required": [ "listing" ] }, "examples": { "default": { "value": { "listing": "334140575100" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "resultType": { "type": "string", "description": "Which shape this response is: search-listings, listing-details, price-check, seller-feedback or product-reviews." }, "requestedUrl": { "type": "string", "description": "The eBay page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was read." }, "transport": { "type": "string", "description": "The upstream source. Always \"ebay\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result — converted prices, a walk that stopped early, a continuation that may repeat listings. Read it on every call: it is where an incomplete answer announces itself." }, "listing": { "type": "object", "additionalProperties": true, "description": "The listing.", "properties": { "itemId": { "type": "string", "description": "Item number, with title and url alongside it." }, "status": { "type": "string", "description": "active or ended." }, "buyingFormat": { "type": "string", "description": "fixed_price or auction." }, "acceptsOffers": { "type": "boolean", "description": "Whether offers are accepted." }, "price": { "type": "object", "additionalProperties": true, "description": "Price as { amount, currency } in US dollars, as shown to a US buyer. A listing priced in another currency is converted at eBay's current rate." }, "listingPrice": { "type": "object", "additionalProperties": true, "description": "The seller's own figure, in the seller's currency. Equal to price for a US-dollar listing. Compare this over time to tell a real price change from exchange-rate movement." }, "originalPrice": { "type": "object", "additionalProperties": true, "description": "List or earlier price where shown, or null." }, "availability": { "type": "string", "description": "in_stock, out_of_stock, or null." }, "quantityAvailable": { "type": "number", "description": "Exact when eBay states a number; null for \"More than 10 available\"." }, "quantityText": { "type": "string", "description": "The quantity line as shown." }, "soldCount": { "type": "number", "description": "Units sold." }, "condition": { "type": "string", "description": "Condition as shown." }, "seller": { "type": "object", "additionalProperties": true, "description": "username, exact feedbackScore, positivePercent and storeUrl." }, "shipping": { "type": "object", "additionalProperties": true, "description": "cost (US dollars), listingCost (seller currency, when not US dollars), free, service and text." }, "location": { "type": "string", "description": "Where it ships from, for example \"Ontario, California, United States\"." }, "returns": { "type": "string", "description": "Return policy as shown." }, "auction": { "type": "object", "additionalProperties": true, "description": "For auctions: currentBid, listingCurrentBid, bidCount, endsAt (ISO 8601) and hasReservePrice. Null for fixed-price listings." }, "itemSpecifics": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "{ name, value } pairs as the seller entered them." }, "categories": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Category path as { categoryId, name }." }, "imageUrls": { "type": "array", "items": { "type": "string" }, "description": "Full-size image URLs." }, "brand": { "type": "string", "description": "Brand, with mpn and gtin alongside it. Null when absent or \"Does not apply\"." }, "paymentMethods": { "type": "array", "items": { "type": "string" }, "description": "Accepted payment methods." }, "listedAt": { "type": "string", "description": "When the listing went live, ISO 8601." } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "listing-details", "requestedUrl": "https://www.ebay.com/itm/334140575100?_ul=US", "transport": "ebay", "notes": [], "listing": { "itemId": "334140575100", "title": "Anker Nano Pro 20W USB C Charger PIQ 3.0 Fast Charging for iPhone 14 13 iPad Pro", "url": "https://www.ebay.com/itm/334140575100", "status": "active", "buyingFormat": "fixed_price", "acceptsOffers": false, "price": { "amount": 11.99, "currency": "USD" }, "listingPrice": { "amount": 11.99, "currency": "USD" }, "originalPrice": null, "availability": "in_stock", "quantityAvailable": null, "quantityText": "More than 10 available", "soldCount": 1256, "condition": "New", "seller": { "username": "ankerdirect", "feedbackScore": 282091, "positivePercent": 99.8, "storeUrl": "https://www.ebay.com/str/ankerdirect" }, "shipping": { "cost": null, "listingCost": null, "free": true, "service": "Standard Shipping", "text": "Free Standard Shipping" }, "location": "Ontario, California, United States", "returns": "30 days returns. Buyer pays for return shipping.", "auction": null, "itemSpecifics": [ { "name": "Items Included", "value": "Anker Nano Pro Charger" }, { "name": "Material", "value": "Plastic" } ], "categories": [ { "categoryId": "15032", "name": "Cell Phones & Accessories" }, { "categoryId": "9394", "name": "Cell Phone Accessories" }, { "categoryId": "123417", "name": "Chargers & Cradles" } ], "imageUrls": [ "https://i.ebayimg.com/images/g/n4AAAOSwsOthODVm/s-l1600.jpg" ], "brand": "Anker", "mpn": "AKA2637", "gtin": null, "paymentMethods": [ "PayPal", "Venmo", "Google Pay", "Visa", "Master Card", "Discover" ], "listedAt": "2021-09-08T04:09:32Z" } } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/price-check": { "post": { "operationId": "price-check", "tags": [ "Listings" ], "summary": "Check prices for many listings", "description": "The lightweight way to monitor prices. Send up to 100 item numbers and get each listing's current price and state back — nothing else. In fast mode (the default) listings are answered up to 50 at a time, at roughly 5KB a listing, so checking a batch costs little more than checking one; each carries its price in US dollars, a price range for listings with variations, bids for an auction, shipping cost to the United States and whether it is still active. Exact mode reads each listing on its own and adds the seller's own currency, availability and the exact quantity. In both modes every listing you ask for comes back: one that has ended is reported as ended with its final price, one that no longer exists as not_found. These are current asking prices; what a listing eventually sold for is shown by eBay to signed-in members only and is not available. Billing: each product that gets a definitive result — a price, or a status such as out of stock, ended, unavailable or not found — counts as one request, so pricing 20 products bills 20. Products that fail on our side (blocked, timed out, not reached) are not billed, and duplicates count once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listings": { "type": "array", "items": { "type": "string" }, "description": "1-100 listings, each an eBay item number (for example 334140575100), or any eBay listing URL. Duplicates are answered once." }, "mode": { "type": "string", "description": "fast answers up to 50 listings together, prices in US dollars. exact reads each listing individually and adds listingPrice (seller's currency), availability and quantityAvailable.", "example": "fast" }, "format": { "type": "string", "description": "json or markdown. Markdown returns the same result rendered for a model to read.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Time limit for each eBay page read, in milliseconds (max 120000)." } }, "additionalProperties": false, "required": [ "listings" ] }, "examples": { "default": { "value": { "listings": [ "334140575100", "326634081605", "335571739480" ] } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "pagesScraped": { "type": "number", "description": "Products that received a definitive result. Each counts as one request against your plan; failed products and duplicates do not." }, "resultType": { "type": "string", "description": "Which shape this response is: search-listings, listing-details, price-check, seller-feedback or product-reviews." }, "requestedUrl": { "type": "string", "description": "The eBay page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was read." }, "transport": { "type": "string", "description": "The upstream source. Always \"ebay\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result — converted prices, a walk that stopped early, a continuation that may repeat listings. Read it on every call: it is where an incomplete answer announces itself." }, "mode": { "type": "string", "description": "fast or exact." }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "itemId": { "type": "string", "description": "Item number, with url alongside it." }, "status": { "type": "string", "description": "active, ended or not_found." }, "price": { "type": "object", "additionalProperties": true, "description": "Price as { amount, currency } in US dollars, in both modes — so a series of checks stays comparable." }, "priceMax": { "type": "object", "additionalProperties": true, "description": "Upper bound of a price range (fast mode), or null." }, "listingPrice": { "type": "object", "additionalProperties": true, "description": "Price in the seller's own currency. Exact mode; in fast mode only for a listing that was read on its own." }, "buyingFormat": { "type": "string", "description": "fixed_price or auction, with bidCount alongside it." }, "availability": { "type": "string", "description": "in_stock or out_of_stock. Exact mode, or a listing read on its own." }, "quantityAvailable": { "type": "number", "description": "Exact quantity where eBay states one. Exact mode, or a listing read on its own." }, "shippingCost": { "type": "object", "additionalProperties": true, "description": "Shipping cost to the United States, or null." }, "freeShipping": { "type": "boolean", "description": "Whether shipping is free. Null when the listing states neither, for example \"May not ship to United States\"." } } }, "description": "One entry per distinct listing asked for, never fewer." }, "itemCount": { "type": "number", "description": "Length of items, with activeCount, endedCount and notFoundCount alongside it." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "price-check", "transport": "ebay", "notes": [ "Prices are in US dollars as eBay shows them to a US buyer; a listing priced in another currency is converted at eBay's current rate. Use mode exact for each listing's own currency, availability and the quantity available." ], "mode": "fast", "items": [ { "itemId": "334140575100", "url": "https://www.ebay.com/itm/334140575100", "status": "active", "price": { "amount": 11.99, "currency": "USD" }, "priceMax": null, "listingPrice": null, "buyingFormat": "fixed_price", "bidCount": null, "availability": null, "quantityAvailable": null, "shippingCost": null, "freeShipping": true }, { "itemId": "326634081605", "url": "https://www.ebay.com/itm/326634081605", "status": "active", "price": { "amount": 16.99, "currency": "USD" }, "priceMax": null, "listingPrice": null, "buyingFormat": "fixed_price", "bidCount": null, "availability": null, "quantityAvailable": null, "shippingCost": null, "freeShipping": true }, { "itemId": "335571739480", "url": "https://www.ebay.com/itm/335571739480", "status": "active", "price": { "amount": 35.99, "currency": "USD" }, "priceMax": null, "listingPrice": null, "buyingFormat": "fixed_price", "bidCount": null, "availability": null, "quantityAvailable": null, "shippingCost": null, "freeShipping": true } ], "itemCount": 3, "activeCount": 3, "endedCount": 0, "notFoundCount": 0 } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/seller-feedback": { "post": { "operationId": "seller-feedback", "tags": [ "Reviews & feedback" ], "summary": "Read a seller's feedback", "description": "A member's feedback profile and the individual feedback behind it. The profile carries the feedback score, positive percentage over twelve months, member-since date, location and store URL, positive, neutral and negative counts for the last month, six months and twelve months, and detailed seller ratings for accurate description, shipping cost, shipping speed and communication. Each entry has its rating, the comment, the buyer (masked by eBay, for example \"e***4\") and their feedback score, when it was left, and the item title, id and price. eBay publishes feedback dates only as relative text such as \"Past month\", never an exact date. Filter by role and rating, and set includeAutomated to false to read only what buyers wrote rather than eBay's automatic on-time-delivery feedback. An unknown username is a 404.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "seller": { "type": "string", "description": "eBay username (for example vipoutlet), or a seller profile or feedback URL. A store URL is refused: a store name is not necessarily its seller's username." }, "role": { "type": "string", "description": "Feedback received as_seller, as_buyer, or all.", "example": "as_seller" }, "rating": { "type": "string", "description": "all, positive, neutral or negative.", "example": "all" }, "includeAutomated": { "type": "boolean", "description": "Include eBay's automatic feedback for orders delivered on time. Set false to read only buyer-written feedback.", "example": "true" }, "limit": { "type": "number", "description": "Maximum feedback entries returned (max 500), or -1 for the maximum.", "example": "25" }, "pages": { "type": "number", "description": "Pages to collect in one request (max 50), or -1 for the maximum allowed. Defaults to as many as limit needs. Each page counts as one request." }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor. A cursor is bound to the request that produced it, so send the same filters with it — a cursor replayed against different filters is a 400." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "format": { "type": "string", "description": "json or markdown. Markdown returns the same result rendered for a model to read.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Time limit for each eBay page read, in milliseconds (max 120000)." } }, "additionalProperties": false, "required": [ "seller" ] }, "examples": { "default": { "value": { "seller": "vipoutlet", "includeAutomated": false, "limit": 25 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "resultType": { "type": "string", "description": "Which shape this response is: search-listings, listing-details, price-check, seller-feedback or product-reviews." }, "requestedUrl": { "type": "string", "description": "The eBay page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was read." }, "transport": { "type": "string", "description": "The upstream source. Always \"ebay\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result — converted prices, a walk that stopped early, a continuation that may repeat listings. Read it on every call: it is where an incomplete answer announces itself." }, "seller": { "type": "object", "additionalProperties": true, "description": "The profile.", "properties": { "feedbackScore": { "type": "number", "description": "Feedback score, with username alongside it." }, "positivePercent": { "type": "number", "description": "Positive feedback percentage over the last 12 months." }, "memberSince": { "type": "string", "description": "As shown, for example \"Mar-12-02\"." }, "location": { "type": "string", "description": "Member location, with storeUrl alongside it." }, "ratingsLastMonth": { "type": "object", "additionalProperties": true, "description": "{ positive, neutral, negative } counts; ratingsLast6Months and ratingsLast12Months have the same shape." }, "detailedRatings": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "{ name, average, count } for accurate description, shipping cost, shipping speed and communication." }, "totalFeedback": { "type": "number", "description": "Total feedback received." } } }, "feedback": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "feedbackId": { "type": "string", "description": "Stable id for the entry." }, "rating": { "type": "string", "description": "positive, neutral or negative." }, "comment": { "type": "string", "description": "The comment." }, "from": { "type": "string", "description": "The member who left it, masked by eBay (\"e***4\"), or \"eBay automated feedback\"; fromFeedbackScore alongside it." }, "when": { "type": "string", "description": "Relative text as eBay publishes it, for example \"Past month\"." }, "itemTitle": { "type": "string", "description": "The item the feedback was left on, with itemId and itemPrice alongside it." }, "verifiedPurchase": { "type": "boolean", "description": "Whether eBay marks it as a verified purchase." }, "automated": { "type": "boolean", "description": "True for eBay's automatic on-time-delivery feedback." } } }, "description": "Individual feedback, newest first." }, "feedbackCount": { "type": "number", "description": "Length of feedback." }, "pagesScraped": { "type": "number", "description": "Pages actually collected. Each page counts as one request against your plan." }, "pagesRequested": { "type": "number", "description": "Pages this request asked for." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue, or null when there is nothing further." }, "hasNextPage": { "type": "boolean", "description": "Whether more results are available beyond this response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "seller-feedback", "transport": "ebay", "notes": [], "seller": { "username": "vipoutlet", "feedbackScore": 963024, "positivePercent": 97.2, "memberSince": "Mar-12-02", "location": "United States", "storeUrl": "https://stores.ebay.com/vipoutlet", "ratingsLastMonth": { "positive": 90637, "neutral": 628, "negative": 1245 }, "ratingsLast6Months": { "positive": 377786, "neutral": 3448, "negative": 7045 }, "ratingsLast12Months": { "positive": 590119, "neutral": 5959, "negative": 14236 }, "detailedRatings": [ { "name": "Accurate description", "average": 4.4, "count": 72587 }, { "name": "Shipping speed", "average": 4.9, "count": 106637 } ], "totalFeedback": 1278373 }, "feedback": [ { "feedbackId": "2732053565020", "rating": "positive", "comment": "Good quality OEM ink, $ & thank you.", "from": "e***4", "fromFeedbackScore": 2507, "when": "Past month", "itemTitle": "Epson T232 Combo High Yield Ink Cartridge - Black/Cyan/Magenta/Yellow", "itemId": "134663833588", "itemPrice": { "amount": 32, "currency": "USD" }, "verifiedPurchase": true, "automated": false } ], "feedbackCount": 25, "pagesScraped": 1, "pagesRequested": 1, "nextCursor": "eyJ2IjoxLCJwIjoyLCJvIjowLCJzIjoyNSwiYiI6Ijk0MGU1OWEwZTBmNyJ9", "hasNextPage": true } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/product-reviews": { "post": { "operationId": "product-reviews", "tags": [ "Reviews & feedback" ], "summary": "Read product reviews", "description": "Buyer reviews of an eBay catalogue product — the product page that groups every listing of the same item, not a single listing. The product summary carries the average rating out of five, rating and review counts, the count per star, and aspect agreement such as \"Good sound quality: 100%\". Each review has its rating, title (eBay truncates long titles), body, author, publication date as shown, whether it was a verified purchase, the condition bought, who sold it, and helpful and not-helpful votes. Reviews come in eBay's most-relevant order, the only order eBay publishes them in. A listing's item specifics carry its catalogue id as \"eBay Product ID (ePID)\". An unknown product is a 404.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string", "description": "eBay catalogue product id (for example 27061041202), or a product or reviews URL." }, "limit": { "type": "number", "description": "Maximum reviews returned (max 500), or -1 for the maximum.", "example": "10" }, "pages": { "type": "number", "description": "Pages to collect in one request (max 50), or -1 for the maximum allowed. Defaults to as many as limit needs. Each page counts as one request." }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor. A cursor is bound to the request that produced it, so send the same filters with it — a cursor replayed against different filters is a 400." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "format": { "type": "string", "description": "json or markdown. Markdown returns the same result rendered for a model to read.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Time limit for each eBay page read, in milliseconds (max 120000)." } }, "additionalProperties": false, "required": [ "product" ] }, "examples": { "default": { "value": { "product": "27061041202", "limit": 10 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "resultType": { "type": "string", "description": "Which shape this response is: search-listings, listing-details, price-check, seller-feedback or product-reviews." }, "requestedUrl": { "type": "string", "description": "The eBay page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was read." }, "transport": { "type": "string", "description": "The upstream source. Always \"ebay\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result — converted prices, a walk that stopped early, a continuation that may repeat listings. Read it on every call: it is where an incomplete answer announces itself." }, "product": { "type": "object", "additionalProperties": true, "description": "The catalogue product.", "properties": { "productId": { "type": "string", "description": "Catalogue product id, with title, url and imageUrl alongside it." }, "averageRating": { "type": "number", "description": "Average rating out of 5." }, "ratingCount": { "type": "number", "description": "Ratings, with the product's total reviewCount alongside it." }, "ratingDistribution": { "type": "object", "additionalProperties": true, "description": "Count per star, keyed \"1\" to \"5\"." }, "aspects": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "{ name, percent } — the share of buyers who agree with statements such as \"Good sound quality\"." } } }, "reviews": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "reviewId": { "type": "string", "description": "Stable id for the review." }, "rating": { "type": "number", "description": "Star rating, 1 to 5." }, "title": { "type": "string", "description": "Review title. eBay truncates long titles; body has the full text." }, "body": { "type": "string", "description": "Review text." }, "author": { "type": "string", "description": "Reviewer username." }, "publishedOn": { "type": "string", "description": "Date as shown, for example \"Nov 06, 2024\"." }, "verifiedPurchase": { "type": "boolean", "description": "Whether the reviewer bought it on eBay." }, "condition": { "type": "string", "description": "Condition bought: new, pre-owned, refurbished." }, "soldBy": { "type": "string", "description": "The seller it was bought from." }, "helpfulCount": { "type": "number", "description": "Helpful votes, with notHelpfulCount alongside it." } } }, "description": "Reviews in eBay's most-relevant order." }, "reviewCount": { "type": "number", "description": "Length of reviews in this response." }, "pagesScraped": { "type": "number", "description": "Pages actually collected. Each page counts as one request against your plan." }, "pagesRequested": { "type": "number", "description": "Pages this request asked for." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue, or null when there is nothing further." }, "hasNextPage": { "type": "boolean", "description": "Whether more results are available beyond this response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "product-reviews", "requestedUrl": "https://www.ebay.com/urw/product-reviews/27061041202?_ul=US", "transport": "ebay", "notes": [ "Reviews are listed in eBay's most relevant order, the only order eBay publishes them in." ], "product": { "productId": "27061041202", "title": "Skullcandy Crusher ANC 2 Bluetooth Wireless Headphones - Black (S6CAW-R740)", "url": "https://www.ebay.com/p/27061041202", "averageRating": 4.9, "ratingCount": 27, "reviewCount": 27, "ratingDistribution": { "1": 0, "2": 0, "3": 1, "4": 1, "5": 25 }, "aspects": [ { "name": "Good sound quality", "percent": 100 }, { "name": "Comfortable", "percent": 100 } ] }, "reviews": [ { "reviewId": "10000000321829280", "rating": 5, "title": "Excellent headset. Better than JBL live6...", "body": "Excellent headset. Better than JBL live660 NC .audio adjustments are such a great feature", "author": "frankstro", "publishedOn": "Nov 06, 2024", "verifiedPurchase": true, "condition": "new", "soldBy": "jpop4me", "helpfulCount": 1, "notHelpfulCount": 0 } ], "reviewCount": 10, "pagesScraped": 1, "pagesRequested": 1, "nextCursor": "eyJ2IjoxLCJwIjoyLCJvIjowLCJzIjoxMCwiYiI6ImVkOGIzOWQwNzJjZCJ9", "hasNextPage": true } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/resolve-url": { "post": { "operationId": "resolve-url", "tags": [ "Utility" ], "summary": "Parse an eBay URL", "description": "Turn any eBay URL into the fields the other endpoints take, without contacting eBay. A listing URL gives its itemId, a search URL its query, categoryId and seller, a category URL its categoryId, a seller profile or feedback URL the username, a store URL the store name, and a catalogue product or reviews URL its productId. Hand it a link a colleague pasted and pass the result straight on. A URL that is not eBay, or an eBay URL of another kind, is a 400. Parsing a URL does not consume a credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Any eBay URL, to be parsed into structured input." }, "format": { "type": "string", "description": "json or markdown. Markdown returns the same result rendered for a model to read.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Time limit for each eBay page read, in milliseconds (max 120000)." } }, "additionalProperties": false, "required": [ "url" ] }, "examples": { "default": { "value": { "url": "https://www.ebay.com/sch/i.html?_nkw=anker+usb+c+charger&_sacat=123417" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "listing, search, category, seller, seller-feedback, store, product or product-reviews." }, "url": { "type": "string", "description": "The URL that was parsed." }, "itemId": { "type": "string", "description": "Present when kind is listing — pass it to listing-details or price-check." }, "query": { "type": "string", "description": "Present when kind is search, with categoryId, seller and page alongside it." }, "categoryId": { "type": "string", "description": "Present when kind is search or category; a category also carries its name." }, "username": { "type": "string", "description": "Present when kind is seller or seller-feedback — pass it to seller-feedback." }, "storeName": { "type": "string", "description": "Present when kind is store." }, "productId": { "type": "string", "description": "Present when kind is product or product-reviews — pass it to product-reviews." } }, "additionalProperties": false }, "examples": { "default": { "value": { "kind": "search", "query": "anker usb c charger", "categoryId": "123417", "seller": null, "page": 1, "url": "https://www.ebay.com/sch/i.html?_nkw=anker+usb+c+charger&_sacat=123417" } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } } } }