MarketplaceAPI

class minim.api.discogs.MarketplaceAPI(client: APIClient, /)[source]

Bases: DiscogsResourceAPI

Marketplace API endpoints for the Discogs API.

Important

This class is managed by DiscogsAPIClient and should not be instantiated directly.

Parameters:
clientminim.api._shared.APIClient

API client instance used to make HTTP requests.

Methods

create_listing

Marketplace > New Listing: Create a marketplace listing.

delete_listing

Marketplace > Listing > Delete a Listing: Delete a marketplace listing.

get_listing

Marketplace > Listing > Get Listing: Get Discogs resource information for a marketplace listing.

get_my_orders

Marketplace > List Orders: Get Discogs resource information for the current user's marketplace orders.

get_order

Marketplace > Order > Get Order: Get Discogs resource information for a marketplace order.

get_order_messages

Marketplace > List Order Messages > List Order Messages: Get the communication history for a marketplace order.

get_release_marketplace_stats

Marketplace > Release Statistics: Get marketplace statistics for a release.

get_release_price_suggestions

Marketplace > Price Suggestions: Get suggested pricing information for a release.

get_selling_fee

Marketplace > Fee: Get the marketplace selling fee for a specified price․ Marketplace > Fee with Currency: Get the marketplace selling fee in a particular currency for a specified price.

get_user_inventory

Marketplace > Inventory: Get Discogs resource information for a user's marketplace inventory.

post_order_message

Marketplace > List Order Messages > Add New Message: Post a new message to and/or update the status for a marketplace order.

update_listing

Marketplace > Listing > Edit a Listing: Update a marketplace listing.

update_order

Marketplace > Order > Edit an Order: Update a marketplace order.
create_listing(release_id: int | str, /, media_condition: str, price: float, *, allow_offers: bool | None = None, private_notes: str | None = None, public_notes: str | None = None, status: str | None = None, shipping_count: int | str | None = None, storage_location: str | None = None, sleeve_condition: str | None = None, weight: int | str | None = None) → dict[str, Any][source]

Marketplace > New Listing: Create a marketplace listing.

User authentication

User authentication

Access protected endpoints.

Parameters:
release_idint or str; positional-only

Discogs ID of the release.

Examples: 772347, "7781525".

media_conditionstr

Media condition.

Valid values: "Mint (M)", "Near Mint (NM or M-)", "Very Good Plus (VG+)", "Very Good (VG)", "Good Plus (G+)", "Good (G)", "Fair (F)", "Poor (P)".

pricefloat

Listing price.

allow_offersbool; keyword-only; optional

Whether to accept offers for the listed item.

API default: False.

private_notesstr; keyword-only; optional

Private comments (e.g., external IDs) that are visible to only the seller.

public_notesstr; keyword-only; optional

Public comments (e.g., item condition) that are displayed to the buyers.

statusstr; keyword-only; optional

Listing status.

Valid values: "Draft", "For Sale".

API default: "For Sale".

shipping_countint or str; keyword-only; optional

Number of items the listing counts as for the purpose of calculating the shipping cost. Use "auto" to automatically estimate the quantity.

API default: "auto".

storage_locationstr; keyword-only; optional

Identifier for the item’s physical storage location that is visible to only the seller.

sleeve_conditionstr; keyword-only; optional

Sleeve condition.

Valid values: "Mint (M)", "Near Mint (NM or M-)", "Very Good Plus (VG+)", "Very Good (VG)", "Good Plus (G+)", "Good (G)", "Fair (F)", "Poor (P)", "Generic", "Not Graded", "No Cover".

weightint or str; keyword-only; optional

Weight of the item in grams for the purpose of calculating the shipping cost. Use "auto" to automatically estimate the value.

API default: "auto".

Returns:
listingdict[str, Any]

Discogs metadata for the newly created listing.

Sample response

{
  "listing_id": <int>,
  "resource_url": <str>
}
delete_listing(listing_id: int | str, /) → None[source]

Marketplace > Listing > Delete a Listing: Delete a marketplace listing.

User authentication

User authentication

Access protected endpoints.

Parameters:
listing_idint or str; positional-only

Discogs ID of the listing.

Examples: 172723812, "2983532888".

get_listing(listing_id: int | str, /, *, currency: str | None = None) → dict[str, Any][source]

Marketplace > Listing > Get Listing: Get Discogs resource information for a marketplace listing.

