search

Search the WAXED vinyl marketplace and catalog. Returns mixed results (records, artists, stores, labels, genres, crates) ranked by relevance. Record results include listing counts and minimum price when copies are for sale. Catalog numbers also match.

Parameters2

query	string	required	Free-text search, e.g. an artist, album title, or label.
limit	integer	optional	Max results (default 20).

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Free-text search, e.g. an artist, album title, or label."
    },
    "limit": {
      "type": "integer",
      "description": "Max results (default 20).",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "query"
  ]
}

get_release

Get full detail for a release by its Discogs release id: artist, title, year, label, formats, genres/styles, cover art, other pressings/versions of the same master, and every copy currently for sale on WAXED with price, media/sleeve condition, and seller info. Prices are in USD cents.

Parameters1

release_id

string

required

Discogs release id, e.g. "249504".

Raw schema

{
  "type": "object",
  "properties": {
    "release_id": {
      "type": "string",
      "description": "Discogs release id, e.g. \"249504\"."
    }
  },
  "required": [
    "release_id"
  ]
}

browse_marketplace

Browse active vinyl listings on WAXED with filters. Returns paginated listings with title, artist, price (USD cents), condition, genre, year, format, and cover art.

Parameters4

genre	string	optional	Filter by genre, e.g. "Jazz".
format	string	optional	Filter by format, e.g. "LP".
sort	string	optional	Sort order; "newest" (default) or price-based sorts.
page	integer	optional	Zero-based page number (48 per page).

Raw schema

{
  "type": "object",
  "properties": {
    "genre": {
      "type": "string",
      "description": "Filter by genre, e.g. \"Jazz\"."
    },
    "format": {
      "type": "string",
      "description": "Filter by format, e.g. \"LP\"."
    },
    "sort": {
      "type": "string",
      "description": "Sort order; \"newest\" (default) or price-based sorts."
    },
    "page": {
      "type": "integer",
      "description": "Zero-based page number (48 per page).",
      "minimum": 0
    }
  }
}

get_price_estimate

Estimate the market price (USD) of a release by Discogs release id, optionally adjusted for media condition (1=Poor … 5=Mint) and buyer country. Returns price_usd, confidence tier, and the adjustment factors used.

Parameters3

release_id	string	required	Discogs release id.
condition	integer	optional	Media condition 1–5 (5 = Mint).
country	string	optional	ISO country code for geo pricing, e.g. "US".

Raw schema

{
  "type": "object",
  "properties": {
    "release_id": {
      "type": "string",
      "description": "Discogs release id."
    },
    "condition": {
      "type": "integer",
      "description": "Media condition 1–5 (5 = Mint).",
      "minimum": 1,
      "maximum": 5
    },
    "country": {
      "type": "string",
      "description": "ISO country code for geo pricing, e.g. \"US\"."
    }
  },
  "required": [
    "release_id"
  ]
}

get_price_history

Get real historical sales for a release by Discogs release id: individual past sales (price, currency, date, condition) plus aggregate stats and the Discogs low/median/high range. mode "exact" = this pressing only; "all_versions" = every pressing of the master.

Parameters2

release_id	string	required	Discogs release id.
mode	string	optional	Default "exact".

Raw schema

{
  "type": "object",
  "properties": {
    "release_id": {
      "type": "string",
      "description": "Discogs release id."
    },
    "mode": {
      "type": "string",
      "enum": [
        "exact",
        "all_versions"
      ],
      "description": "Default \"exact\"."
    }
  },
  "required": [
    "release_id"
  ]
}

get_store

Get a WAXED dealer storefront by store slug, username, or profile id: store profile, follower stats, and its active listings (paginated, prices in USD cents).

Parameters3

slug	string	required	Store slug (from waxed.market/stores/<slug>), username, or profile UUID.
limit	integer	optional	Max listings (default 48, max 100).
offset	integer	optional	Pagination offset.

Raw schema

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Store slug (from waxed.market/stores/<slug>), username, or profile UUID."
    },
    "limit": {
      "type": "integer",
      "description": "Max listings (default 48, max 100).",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "type": "integer",
      "description": "Pagination offset.",
      "minimum": 0
    }
  },
  "required": [
    "slug"
  ]
}

get_shared_wishlist

Read a publicly shared WAXED want-list by its share token: the wants (artist/title/label/year) and which of them currently have copies for sale on WAXED with prices.

Parameters1

token

string

required

Share token from a waxed.market/wishlist/<token> link.

Raw schema

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "Share token from a waxed.market/wishlist/<token> link."
    }
  },
  "required": [
    "token"
  ]
}

get_artist

Get a WAXED artist page by name: bio, verified flag, tags, full discography, and copies currently for sale on WAXED with prices in USD cents.

Parameters2

name	string	required	Artist name, e.g. "Miles Davis".
limit	integer	optional	Max listings (default 48, max 100).

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Artist name, e.g. \"Miles Davis\"."
    },
    "limit": {
      "type": "integer",
      "description": "Max listings (default 48, max 100).",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "name"
  ]
}

