Waxed MCP Server

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.

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.

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.

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).

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.

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 release_id rematch.

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 }.

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.

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.

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.

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.

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.

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.

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

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.

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

Get real historical sales for a release by catalog 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.

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.

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.

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.

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.

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.

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.

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

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 catalog 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.

Build a link for a human to review and pay for a cart of WAXED listings. This does NOT purchase anything, move money, create a Stripe session, or collect any payment/address/shipping info — it only returns a checkout_url that pre-loads WAXED's cart. The human opens that link, signs in, enters their shipping address, picks a shipping option per seller, and pays through WAXED's existing checkout — all of that happens on the website, not here. Multi-seller carts are normal: WAXED checkout splits payment per seller automatically. Hand this link to your human; do not try to complete the purchase yourself.

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.

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.

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).

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.

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.

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, 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.

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

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.

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.

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.

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.

Get full detail for a release by its catalog 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.

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.

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.

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.

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

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).