User authentication

User authentication

Access the in_cart key if authenticated, and the weight, format_quantity, external_id, location, and quantity keys if authenticated as the listing’s owner.

Parameters:
listing_idint or str; positional-only; optional

Discogs ID of the listing.

Examples: 172723812, "2983532888".

currencystr; keyword-only; optional

Currency for marketplace data.

Valid values: "USD", "GBP", "EUR", "CAD", "AUD", "JPY", "CHF", "MXN", "BRL", "NZD", "SEK", "ZAR".

Returns:
listingdict[str, Any]

Discogs metadata for the listing.

Sample response

{
  "allow_offers": <bool>,
  "audio": <bool>,
  "comments": <str>,
  "condition": <str>,
  "id": <int>,
  "original_price": {
    "curr_abbr": <str>,
    "curr_id": <int>,
    "formatted": <str>,
    "value": <float>
  },
  "original_shipping_price": {
    "curr_abbr": <str>,
    "curr_id": <int>,
    "formatted": <str>,
    "value": <float>
  },
  "posted": <str>,
  "price": {
    "currency": <str>,
    "value": <float>
  },
  "release": {
    "catalog_number": <str>,
    "description": <str>,
    "id": <int>,
    "resource_url": <str>,
    "thumbnail": <str>,
    "year": <int>
  },
  "resource_url": <str>,
  "seller": {
    "avatar_url": <str>,
    "payment": <str>,
    "resource_url": <str>,
    "shipping": <str>,
    "stats": {
      "rating": <str>,
      "stars": <float>,
      "total": <int>
    },
    "url": <str>,
    "username": <str>
  },
  "shipping_price": {
    "currency": <str>,
    "value": <float>
  },
  "ships_from": <str>,
  "sleeve_condition": <str>,
  "status": <str>,
  "uri": <str>
}
get_my_orders(*, status: str | None = None, created_after: str | datetime | None = None, created_before: str | datetime | None = None, archived: bool | None = None, limit: int | None = None, page: int | None = None, sort_by: str | None = None, descending: bool | None = None) → dict[str, Any][source]

Marketplace > List Orders: Get Discogs resource information for the current user’s marketplace orders.

User authentication

User authentication

Access protected endpoints.

Parameters:
statusstr; keyword-only; optional

Order status to filter by.

Valid values: "All", "New Order", "Buyer Contacted", "Invoice Sent", "Payment Pending", "Payment Received", "In Progress", "Shipped", "Merged", "Order Changed", "Refund Sent", "Cancelled (Non-Paying Buyer)", "Cancelled (Item Unavailable)", "Cancelled (Per Buyer's Request)", "Cancelled (Refund Received)".

created_afterstr or datetime.datetime; keyword-only; optional

Only return orders created after this date, in YYYY-MM-DDTHH:MM:SSZ format.

created_beforestr or datetime.datetime; keyword-only; optional

Only return orders created before this date, in YYYY-MM-DDTHH:MM:SSZ format.

archivedbool; keyword-only; optional

Whether to only include archived orders.

limitint; keyword-only; optional

Maximum number of orders to return.

Valid range: 1 to 100.

API default: 50.

pageint; keyword-only; optional

Page number. Use with limit to get the next page of orders.

Minimum value: 1.

API default: 1.

sort_bystr; keyword-only; optional

Field to sort the returned orders by.

Valid values: "id", "buyer", "created", "status", "last_activity".

descendingbool; keyword-only; optional

Whether to sort in descending order.

Returns:
ordersdict[str, Any]

Page of Discogs metadata for the current user’s orders.

Sample response

{
  "orders": [
    {
      "additional_instructions": <str>,
      "archived": <bool>,
      "buyer": {
        "id": <int>,
        "resource_url": <str>,
        "username": <str>
      },
      "created": <str>,
      "fee": {
        "currency": <str>,
        "value": <float>
      },
      "id": <str>,
      "items": [
        {
          "id": <int>,
          "media_condition": <str>,
          "price": {
            "currency": <str>,
            "value": <float>
          },
          "release": {
            "description": <str>,
            "id": <int>
          },
          "sleeve_condition": <str>
        }
      ],
      "last_activity": <str>,
      "messages_url": <str>,
      "next_status": <list[str]>,
      "resource_url": <str>,
      "seller": {
        "id": <int>,
        "resource_url": <str>,
        "username": <str>
      },
      "shipping": {
        "currency": <str>,
        "method": <str>,
        "value": <float>
      },
      "shipping_address": <str>,
      "status": <str>,
      "total": {
        "currency": <str>,
        "value": <float>
      },
      "uri": <str>
    }
  ],
  "pagination": {
    "items": <int>,
    "page": <int>,
    "pages": <int>,
    "per_page": <int>,
    "urls": {
      "first": <str>,
      "last": <str>,
      "next": <str>,
      "prev": <str>
    }
  }
}
get_order(order_id: str, /) → dict[str, Any][source]