get_label

Get a WAXED record label page by name: profile/bio, sublabels, full discography, and copies currently for sale on WAXED with prices in USD cents.

Parameters2

name	string	required	Label name, e.g. "Blue Note".
limit	integer	optional	Max listings (default 48, max 100).

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Label name, e.g. \"Blue Note\"."
    },
    "limit": {
      "type": "integer",
      "description": "Max listings (default 48, max 100).",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "name"
  ]
}

get_crate

Get a WAXED crate by id: a dealer-curated bundle of records sold together. Returns the full item list (each record with artist, title, release id, and price), the total bundle price in USD cents, item count, genres, and the country the crate ships from.

Parameters1

id

string

required

Crate id (marketplace listing id or bundle_crate_id).

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Crate id (marketplace listing id or bundle_crate_id)."
    }
  },
  "required": [
    "id"
  ]
}

discogs_search

Search the full Discogs catalog via WAXED's proxy — at least one param required. Use for finding the right release/version to list or match, e.g. before create_listing or update_listing's discogs_release_id rematch.

Parameters7

q	string	optional	Free-text search, e.g. an artist, album title, or catalog number.
genre	string	optional	Filter by genre, e.g. "Jazz".
year_from	integer	optional	Earliest release year, inclusive.
year_to	integer	optional	Latest release year, inclusive.
format	string	optional	Filter by format, e.g. "LP".
limit	integer	optional	Max results per page.
page	integer	optional	Zero-based page number.

Raw schema

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "Free-text search, e.g. an artist, album title, or catalog number."
    },
    "genre": {
      "type": "string",
      "description": "Filter by genre, e.g. \"Jazz\"."
    },
    "year_from": {
      "type": "integer",
      "description": "Earliest release year, inclusive."
    },
    "year_to": {
      "type": "integer",
      "description": "Latest release year, inclusive."
    },
    "format": {
      "type": "string",
      "description": "Filter by format, e.g. \"LP\"."
    },
    "limit": {
      "type": "integer",
      "description": "Max results per page.",
      "minimum": 1
    },
    "page": {
      "type": "integer",
      "description": "Zero-based page number.",
      "minimum": 0
    }
  }
}

lookup_barcode

Scan-to-list: resolve a UPC/EAN barcode to a Discogs release id, title, artist, and year via WAXED's proxy. Use the result for create_listing or update_listing's discogs_release_id rematch.

Parameters1

barcode

string

required

UPC/EAN barcode, 8–14 digits.

Raw schema

{
  "type": "object",
  "properties": {
    "barcode": {
      "type": "string",
      "description": "UPC/EAN barcode, 8–14 digits."
    }
  },
  "required": [
    "barcode"
  ]
}

my_listings

List the authenticated dealer's own marketplace listings (requires an agent key). Returns a compact projection per listing: id, title, artist, price (USD cents), status, condition, sleeve_condition, quantity, discogs_release_id, created_at, sync_state ('listed'/'unlisted'/'removed'/null — the listing's cross-platform sync state; null when the dealer doesn't sync externally). Optionally filter by status and cap the count.

Parameters2

status	string	optional	Filter to this listing status, e.g. 'active', 'removed', 'sold', 'collection'.
limit	integer	optional	Max listings to return.

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Filter to this listing status, e.g. 'active', 'removed', 'sold', 'collection'."
    },
    "limit": {
      "type": "integer",
      "description": "Max listings to return.",
      "minimum": 1,
      "maximum": 500
    }
  }
}

create_listing

Create a new marketplace listing for the authenticated dealer (requires an agent key). price_cents is an integer number of USD cents (e.g. 1500 = $15.00); active listings require at least 50 cents. condition and sleeve_condition are Goldmine grades: 'Mint', 'Near Mint', 'VG+', 'VG', 'Good+', 'Good', 'Fair', 'Poor' (sleeve_condition also accepts 'Generic' for a plain/missing jacket). status defaults to 'active' (for sale); use 'collection' for a non-selling catalog entry.

Parameters9

title	string	required	Release title.
artist	string	required	Artist name.
price_cents	integer	required	Price in USD cents. Minimum 50 for active listings.
condition	string	required	Media (vinyl) condition, Goldmine grade.
discogs_release_id	string	optional	Optional Discogs release id to link this listing to.
sleeve_condition	string	optional	Sleeve condition, Goldmine grade or 'Generic'.
description	string	optional	Optional free-text listing description (max 5000 chars).
status	string	optional	'active' (for sale, default) or 'collection' (not for sale).
quantity	integer	optional	Number of copies available.

