Mercari Listing Search API Documentation Search Mercari by keyword in the US market (USD) or the Japanese market (JPY). Filter by brand, category, condition, size, price range, shipping payer, seller and status. Set status to sold to read sold prices. Each listing has id, url, title, price as a number with currency, condition, brand, size, photos, likes, status and times; the Japanese market adds listing_type (c2c or shop). Sort by relevance, price or newest. The page parameter pages 30 listings at a time: up to page 33 in the US and page 500 in Japan. The total is capped at 10000 (US) and 15000 (JP). Ids for brand, category and size come from the listings. The data is public and read only. Each successful request costs 1 credit. A failed request is never billed.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
This endpoint has no required query parameters.
14 optional filters available.
string
Optional
Search keywords, for example nike. Required unless you send category, brand or seller.
coffee shops
string
Optional
Marketplace: us (United States) or jp (Japan). Defaults to us. The two markets are separate: ids and filters differ.
US
string
Optional
Comma list of Mercari category ids, for example 308. Take ids from the category block of search results.
example
string
Optional
Comma list of Mercari brand ids, for example 4578 (US Nike) or 857 (JP NIKE). Take ids from search results.
example
string
Optional
Comma list of condition ids. US: 1 New, 2 Like new, 3 Good, 4 Fair, 5 Poor. JP adds 6 Bad.
example
string
Optional
Comma list of size ids, taken from the size block of search results.
example
string
Optional
Comma list of color ids. Japan market only.
example
number
Optional
Lowest price in the market currency: US dollars or Japanese yen.
10
number
Optional
Highest price in the market currency. Must be at least min_price.
10
string
Optional
on_sale (default) or sold. Sold listings carry the sold price.
example
string
Optional
relevance (default), price_asc, price_desc or newest.
relevance
string
Optional
buyer or seller: who pays for shipping.
example
integer
Optional
Numeric seller id. Returns only listings of that seller.
10
integer
Optional
Page number, 30 listings per page. Defaults to 1. Maximum 33 for us and 500 for jp.
1
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
success
{
"data": {
"page": 1,
"items": [
{
"id": "m85764352496",
"url": "https://www.mercari.com/us/item/m85764352496/",
"size": {
"id": 78,
"name": "13 (46)"
},
"brand": {
"id": 31861,
"name": "Nike SB"
},
"likes": 7,
"price": 250,
"title": "Freddy Krueger SB Dunks",
"market": "us",
"photos": [
"https://u-mercari-images.mercdn.net/photos/m85764352496_1.jpg?1793310628"
],
"seller": {
"id": 207052431,
"name": null,
"rating_count": 81
},
"status": "on_sale",
"category": {
"id": 399,
"name": "Fashion sneakers"
},
"currency": "USD",
"condition": {
"id": 1,
"name": "New"
},
"listed_at": "2026-10-29T21:50:28Z",
"thumbnail": "https://u-mercari-images.mercdn.net/photos/m85764352496_1.jpg?1793310628",
"sold_price": null,
"updated_at": "2026-10-29T21:50:28Z",
"original_price": null,
"discount_percent": null
}
],
"query": "nike",
"total": 10000,
"market": "us",
"has_next": true,
"per_page": 30,
"total_is_capped": true
},
"success": true
}Errors
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
A parameter is missing or invalid. Mercari is not called and the request is not billable.
{
"errors": {
"page": [
"The page must be 33 or lower for the us market. Narrow the search or sort by price to reach more listings."
]
},
"message": "The request validation failed"
}Transport Unavailable
Mercari did not answer after several tries. Retry later. This response is not billable.
{
"error": {
"code": "transport_unavailable",
"message": "Mercari could not be reached right now. The request is not billed. Try again."
},
"success": false
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.