Marketplace > Order > Get Order: Get Discogs resource information for a marketplace order.

User authentication

User authentication

Access protected endpoints.

Parameters:
order_idstr; positional-only

Discogs ID of the order.

Example: "1-1".

Returns:
orderdict[str, Any]

Discogs metadata for the order.

Sample response

{
  "additional_instructions": <str>,
  "archived": <bool>,
  "buyer": {
    "id": <int>,
    "resource_url": <str>,
    "username": <str>
  },
  "created": <str>,
  "fee": {
    "currency": <str>,
    "value": <float>
  },
  "id": <str>,
  "items": [
    {
      "id": <int>,
      "media_condition": <str>,
      "price": {
        "currency": <str>,
        "value": <float>
      },
      "release": {
        "description": <str>,
        "id": <int>
      },
      "sleeve_condition": <str>
    }
  ],
  "last_activity": <str>,
  "messages_url": <str>,
  "next_status": <list[str]>,
  "resource_url": <str>,
  "seller": {
    "id": <int>,
    "resource_url": <str>,
    "username": <str>
  },
  "shipping": {
    "currency": <str>,
    "method": <str>,
    "value": <float>
  },
  "shipping_address": <str>,
  "status": <str>,
  "total": {
    "currency": <str>,
    "value": <float>
  },
  "uri": <str>
}
get_order_messages(order_id: str, /, *, limit: int | None = None, page: int | None = None) → dict[str, Any][source]

Marketplace > List Order Messages > List Order Messages: Get the communication history for a marketplace order.

User authentication

User authentication

Access protected endpoints.

Parameters:
order_idstr; positional-only

Discogs ID of the order.

Example: "1-1".

limitint; keyword-only; optional

Maximum number of messages to return.

Valid range: 1 to 100.

API default: 50.

pageint; keyword-only; optional

Page number. Use with limit to get the next page of messages.

Minimum value: 1.

API default: 1.

Returns:
messagesdict[str, Any]

Page of Discogs metadata for the order’s messages.

Sample response

{
  "from": {
    "resource_url": <str>,
    "username": <str>
  },
  "message": <str>,
  "order": {
    "id": <str>,
    "resource_url": <str>
  },
  "subject": <str>,
  "timestamp": <str>
}
get_release_marketplace_stats(release_id: int | str, /, *, currency: str | None = None) → dict[str, Any][source]

Marketplace > Release Statistics: Get marketplace statistics for a release.

Parameters:
release_idint or str; positional-only

Discogs ID of the release.

Examples: 772347, "7781525".

currencystr; keyword-only; optional

Currency.

Valid values: "USD", "GBP", "EUR", "CAD", "AUD", "JPY", "CHF", "MXN", "BRL", "NZD", "SEK", "ZAR".

Returns:
marketplace_statsdict[str, Any]

Release’s marketplace statistics.

Sample response

{
  "blocked_from_sale": <bool>,
  "lowest_price": {
    "currency": <str>,
    "value": <float>
  },
  "num_for_sale": <int>
}
get_release_price_suggestions(release_id: int | str, /) → dict[str, Any][source]

Marketplace > Price Suggestions: Get suggested pricing information for a release.

User authentication

User authentication

Access protected endpoints.

Parameters:
release_idint or str; positional-only

Discogs ID of the release.

Examples: 772347, "7781525".

Returns:
price_suggestionsdict[str, Any]

Release’s suggested prices by media condition.

Sample response