Raw schema

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Release title."
    },
    "artist": {
      "type": "string",
      "description": "Artist name."
    },
    "price_cents": {
      "type": "integer",
      "description": "Price in USD cents. Minimum 50 for active listings.",
      "minimum": 0
    },
    "condition": {
      "type": "string",
      "enum": [
        "Mint",
        "Near Mint",
        "VG+",
        "VG",
        "Good+",
        "Good",
        "Fair",
        "Poor"
      ],
      "description": "Media (vinyl) condition, Goldmine grade."
    },
    "discogs_release_id": {
      "type": "string",
      "description": "Optional Discogs release id to link this listing to."
    },
    "sleeve_condition": {
      "type": "string",
      "enum": [
        "Mint",
        "Near Mint",
        "VG+",
        "VG",
        "Good+",
        "Good",
        "Fair",
        "Poor",
        "Generic"
      ],
      "description": "Sleeve condition, Goldmine grade or 'Generic'."
    },
    "description": {
      "type": "string",
      "description": "Optional free-text listing description (max 5000 chars)."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "collection"
      ],
      "description": "'active' (for sale, default) or 'collection' (not for sale)."
    },
    "quantity": {
      "type": "integer",
      "description": "Number of copies available.",
      "minimum": 0
    }
  },
  "required": [
    "title",
    "artist",
    "price_cents",
    "condition"
  ]
}

update_listing

Update fields on one of the authenticated dealer's existing listings (requires an agent key). Only provided fields are changed. price_cents is an integer number of USD cents; active listings require at least 50 cents. condition/sleeve_condition are Goldmine grades (sleeve_condition also accepts 'Generic'). This does not change listing status (delisted/relisted) — use set_listing_status for that — and does not cascade to Discogs or Square.

Parameters9

listing_id	string	required	The listing id to update.
price_cents	integer	optional	New price in USD cents.
condition	string	optional	Media condition, Goldmine grade.
sleeve_condition	string	optional	Sleeve condition, Goldmine grade or 'Generic'.
description	string	optional	Free-text listing description (max 5000 chars).
quantity	integer	optional	Number of copies available.
accept_offers	boolean	optional	Whether buyers can submit offers below the listed price.
location	string	optional	Storage/location note for the dealer.
discogs_release_id	string	optional	Rematch this listing to a different pressing/version (get_release returns versions[] to choose from). Numeric Discogs release id. Blocked for Discogs-synced listings. Cover art follows the new release automatically.

Raw schema

{
  "type": "object",
  "properties": {
    "listing_id": {
      "type": "string",
      "description": "The listing id to update."
    },
    "price_cents": {
      "type": "integer",
      "description": "New price in USD cents.",
      "minimum": 0
    },
    "condition": {
      "type": "string",
      "enum": [
        "Mint",
        "Near Mint",
        "VG+",
        "VG",
        "Good+",
        "Good",
        "Fair",
        "Poor"
      ],
      "description": "Media condition, Goldmine grade."
    },
    "sleeve_condition": {
      "type": "string",
      "enum": [
        "Mint",
        "Near Mint",
        "VG+",
        "VG",
        "Good+",
        "Good",
        "Fair",
        "Poor",
        "Generic"
      ],
      "description": "Sleeve condition, Goldmine grade or 'Generic'."
    },
    "description": {
      "type": "string",
      "description": "Free-text listing description (max 5000 chars)."
    },
    "quantity": {
      "type": "integer",
      "description": "Number of copies available.",
      "minimum": 0
    },
    "accept_offers": {
      "type": "boolean",
      "description": "Whether buyers can submit offers below the listed price."
    },
    "location": {
      "type": "string",
      "description": "Storage/location note for the dealer."
    },
    "discogs_release_id": {
      "type": "string",
      "description": "Rematch this listing to a different pressing/version (get_release returns versions[] to choose from). Numeric Discogs release id. Blocked for Discogs-synced listings. Cover art follows the new release automatically."
    }
  },
  "required": [
    "listing_id"
  ]
}

set_listing_status

Delist or relist one of the authenticated dealer's listings (requires an agent key). action 'delist' removes the listing from WAXED and, when linked, deletes the corresponding Discogs listing (irreversible on the Discogs side — Discogs has no un-delete) and decrements Square inventory. action 'relist' brings it back for sale on WAXED and re-increments linked Square inventory, but does NOT restore a deleted Discogs listing; relisting also requires the dealer to have completed Stripe payouts onboarding.

Parameters2

listing_id	string	required	The listing id to change.
action	string	required	'delist' or 'relist'.

Raw schema

{
  "type": "object",
  "properties": {
    "listing_id": {
      "type": "string",
      "description": "The listing id to change."
    },
    "action": {
      "type": "string",
      "enum": [
        "delist",
        "relist"
      ],
      "description": "'delist' or 'relist'."
    }
  },
  "required": [
    "listing_id",
    "action"
  ]
}

delete_listing

Permanently delete one of the authenticated dealer's listings (requires an agent key). This is irreversible: the WAXED row is deleted outright and, when linked, the corresponding Discogs listing (or collection instance) is also deleted upstream. Requires confirm: true or the call is rejected before anything is deleted.

Parameters2

listing_id	string	required	The listing id to delete.
confirm	boolean	required	Must be true to proceed — this is a permanent, irreversible delete.

Raw schema

