Mercari Seller API Documentation Read a Mercari seller by numeric id in the US or Japanese market. The answer has the profile and one page of listings, 30 per page. The US profile has name and rating count. The Japanese profile adds the introduction, good, normal and bad ratings, star score, followers and listing count. Contact data such as email or phone is never returned. Set status to sold to list sold items with their sold prices. Seller review texts are not public and are not returned. 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
1 required parameter needed before sending a request.
3 optional filters available.
integer
Required
Numeric seller id, for example 306933034. Read it from the seller block of a listing.
1234567890
string
Optional
Marketplace: us (United States) or jp (Japan). Defaults to us. The two markets are separate: ids and filters differ.
US
string
Optional
Which listings to return: on_sale (default) or sold.
example
integer
Optional
Listing page, 30 per page. Defaults to 1.
1
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
success
{
"data": {
"market": "us",
"seller": {
"id": 207052431,
"name": "donburgundy01",
"rating_count": 81
},
"listings": {
"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
}
],
"total": 1,
"has_next": false,
"per_page": 30,
"total_is_capped": false
}
},
"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": {
"id": [
"Send the numeric seller id, for example 306933034."
]
},
"message": "The request validation failed"
}Not Found
The seller does not exist or is not public. This response is not billable.
{
"error": {
"code": "not_found",
"message": "Mercari has no public listing or seller for this id."
},
"success": false
}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.