{
  "Very Good (VG)": {
    "currency": <str>,
    "value": <float>
  },
  "Good Plus (G+)": {
    "currency": <str>,
    "value": <float>
  },
  "Near Mint (NM or M-)": {
    "currency": <str>,
    "value": <float>
  },
  "Good (G)": {
    "currency": <str>,
    "value": <float>
  },
  "Very Good Plus (VG+)": {
    "currency": <str>,
    "value": <float>
  },
  "Mint (M)": {
    "currency": <str>,
    "value": <float>
  },
  "Fair (F)": {
    "currency": <str>,
    "value": <float>
  },
  "Poor (P)": {
    "currency": <str>,
    "value": <float>
  }
}
get_selling_fee(price: float, /, currency: str | None = None) → dict[str, Any][source]

Marketplace > Fee: Get the marketplace selling fee for a specified price․ Marketplace > Fee with Currency: Get the marketplace selling fee in a particular currency for a specified price.

Parameters:
pricefloat; positional-only

Item price.

currencystr; optional

Fee currency.

Valid values: "USD", "GBP", "EUR", "CAD", "AUD", "JPY", "CHF", "MXN", "BRL", "NZD", "SEK", "ZAR".

Returns:
feedict[str, Any]

Calculated marketplace selling fee.

Sample response: {"currency": <str>, "value": <float>}.

get_user_inventory(username: str | None = None, /, *, status: str | None = None, limit: int | None = None, page: int | None = None, sort_by: str | None = None, descending: bool | None = None) → dict[str, Any][source]

Marketplace > Inventory: Get Discogs resource information for a user’s marketplace inventory.

User authentication

User authentication

Access private listings and the weight, format_quantity, external_id, location, and quantity keys if authenticated as the requested user.

Parameters:
usernamestr; positional-only; optional

Username of the user. If not specified, the username of the current user is used. Only optional when authenticated.

Example: "rodneyfool".

statusstr; keyword-only; optional

Listing status to filter by.

Valid values: "All", "Deleted", "Draft", "Expired", "For Sale", "Sold", "Suspended", "Violation".

limitint; keyword-only; optional

Maximum number of listings to return.

Valid range: 1 to 100.

API default: 50.

pageint; keyword-only; optional

Page number. Use with limit to get the next page of listings.

Minimum value: 1.

API default: 1.

sort_bystr; keyword-only; optional

Field to sort the returned listings by.

Valid values: "listed", "price", "item", "artist", "label", "catno", "audio", "status", "location".

descendingbool; keyword-only; optional

Whether to sort in descending order.

Returns:
inventorydict[str, Any]

Page of Discogs metadata for the user’s marketplace inventory.

Sample responses

{
  "listings": [
    {
      "allow_offers": <bool>,
      "audio": <bool>,
      "comments": <str>,
      "condition": <str>,
      "id": <int>,
      "posted": <str>,
      "price": {
        "currency": <str>,
        "value": <float>
      },
      "release": {
        "artist": <str>,
        "catalog_number": <str>,
        "description": <str>,
        "format": <str>,
        "id": <int>,
        "resource_url":  <str>,
        "thumbnail": <str>,
        "title": <str>,
        "year": <int>
      },
      "resource_url": <str>,
      "seller": {
        "id": <int>,
        "resource_url": <str>,
        "username": <str>
      },
      "ships_from": <str>,
      "sleeve_condition": <str>,
      "status": <str>,
      "uri": <str>
    }
  ],
  "pagination": {
    "items": <int>,
    "page": <int>,
    "pages": <int>,
    "per_page": <int>,
    "urls": {
      "first": <str>,
      "last": <str>,
      "next": <str>,
      "prev": <str>
    }
  }
}
post_order_message(order_id: str, message: str | None = None, /, *, status: str | None = None) → dict[str, Any][source]

Marketplace > List Order Messages > Add New Message: Post a new message to and/or update the status for a marketplace order.

User authentication

User authentication

Access protected endpoints.

Important

At least one of message or status must be provided.

Parameters:
order_idstr; positional-only

Discogs ID of the order.

Example: "1-1".

messagestr; positional-only; optional

Order message.

statusstr; keyword-only; optional

Order status.

Note

If specified, message will be prepended with:

f"Seller changed status from {old_status} to {status}"

Valid values: "New Order", "Buyer Contacted", "Invoice Sent", "Payment Pending", "Payment Received", "In Progress", "Shipped", "Refund Sent", "Cancelled (Non-Paying Buyer)", "Cancelled (Item Unavailable)", "Cancelled (Per Buyer's Request)".

Returns:
messagedict[str, Any]

Discogs metadata for the order’s new message.

Sample response