{
  "type": "object",
  "properties": {
    "listing_id": {
      "type": "string",
      "description": "The listing id to delete."
    },
    "confirm": {
      "type": "boolean",
      "description": "Must be true to proceed — this is a permanent, irreversible delete."
    }
  },
  "required": [
    "listing_id",
    "confirm"
  ]
}

bulk_update_listings

Run one bulk operation across up to 100 of the authenticated dealer's listings at once (requires an agent key). action 'price_update' with mode 'set' sets every listing to value (integer USD cents; the $0.50 floor applies to active listings), or mode 'percent' adjusts each listing's current price by value percent (e.g. -10 lowers price 10%; same floor on active listings). action 'auto_price' runs the WAXED pricing engine per listing from its linked Discogs release id — capped at 25 listing ids per call (estimatePrice can live-fetch and run long); listings without a linked release are skipped. action 'status_change' moves listings to status 'active', 'removed', or 'collection' — 'removed' cascades a best-effort Discogs delist + Square inventory decrement for linked listings. action 'mark_sold' marks listings sold and cascades the same best-effort delist/decrement. action 'export_csv' returns the listings as CSV text (no mode/value/status needed). Bulk delete is deliberately not offered here — use delete_listing per item to permanently remove a listing.

Parameters5

action	string	required	The bulk operation to run.
listing_ids	array	required	Listing ids to act on, 1–100 items. auto_price is further capped at 25.
mode	string	optional	For action 'price_update' only: 'set' (fixed price) or 'percent' (relative adjustment).
value	number	optional	For action 'price_update' only: integer USD cents (mode 'set') or a percent like -10 (mode 'percent').
status	string	optional	For action 'status_change' only: the new status.

Raw schema

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "price_update",
        "auto_price",
        "status_change",
        "mark_sold",
        "export_csv"
      ],
      "description": "The bulk operation to run."
    },
    "listing_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Listing ids to act on, 1–100 items. auto_price is further capped at 25.",
      "minItems": 1,
      "maxItems": 100
    },
    "mode": {
      "type": "string",
      "enum": [
        "set",
        "percent"
      ],
      "description": "For action 'price_update' only: 'set' (fixed price) or 'percent' (relative adjustment)."
    },
    "value": {
      "type": "number",
      "description": "For action 'price_update' only: integer USD cents (mode 'set') or a percent like -10 (mode 'percent')."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "removed",
        "collection"
      ],
      "description": "For action 'status_change' only: the new status."
    }
  },
  "required": [
    "action",
    "listing_ids"
  ]
}

my_crates

List the authenticated dealer's own crates and lots (requires an agent key). Returns a compact projection per crate: id, name, color, type ('crate'|'lot'), item_count, total_value (USD cents, sum of member listing prices), item_ids (member listing ids).

Parameters1

type

string

optional

Filter to this type; default 'crate'.

Raw schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "crate",
        "lot",
        "all"
      ],
      "description": "Filter to this type; default 'crate'."
    }
  }
}

create_crate

Create a new crate or lot for the authenticated dealer (requires an agent key). type 'crate' (default) is a dealer-curated bundle sold together; 'lot' is a private grouping. Use modify_crate_items afterward to add listings, and publish_crate to put it up for sale.

Parameters3

name	string	required	Crate name, e.g. 'Jazz Deep Cuts'.
color	string	optional	Optional display color (hex or theme name).
type	string	optional	'crate' (default) or 'lot'.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Crate name, e.g. 'Jazz Deep Cuts'."
    },
    "color": {
      "type": "string",
      "description": "Optional display color (hex or theme name)."
    },
    "type": {
      "type": "string",
      "enum": [
        "crate",
        "lot"
      ],
      "description": "'crate' (default) or 'lot'."
    }
  },
  "required": [
    "name"
  ]
}

update_crate

Rename or recolor one of the authenticated dealer's crates (requires an agent key). Only provided fields are changed; does not touch membership (use modify_crate_items) or publish state (use publish_crate).

Parameters3

crate_id	string	required	The crate id to update.
name	string	optional	New crate name.
color	string	optional	New display color.

Raw schema

{
  "type": "object",
  "properties": {
    "crate_id": {
      "type": "string",
      "description": "The crate id to update."
    },
    "name": {
      "type": "string",
      "description": "New crate name."
    },
    "color": {
      "type": "string",
      "description": "New display color."
    }
  },
  "required": [
    "crate_id"
  ]
}

delete_crate

Permanently delete one of the authenticated dealer's crates (requires an agent key). This is irreversible: the crate row and all its item memberships are deleted (member listings themselves are untouched). If the crate was published, its public bundle listing is left orphaned — unpublish first. Requires confirm: true or the call is rejected before anything is deleted.

Parameters2

crate_id	string	required	The crate id to delete.
confirm	boolean	required	Must be true to proceed — this is a permanent, irreversible delete.

Raw schema

{
  "type": "object",
  "properties": {
    "crate_id": {
      "type": "string",
      "description": "The crate id to delete."
    },
    "confirm": {
      "type": "boolean",
      "description": "Must be true to proceed — this is a permanent, irreversible delete."
    }
  },
  "required": [
    "crate_id",
    "confirm"
  ]
}

