# Discogs Marketplace API Documentation

<p><strong>Discogs Marketplace API Documentation</strong> 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.</p>

- **Documentation:** [https://scrappa.co/docs/discogs-api/discogs_marketplace](https://scrappa.co/docs/discogs-api/discogs_marketplace)
- **API group:** Discogs API
- **Endpoint:** `GET https://scrappa.co/api/discogs/marketplace`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `release_id` | integer | Yes | Discogs release id. Example: 249504. Take it from the search endpoint. |
| `condition` | string | No | Disc condition: mint, near_mint, very_good_plus, very_good, good_plus, good, fair, poor. |
| `sleeve_condition` | string | No | Sleeve condition: the media values plus generic, not_graded and no_cover. |
| `currency` | string | No | Only listings priced in this currency: USD, EUR, GBP, AUD, CAD, JPY, CHF, MXN, BRL, NZD, SEK or ZAR. |
| `ships_from` | string | No | 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. |
| `limit` | integer | No | Listings per answer, 1 to 50. Default: 25. |
| `cursor` | string | No | The next_cursor value of the previous answer. Leave it out for the first page. |

## Example response

```json
{
    "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

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A query parameter is missing or invalid. This response is not billable. |
| 503 | Service Unavailable | Discogs could not be reached, refused the request or changed its answer. This response is not billable. Retry later. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)