{
  "from": {
    "resource_url": <str>,
    "username": <str>
  },
  "message": <str>,
  "order": {
    "id": <str>,
    "resource_url": <str>
  },
  "subject": <str>,
  "timestamp": <str>
}
update_listing(listing_id: int | str, /, *, allow_offers: bool | None = None, media_condition: str | None = None, price: float | None = None, private_notes: str | None = None, public_notes: str | None = None, status: str | None = None, shipping_count: int | str | None = None, storage_location: str | None = None, sleeve_condition: str | None = None, weight: int | str | None = None) → None[source]

Marketplace > Listing > Edit a Listing: Update a marketplace listing.

User authentication

User authentication

Access protected endpoints.

Parameters:
listing_idint or str; positional-only

Discogs ID of the listing.

Examples: 172723812, "2983532888".

allow_offersbool; keyword-only; optional

Whether to accept offers for the listed item.

API default: False.

media_conditionstr; keyword-only; optional

Media condition.

Valid values: "Mint (M)", "Near Mint (NM or M-)", "Very Good Plus (VG+)", "Very Good (VG)", "Good Plus (G+)", "Good (G)", "Fair (F)", "Poor (P)".

pricefloat; keyword-only; optional

Listing price.

private_notesstr; keyword-only; optional

Private comments (e.g., external IDs) that are visible to only the seller.

public_notesstr; keyword-only; optional

Public comments (e.g., item condition) that are displayed to the buyers.

statusstr; keyword-only; optional

Listing status.

Valid values: "Draft", "For Sale".

shipping_countint or str; keyword-only; optional

Number of items the listing counts as for the purpose of calculating the shipping cost. Use "auto" to automatically estimate the quantity.

storage_locationstr; keyword-only; optional

Identifier for the item’s physical storage location that is visible to only the seller.

sleeve_conditionstr; keyword-only; optional

Sleeve condition.

Valid values: "Mint (M)", "Near Mint (NM or M-)", "Very Good Plus (VG+)", "Very Good (VG)", "Good Plus (G+)", "Good (G)", "Fair (F)", "Poor (P)", "Generic", "Not Graded", "No Cover".

weightint or str; keyword-only; optional

Weight of the item in grams for the purpose of calculating the shipping cost. Use "auto" to automatically estimate the value.

update_order(order_id: str, /, *, status: str | None = None, shipping_fee: float | None = None) → dict[str, Any][source]

Marketplace > Order > Edit an Order: Update a marketplace order.

User authentication

User authentication

Access protected endpoints.

Important

Exactly one of status or shipping_fee must be provided.

Note

Calling this method will send the buyer a message with the following content:

Seller changed status from {old_status} to {new_status}

See also

add_order_message() – Simultaneously add an order message and change the order status.

Parameters:
order_idstr; positional-only

Discogs ID of the order.

Example: "1-1".

statusstr; keyword-only; optional

Order status.

Valid values: "New Order", "Buyer Contacted", "Invoice Sent", "Payment Pending", "Payment Received", "In Progress", "Shipped", "Refund Sent", "Cancelled (Non-Paying Buyer)", "Cancelled (Item Unavailable)", "Cancelled (Per Buyer's Request)".

shipping_feefloat; keyword-only; optional

Shipping fee. If specified, the buyer is invoiced and the order status is set to Invoice Sent.

Returns:
orderdict[str, Any]

Discogs metadata for the updated order.

Sample response

{
  "additional_instructions": <str>,
  "archived": <bool>,
  "buyer": {
    "id": <int>,
    "resource_url": <str>,
    "username": <str>
  },
  "created": <str>,
  "fee": {
    "currency": <str>,
    "value": <float>
  },
  "id": <str>,
  "items": [
    {
      "id": <int>,
      "media_condition": <str>,
      "price": {
        "currency": <str>,
        "value": <float>
      },
      "release": {
        "description": <str>,
        "id": <int>
      },
      "sleeve_condition": <str>
    }
  ],
  "last_activity": <str>,
  "messages_url": <str>,
  "next_status": <list[str]>,
  "resource_url": <str>,
  "seller": {
    "id": <int>,
    "resource_url": <str>,
    "username": <str>
  },
  "shipping": {
    "currency": <str>,
    "method": <str>,
    "value": <float>
  },
  "shipping_address": <str>,
  "status": <str>,
  "total": {
    "currency": <str>,
    "value": <float>
  },
  "uri": <str>
}