modify_crate_items

Add or remove listings from one of the authenticated dealer's crates (requires an agent key). action 'add' upserts the given listing ids as crate members (no error on duplicates); 'remove' drops them from the crate without deleting the listings themselves.

Parameters3

crate_id	string	required	The crate id to modify.
action	string	required	'add' or 'remove'.
listing_ids	array	required	Listing ids to add to or remove from the crate.

Raw schema

{
  "type": "object",
  "properties": {
    "crate_id": {
      "type": "string",
      "description": "The crate id to modify."
    },
    "action": {
      "type": "string",
      "enum": [
        "add",
        "remove"
      ],
      "description": "'add' or 'remove'."
    },
    "listing_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Listing ids to add to or remove from the crate.",
      "minItems": 1
    }
  },
  "required": [
    "crate_id",
    "action",
    "listing_ids"
  ]
}

publish_crate

Publish or unpublish one of the authenticated dealer's crates (requires an agent key; needs at least 2 member listings to publish). action 'publish' activates every member listing priced at or above $0.50 and creates (or updates) a public bundle page at waxed.market/crates/{crate_id}, priced as the sum of member prices. action 'unpublish' moves member listings back to 'collection' (not for sale) and removes the public bundle listing. Re-running publish recalculates the crate price from current member prices — to reprice a crate, update_listing its members then publish again.

Parameters2

crate_id	string	required	The crate id to publish or unpublish.
action	string	required	'publish' or 'unpublish'.

Raw schema

{
  "type": "object",
  "properties": {
    "crate_id": {
      "type": "string",
      "description": "The crate id to publish or unpublish."
    },
    "action": {
      "type": "string",
      "enum": [
        "publish",
        "unpublish"
      ],
      "description": "'publish' or 'unpublish'."
    }
  },
  "required": [
    "crate_id",
    "action"
  ]
}

my_orders

List the authenticated dealer's orders (requires an agent key), merging native WAXED checkout orders (marketplace_transactions) with Square POS sales (square_orders). Returns a compact projection per order: id (Square rows are prefixed 'square:'), source ('waxed'|'square'), status, total_cents (integer USD cents), created_at, and — when available — buyer_name, listing_title, listing_id. role defaults to 'seller'; Square POS rows only ever appear for role 'seller' (they're POS sales, never a buyer's own order). role 'buyer' returns only the caller's own WAXED purchases. Optionally filter by the unified status field and cap the count (default 50, max 200); results are sorted newest first.

Parameters3

role	string	optional	'seller' (default) or 'buyer'.
status	string	optional	Filter to this unified order status, e.g. 'pending', 'confirmed', 'shipped', 'completed'.
limit	integer	optional	Max orders to return (default 50, max 200).

Raw schema

{
  "type": "object",
  "properties": {
    "role": {
      "type": "string",
      "enum": [
        "seller",
        "buyer"
      ],
      "description": "'seller' (default) or 'buyer'."
    },
    "status": {
      "type": "string",
      "description": "Filter to this unified order status, e.g. 'pending', 'confirmed', 'shipped', 'completed'."
    },
    "limit": {
      "type": "integer",
      "description": "Max orders to return (default 50, max 200).",
      "minimum": 1,
      "maximum": 200
    }
  }
}

get_order

Get full detail for one order by id (requires an agent key; the authenticated dealer must be the buyer or seller on it, else 403). WAXED-native orders only — Square POS sales aren't queryable here. Returns the order row, its order_events history, listing, the other party's profile, and any seller review. Shipping addresses are redacted by role: sellers see the buyer's full address; buyers see only the seller's city/state/country. Pickup orders are the exception — both parties see the full public pickup address plus the seller's pickup instructions.

Parameters1

order_id

string

required

The order id.

Raw schema

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The order id."
    }
  },
  "required": [
    "order_id"
  ]
}

update_order_status

Advance an order's status, or attach a note without changing status (requires an agent key; the authenticated dealer must be the buyer or seller on it). Legal status transitions: confirmed→shipped (seller only; pass tracking_number/carrier — registers tracking for delivery webhooks), confirmed→canceled (either party), shipped→delivered (buyer only, except a seller may mark a pickup order delivered themselves), delivered→return_requested (buyer only), return_requested→returned (seller only). event_type 'note' can be attached at any status by either party and never changes status. Any other transition is rejected with a 422. NOTE: returned→refunded is a real transition in the app, but it fires a DB trigger that auto-issues store credit to the buyer. The refunded transition is dashboard-only because it issues store credit to the buyer; it is blocked for agent keys (403) even though this tool accepts other transitions.

Parameters5

order_id	string	required	The order id.
event_type	string	required	The transition (or note) to apply — see tool description for the legal transition table. 'refunded' is intentionally not offered here (dashboard-only, issues store credit).
tracking_number	string	optional	Shipment tracking number. Only meaningful with event_type 'shipped'; carried in the event's metadata.
carrier	string	optional	Carrier name, e.g. 'USPS', 'UPS'. Only meaningful with event_type 'shipped'; carried in the event's metadata.
note	string	optional	Optional free-text note stored on the event, alongside a transition or standalone with event_type "note".

