Ricardo Listing Detail API Documentation Retrieve one Ricardo.ch listing: title, web url, offer type, status (open or closed), condition label, start and end date (ISO 8601, UTC), buy-now price, current bid, minimum next bid and bid increment for auctions, bid count, available quantity, description as HTML and plain text, images (largest size), category breadcrumb, shipping options, payment methods, attributes and the seller with rating in percent. All prices are CHF numbers. Ended auctions return status closed with the final bid. An unknown listing id answers a non-billable 404.
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.
1 optional filter available.
string
Required
Ricardo listing number of 6 to 12 digits, e.g. 1320000000. Take it from the id field of a search result.
1234567890
string
Optional
Language of labels and the listing url: de or fr. Defaults to de.
en
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
meta
success
{
"data": {
"id": "1320000000",
"url": "https://www.ricardo.ch/de/a/1320000000/",
"title": "IWC Porsche Design Titanium, Vintage,automatic",
"images": [
{
"url": "https://img.ricardostatic.ch/images/765c8f11-91d2-4f89-842d-476bcd062786/t_1800x1350"
},
{
"url": "https://img.ricardostatic.ch/images/39005c87-4126-4a84-9aa5-3d76a9231cea/t_1800x1350"
},
{
"url": "https://img.ricardostatic.ch/images/dc4784d8-2755-4d5e-8acb-45b133974cf7/t_1800x1350"
}
],
"seller": {
"id": "408769950",
"city": "Grand-Lancy",
"country": "CH",
"nickname": "Montre-Swiss",
"zip_code": "1212",
"rating_percent": 99.4,
"profile_picture_url": "https://img.ricardostatic.ch/images/6bbad529-49c0-4c4f-8061-3c29d262b2ef/t_250"
},
"status": "closed",
"currency": "CHF",
"end_date": "2026-07-27T10:58:47Z",
"attributes": [
{
"name": "Gespartes CO\u2082e",
"values": [
"9 kg"
]
},
{
"name": "Material",
"values": [
"Titanium"
]
},
{
"name": "Farbe",
"values": [
"Andere"
]
}
],
"bids_count": 1,
"categories": [
{
"name": "Uhren & Schmuck",
"category_id": "42272"
},
{
"name": "Uhren",
"category_id": "81990"
}
],
"offer_type": "auction_with_buynow",
"start_date": "2026-07-27T10:42:00Z",
"current_bid": 420,
"bid_increment": 1,
"buy_now_price": 420,
"condition_label": "Gebraucht",
"payment_methods": [
"cash",
"bank"
],
"description_html": "<p>IWC Porsche Design, une montre automatique d'occasion en titane pour homme. Un classique intemporel! Cette montre combine l'\u00e9l\u00e9gance et la robustesse. Parfaite pour un usage quotidien ou pour les collectionneurs. Son design distinctif ne manquera pas d'attirer l'attention. movement authentic top cualite.. fonction parfaitement.. magnifique cadran noir..avec date rapide.. bracelet neuf,anti allergies..</p><p>boucle d'origine iwc Porsche Design..</p><p>en bonne \u00e9tat g\u00e9n\u00e9ral voir photo..</p><p>vondu avec un bo\u00eete neuf pour protection..</p><p>Une opportunit\u00e9 \u00e0 ne pas manquer!</p>",
"description_text": "IWC Porsche Design, une montre automatique d'occasion en titane pour homme. Un classique intemporel! Cette montre combine l'\u00e9l\u00e9gance et la robustesse. Parfaite pour un usage quotidien ou pour les collectionneurs. Son design distinctif ne manquera pas d'attirer l'attention. movement authentic top cualite.. fonction parfaitement.. magnifique cadran noir..avec date rapide.. bracelet neuf,anti allergies..\nboucle d'origine iwc Porsche Design..\nen bonne \u00e9tat g\u00e9n\u00e9ral voir photo..\nvondu avec un bo\u00eete neuf pour protection..\nUne opportunit\u00e9 \u00e0 ne pas manquer!",
"shipping_options": [
{
"method": "get_by_buyer",
"pickup": true
},
{
"cost": 6.7,
"method": "letter_a_b5_500g_5cm"
}
]
},
"meta": {
"billable": true,
"endpoint_family": "listing"
},
"success": true
}Errors
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
The id is missing or not a listing number of 6 to 12 digits. This response is not billable.
{
"errors": {
"id": [
"The id must be a Ricardo listing number of 6 to 12 digits."
]
},
"message": "The request validation failed"
}Resource Not Found
The listing does not exist. This response is not billable.
{
"error": {
"code": "NOT_FOUND",
"message": "The requested Ricardo resource was not found."
},
"success": false
}Invalid Source Response
Ricardo answered with a response Scrappa could not read. This response is not billable.
{
"error": {
"code": "PARSER_DRIFT",
"message": "Ricardo returned a response Scrappa could not read. Please retry later."
},
"success": false
}Service Unavailable
The upstream service is temporarily unavailable. Please retry shortly.
{
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "The Ricardo API is temporarily unavailable. Please retry."
},
"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.