Discogs Marketplace API Documentation List the items for sale of one release, cheapest first. Each listing has its id and url, the asking price in the currency of the seller (price) and the price in the currency Discogs shows the buyer (buyer_price), shipping price in both, media and sleeve condition with the Discogs label, the seller notes, the listing date, photos, availability, a flag for offers and a flag for deals. The seller block has the name, id, rating in percent, rating count, ships-from country and independent seller flag. The release block has title, artists, labels, catalog numbers and format. The answer also has the total count and counts per condition, currency and ships-from country. Filters are applied by Discogs: condition and sleeve_condition (media: mint, near_mint, very_good_plus, very_good, good_plus, good, fair, poor; sleeve also generic, not_graded, no_cover), currency (lists only items priced in that currency), ships_from (country name as in ships_from facet counts, for example United Kingdom). Prices of different currencies are never mixed up: every price has its own currency. Paging uses a cursor: send next_cursor of the previous answer as cursor. A page parameter is rejected. Sorting is by price, lowest first. Sold prices, suggested prices and sold history need a Discogs login and are not available. Cost: 1 credit per answer with listings. A release with no listings answers 200 with total_count 0 and costs nothing.
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.
6 optional filters available.
integer
Required
Discogs release id. Example: 249504. Take it from the search endpoint.
1234567890
string
Optional
Disc condition: mint, near_mint, very_good_plus, very_good, good_plus, good, fair, poor.
example
string
Optional
Sleeve condition: the media values plus generic, not_graded and no_cover.
example
string
Optional
Only listings priced in this currency: USD, EUR, GBP, AUD, CAD, JPY, CHF, MXN, BRL, NZD, SEK or ZAR.
USD
string
Optional
Only sellers that ship from this country, written as Discogs does, for example United Kingdom or Italy. A country with no listing returns total_count 0.
example
integer
Optional
Listings per answer, 1 to 50. Default: 25.
10
string
Optional
The next_cursor value of the previous answer. Leave it out for the first page.
0
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
meta
success
{
"data": {
"count": 2,
"facets": {
"currency": [
{
"count": 115,
"value": "GBP"
},
{
"count": 19,
"value": "EUR"
}
],
"condition": [
{
"count": 47,
"value": "Very Good Plus (VG+)"
},
{
"count": 33,
"value": "Mint (M)"
}
],
"ships_from": [
{
"count": 113,
"value": "United Kingdom"
},
{
"count": 5,
"value": "Italy"
}
],
"sleeve_condition": [
{
"count": 35,
"value": "Very Good (VG)"
},
{
"count": 33,
"value": "Very Good Plus (VG+)"
}
]
},
"listings": [
{
"id": 3528577817,
"url": "https://www.discogs.com/sell/item/3528577817",
"notes": "Hairline marks, small scuffs on the disk ***due to my ultrasonic cleaner being broken, I am unable to clean them efficiently***",
"price": {
"amount": 0.5,
"currency": "GBP"
},
"seller": {
"id": 19575559,
"username": "Horus-XVI",
"avatar_url": "https://i.discogs.com/vSDy4wJtUxPFiQmAHOQNzFCCgSkGEBT_dV0nxB2U3H8/rs:fill/g:sm/q:40/h:300/w:300/czM6Ly9kaXNjb2dz/LXVzZXItYXZhdGFy/cy9VLTE5NTc1NTU5/LTE3MzkwODg4Njgu/anBlZw.jpeg",
"ships_from": "United Kingdom",
"independent": false,
"rating_count": 133,
"rating_percent": 99.2481
},
"is_deal": false,
"release": {
"id": 249504,
"title": "Never Gonna Give You Up",
"format": "Vinyl",
"labels": [
{
"id": 895,
"name": "RCA",
"role": "LABEL",
"catalog_number": "PB 41447"
},
{
"id": 82835,
"name": "BMG Records (UK) Ltd.",
"role": "PHONOGRAPHIC_COPYRIGHT"
},
{
"id": 82835,
"name": "BMG Records (UK) Ltd.",
"role": "COPYRIGHT"
},
{
"id": 301937,
"name": "Pete Waterman Ltd.",
"role": "PHONOGRAPHIC_COPYRIGHT"
},
{
"id": 273945,
"name": "All Boys Music Ltd.",
"role": "PUBLISHED_BY"
},
{
"id": 26385,
"name": "BMG Records",
"role": "DISTRIBUTED_BY"
},
{
"id": 33652,
"name": "BMG Ariola",
"role": "DISTRIBUTED_BY"
},
{
"id": 29656,
"name": "RCA Records",
"role": "MARKETED_BY"
},
{
"id": 266218,
"name": "Utopia Studios",
"role": "LACQUER_CUT_AT"
},
{
"id": 82835,
"name": "BMG Records (UK) Ltd.",
"role": "LICENSED_TO"
},
{
"id": 30024,
"name": "PWL",
"role": "RECORD_COMPANY"
},
{
"id": 553982,
"name": "CBS Pressing Plant, Aston Clinton",
"role": "PRESSED_BY"
}
],
"artists": [
"Rick Astley"
],
"country": "UK",
"released": "1987-07-00",
"image_url": "https://i.discogs.com/ogv0j2FCgzO0Ihhl9HyUITpMYif3qabIMpaGUx_n3SM/rs:fit/g:sm/q:40/h:300/w:300/czM6Ly9kaXNjb2dz/LWRhdGFiYXNlLWlt/YWdlcy9SLTI0OTUw/NC0xMzM0NTkyMjEy/LmpwZWc.jpeg",
"recording_types": [
"Single"
],
"format_description": "7\""
},
"shipping": {
"price": {
"amount": 18.6,
"currency": "GBP"
},
"buyer_price": {
"amount": 22.37,
"currency": "EUR"
}
},
"available": true,
"condition": {
"media": "Very Good (VG)",
"sleeve": "No Cover",
"media_key": "very_good",
"sleeve_key": "no_cover"
},
"listed_at": "2025-06-01T12:00:02+00:00",
"buyer_price": {
"amount": 0.6,
"currency": "EUR"
},
"accepts_offers": true
}
],
"release_id": 249504,
"next_cursor": "WzAuNjY2NjY1LCAzNzYxMjUxNzY1XQ==",
"total_count": 138
},
"meta": {
"credits": 1,
"billable": true,
"endpoint_family": "marketplace"
},
"success": true
}Errors
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
A query parameter is missing or invalid. This response is not billable.
{
"errors": {
"condition": [
"The condition is one of mint, near_mint, very_good_plus, very_good, good_plus, good, fair, poor."
]
},
"message": "The request validation failed"
}Service Unavailable
Discogs could not be reached, refused the request or changed its answer. This response is not billable. Retry later.
{
"meta": {
"billable": false,
"retryable": true,
"endpoint_family": "marketplace"
},
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "The Discogs 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.