Raw schema

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The order id."
    },
    "event_type": {
      "type": "string",
      "enum": [
        "shipped",
        "delivered",
        "return_requested",
        "returned",
        "canceled",
        "note"
      ],
      "description": "The transition (or note) to apply — see tool description for the legal transition table. 'refunded' is intentionally not offered here (dashboard-only, issues store credit)."
    },
    "tracking_number": {
      "type": "string",
      "description": "Shipment tracking number. Only meaningful with event_type 'shipped'; carried in the event's metadata."
    },
    "carrier": {
      "type": "string",
      "description": "Carrier name, e.g. 'USPS', 'UPS'. Only meaningful with event_type 'shipped'; carried in the event's metadata."
    },
    "note": {
      "type": "string",
      "description": "Optional free-text note stored on the event, alongside a transition or standalone with event_type \"note\"."
    }
  },
  "required": [
    "order_id",
    "event_type"
  ]
}

discogs_sync

Queue a full Discogs sync for the authenticated dealer (requires an agent key, and the dealer must have already connected Discogs in Settings — otherwise this returns a clear 'Discogs not connected' error). The sync runs on a background worker and this call returns immediately (HTTP 202, queued: true) rather than waiting for completion; poll discogs_status to watch progress via last_listings_sync_at / sync_pending.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

discogs_status

Get the authenticated dealer's Discogs connection and sync status (requires an agent key). Returns connected flag, discogs username, listings_for_sale count, last_listings_sync_at, listings_sync_error, sync_pending/force_sync_requested, and paused. If Discogs isn't connected, returns { connected: false }.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

discogs_pause

Pause or resume the authenticated dealer's automatic Discogs sync (requires an agent key and an already-connected Discogs account). Pausing stops the background worker from picking up sync requests for this dealer until resumed; it does not affect data already synced.

Parameters1

paused

boolean

required

true to pause automatic sync, false to resume it.

Raw schema

{
  "type": "object",
  "properties": {
    "paused": {
      "type": "boolean",
      "description": "true to pause automatic sync, false to resume it."
    }
  },
  "required": [
    "paused"
  ]
}

square_status

Get the authenticated dealer's Square POS connection and health (requires an agent key). Returns connected flag, merchantId, connectedAt, lastSyncAt, tokenHealthy, integrationHealth ('healthy' or an error state from the last token-refresh/webhook), and lastErrorMessage. If Square isn't connected, connected is false.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

square_push

Push up to 20 of the authenticated dealer's listings to their connected Square catalog (requires an agent key, and the dealer must have already connected Square — otherwise this returns a clear 'No Square account connected' error). Creates or updates the matching Square catalog item and variation for each listing id and sets Square inventory (1 if the listing is active, else 0). Pull sync (Square -> WAXED) is dashboard-only and not exposed here.

Parameters1

listing_ids

array

required

Listing ids to push to Square, 1–20 items.

Raw schema

{
  "type": "object",
  "properties": {
    "listing_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Listing ids to push to Square, 1–20 items.",
      "minItems": 1,
      "maxItems": 20
    }
  },
  "required": [
    "listing_ids"
  ]
}

my_analytics

Cross-platform sales/inventory aggregate for the authenticated dealer (requires an agent key), merging WAXED, Discogs, and Square activity. Defaults to the last 30 days when from/to are omitted. platform filters to a single connected platform ('waxed'|'discogs'|'square') or 'all' (default). from/to are ISO 8601 date-times.

Parameters3

platform	string	optional	Platform to scope to; default 'all'.
from	string	optional	Range start, ISO 8601 date-time. Default: 30 days before `to`.
to	string	optional	Range end, ISO 8601 date-time. Default: now.

Raw schema

{
  "type": "object",
  "properties": {
    "platform": {
      "type": "string",
      "enum": [
        "all",
        "waxed",
        "discogs",
        "square"
      ],
      "description": "Platform to scope to; default 'all'."
    },
    "from": {
      "type": "string",
      "description": "Range start, ISO 8601 date-time. Default: 30 days before `to`."
    },
    "to": {
      "type": "string",
      "description": "Range end, ISO 8601 date-time. Default: now."
    }
  }
}

hot_items

Demand-scored items for the authenticated dealer's own listings (requires an agent key), ranked by views, favorites, sales velocity, and price competitiveness. mode 'hot' (default) returns the top items to prioritize; 'underperforming' returns competitively-priced items not getting enough engagement; 'full' returns complete scoring data with all metrics.

Parameters2

mode	string	optional	Default 'hot'.
limit	integer	optional	Max items to return (default 10, max 50).

Raw schema

{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "hot",
        "underperforming",
        "full"
      ],
      "description": "Default 'hot'."
    },
    "limit": {
      "type": "integer",
      "description": "Max items to return (default 10, max 50).",
      "minimum": 1,
      "maximum": 50
    }
  }
}

market_trends

Market-wide trends across the whole WAXED marketplace (all sellers, not dealer-specific), comparing the current vs previous 30-day period. mode 'full' (default) returns trending genres, artists, and price movement together; 'genres' or 'artists' returns just that trend category. Requires an agent key.

Parameters2

mode	string	optional	Default 'full'.
limit	integer	optional	Max items for 'genres'/'artists' mode (default 10, max 50).

Raw schema

{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "full",
        "genres",
        "artists"
      ],
      "description": "Default 'full'."
    },
    "limit": {
      "type": "integer",
      "description": "Max items for 'genres'/'artists' mode (default 10, max 50).",
      "minimum": 1,
      "maximum": 50
    }
  }
}

my_profile

Get the authenticated dealer's own storefront profile (requires an agent key). Returns a compact projection only: id, store_name, display_name, username, store_slug, bio, store_location, is_verified, seller_rating, seller_rating_count, discogs_username, discogs_connected, square_connected. Never includes email, Stripe ids, tax fields, or settings blobs.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

update_profile

Update your public storefront profile: bio, display/store name, location, featured genres, social links, currency, and publish/unpublish (`is_published: false` hides your storefront — closest thing to vacation mode). Store policies are not a WAXED feature yet. Requires an agent key; updates only your own profile row, all fields optional.

Parameters11

display_name	string	optional	Public display name (max 80 chars). Cannot be blank.
store_name	string	optional	Storefront name (max 80 chars). Cannot be blank.
bio	string	optional	Storefront bio/about text (max 2000 chars). Empty string clears it.
store_location	string	optional	Storefront location, e.g. "Portland, OR" (max 120 chars). Empty string clears it.
featured_genres	array	optional	Up to 10 featured genres, each max 40 chars. Blank entries are dropped.
is_published	boolean	optional	false hides your storefront from the public marketplace (vacation mode); true publishes it.
default_currency	string	optional	Default storefront display currency.
social_instagram	string	optional	Instagram URL, must start with https:// (empty string clears it).
social_bandcamp	string	optional	Bandcamp URL, must start with https:// (empty string clears it).
social_twitter	string	optional	Twitter/X URL, must start with https:// (empty string clears it).
social_youtube	string	optional	YouTube URL, must start with https:// (empty string clears it).

Raw schema

{
  "type": "object",
  "properties": {
    "display_name": {
      "type": "string",
      "description": "Public display name (max 80 chars). Cannot be blank.",
      "maxLength": 80
    },
    "store_name": {
      "type": "string",
      "description": "Storefront name (max 80 chars). Cannot be blank.",
      "maxLength": 80
    },
    "bio": {
      "type": "string",
      "description": "Storefront bio/about text (max 2000 chars). Empty string clears it.",
      "maxLength": 2000
    },
    "store_location": {
      "type": "string",
      "description": "Storefront location, e.g. \"Portland, OR\" (max 120 chars). Empty string clears it.",
      "maxLength": 120
    },
    "featured_genres": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 40
      },
      "maxItems": 10,
      "description": "Up to 10 featured genres, each max 40 chars. Blank entries are dropped."
    },
    "is_published": {
      "type": "boolean",
      "description": "false hides your storefront from the public marketplace (vacation mode); true publishes it."
    },
    "default_currency": {
      "type": "string",
      "enum": [
        "USD",
        "EUR",
        "GBP",
        "CAD",
        "AUD",
        "JPY"
      ],
      "description": "Default storefront display currency."
    },
    "social_instagram": {
      "type": "string",
      "description": "Instagram URL, must start with https:// (empty string clears it).",
      "maxLength": 200
    },
    "social_bandcamp": {
      "type": "string",
      "description": "Bandcamp URL, must start with https:// (empty string clears it).",
      "maxLength": 200
    },
    "social_twitter": {
      "type": "string",
      "description": "Twitter/X URL, must start with https:// (empty string clears it).",
      "maxLength": 200
    },
    "social_youtube": {
      "type": "string",
      "description": "YouTube URL, must start with https:// (empty string clears it).",
      "maxLength": 200
    }
  },
  "additionalProperties": false
}

my_conversations

List your buyer/seller message conversations with unread status and last message. role/counterpart/last_message.from are computed relative to you (requires an agent key). Returns a compact projection per conversation: id, role ('seller'|'buyer'), counterpart {id, name, store_name}, listing {id, title, price} or null, last_message {from ('you'|'them'), body, created_at} or null, unread, status, last_message_at.

Parameters4

role	string	optional	Filter to conversations where you're the seller or the buyer; default 'all'.
status	string	optional	Filter by conversation status; default 'open'.
limit	integer	optional	Max conversations to return (default 25, max 100).
offset	integer	optional	Pagination offset (default 0).

Raw schema

{
  "type": "object",
  "properties": {
    "role": {
      "type": "string",
      "enum": [
        "seller",
        "buyer",
        "all"
      ],
      "description": "Filter to conversations where you're the seller or the buyer; default 'all'."
    },
    "status": {
      "type": "string",
      "enum": [
        "open",
        "closed",
        "all"
      ],
      "description": "Filter by conversation status; default 'open'."
    },
    "limit": {
      "type": "integer",
      "description": "Max conversations to return (default 25, max 100).",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "type": "integer",
      "description": "Pagination offset (default 0).",
      "minimum": 0
    }
  }
}

get_conversation

Get a message thread by conversation id (requires an agent key; you must be the seller or buyer on it). Returns the conversation (id, role relative to you, status, last_message_at) and its messages, newest last, each projected to id, from ('you'|'them'), body, created_at. Pass before (ISO 8601 date-time) to page further back in history. mark_read: true marks the thread read on your side as of now.

Parameters4

conversation_id	string	required	The conversation id.
limit	integer	optional	Max messages to return (default 50, max 200).
before	string	optional	ISO 8601 date-time — return messages created before this time.
mark_read	boolean	optional	If true, marks the thread read on your side as of now.

Raw schema

{
  "type": "object",
  "properties": {
    "conversation_id": {
      "type": "string",
      "description": "The conversation id."
    },
    "limit": {
      "type": "integer",
      "description": "Max messages to return (default 50, max 200).",
      "minimum": 1,
      "maximum": 200
    },
    "before": {
      "type": "string",
      "description": "ISO 8601 date-time — return messages created before this time."
    },
    "mark_read": {
      "type": "boolean",
      "description": "If true, marks the thread read on your side as of now."
    }
  },
  "required": [
    "conversation_id"
  ]
}

send_message

Sends a real message the other party sees immediately in their inbox. There is no undo. Pass conversation_id to reply in an existing thread, or omit it and pass buyer_id (optionally listing_id) to start a new conversation with that buyer and send the first message in one call (you are the seller). Requires an agent key.

Parameters4

conversation_id	string	optional	Existing conversation id to reply in. Omit to start a new conversation instead.
buyer_id	string	optional	The buyer's profile id to start a new conversation with. Required when conversation_id is omitted.
listing_id	string	optional	Optional listing id to associate with a new conversation. Only used when conversation_id is omitted.
body	string	required	Message text, up to 4000 characters.

Raw schema

{
  "type": "object",
  "properties": {
    "conversation_id": {
      "type": "string",
      "description": "Existing conversation id to reply in. Omit to start a new conversation instead."
    },
    "buyer_id": {
      "type": "string",
      "description": "The buyer's profile id to start a new conversation with. Required when conversation_id is omitted."
    },
    "listing_id": {
      "type": "string",
      "description": "Optional listing id to associate with a new conversation. Only used when conversation_id is omitted."
    },
    "body": {
      "type": "string",
      "description": "Message text, up to 4000 characters."
    }
  },
  "required": [
    "body"
  ]
}

get_shipping_quote

Estimate shipping cost for a listing to a destination. Quotes only — labels cannot be purchased via agents.

Parameters6

listing_id	string	required	The listing id to quote shipping for.
country	string	required	Destination ISO 3166-1 alpha-2 country code, e.g. "US".
postal	string	optional	Destination postal/zip code.
state	string	optional	Destination state/province.
city	string	optional	Destination city.
quantity	integer	optional	Number of copies (default 1).

Raw schema

{
  "type": "object",
  "properties": {
    "listing_id": {
      "type": "string",
      "description": "The listing id to quote shipping for."
    },
    "country": {
      "type": "string",
      "description": "Destination ISO 3166-1 alpha-2 country code, e.g. \"US\".",
      "minLength": 2,
      "maxLength": 2
    },
    "postal": {
      "type": "string",
      "description": "Destination postal/zip code."
    },
    "state": {
      "type": "string",
      "description": "Destination state/province."
    },
    "city": {
      "type": "string",
      "description": "Destination city."
    },
    "quantity": {
      "type": "integer",
      "description": "Number of copies (default 1).",
      "minimum": 1
    }
  },
  "required": [
    "listing_id",
    "country"
  ]
}

get_order_shipping_rates

Get live carrier rate quotes for a confirmed order you're selling. Read-only: purchasing the label happens in the dashboard.

Parameters1

order_id

string

required

The order id. Must be status 'confirmed' and you must be the seller.

Raw schema

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The order id. Must be status 'confirmed' and you must be the seller."
    }
  },
  "required": [
    "order_id"
  ]
}

market.waxed/mcp MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

search

get_release

browse_marketplace

get_price_estimate

get_price_history

get_store

get_shared_wishlist

get_artist

get_label

get_crate

discogs_search

lookup_barcode

my_listings

create_listing

update_listing

set_listing_status

delete_listing

bulk_update_listings

my_crates

create_crate

update_crate

delete_crate

modify_crate_items

publish_crate

my_orders

get_order

update_order_status

discogs_sync

discogs_status

discogs_pause

square_status

square_push

my_analytics

hot_items

market_trends

my_profile

update_profile

my_conversations

get_conversation

send_message

get_shipping_quote

get_order_shipping_rates

Install

Remote endpoint