# Musiquay — Feature: Merchandise and Physical Sales > T-shirts, cassettes, vinyl, you name it, hoodies, undies, socks, anything and everything band related. Record shops, distros, everyone welcome. ## Overview Musiquay is where the scene lives — and the scene runs on physical objects. T-shirts at the merch table. Vinyl at the record shop. Cassettes from the distro. Patches from the band's webstore. Posters from the designer. The physical economy of music is massive, fragmented, and underserved by every existing platform. Bands and labels should be able to catalog and sell merchandise directly from their Musiquay profiles. Record shops — who have always struggled with websites and payment infrastructure — should be able to list their inventory and sell to anyone. Distros should be able to catalog what they carry and connect with artists looking for distribution. Fans should be able to resell merch and rare pressings to each other. All on the same protocol. Same identities. Same payment infrastructure. Zero platform cut. ## What This Covers The merchandise system serves four distinct but interconnected use cases: 1. **Artist and label merch stores** — sell merch directly from your profile 2. **Record shops** — catalog and sell inventory, both in-store and online 3. **Distros** — distribution labels catalog what they carry, connect with artists and buyers 4. **Resale / second-hand market** — fans resell merch and physical music to each other All four use cases share the same protocol primitives, the same payment rails, and the same principle: **Musiquay is the infrastructure, not the middleman.** ## NIP-15 and NIP-99: Two Protocols, Two Use Cases Nostr already has two relevant specs, and they map cleanly to the different selling patterns. ### NIP-15: Nostr Marketplace (Structured Stores) NIP-15 is designed for merchants selling products. It provides: | Event Kind | Purpose | Musiquay Usage | |------------|---------|----------------| | **Kind 30017** | Stall — a named collection of products with currency and shipping zones | Artist merch store, record shop inventory, distro catalog | | **Kind 30018** | Product — a single item for sale with price, quantity, images, specs, and shipping | Individual merch items, records, physical releases | **Key NIP-15 features:** - **Stalls** — a seller can have multiple stalls. An artist might have a "Merch" stall and a "Physical Releases" stall. A record shop might organize by genre or format. - **Products** — structured with name, description, images, price, quantity, and arbitrary `specs` key-value pairs. Specs handle size options, color variants, format details, condition grading — anything. - **Shipping zones** — structured shipping costs by region, defined at the stall level. Handles domestic vs. international, EU vs. rest-of-world, whatever the seller needs. - **Quantity tracking** — stock levels visible on the product. Can be null for unlimited/made-to-order items. - **Currency** — defined at the stall level. Can be fiat (EUR, USD, GBP) or sats/BTC. NIP-15 is the right protocol for **ongoing storefronts** — artists selling merch, record shops listing inventory, distros cataloging their stock. ### NIP-99: Classified Listings (One-Off Sales) NIP-99 (kind 30402) — already used by the [services marketplace](./FEATURES_MARKETPLACE.md) — is better suited for one-off resale: - A fan selling a rare first pressing - Someone offloading a tour T-shirt they've outgrown - A collector thinning their collection NIP-99 provides price, location, status (active/sold), images, and free-text description — everything a classified ad needs without the overhead of stalls and shipping zones. ### When to Use Which | Scenario | Protocol | Why | |----------|----------|-----| | Artist selling merch (ongoing store) | NIP-15 | Multiple products, structured inventory, shipping zones | | Record shop listing inventory | NIP-15 | Large catalog, structured specs (format, condition, edition), shipping | | Distro cataloging stock | NIP-15 | Structured catalog with format details and availability | | Label selling physical releases | NIP-15 | Multiple editions, structured product data | | Fan reselling a rare pressing | NIP-99 | One-off listing, simpler structure | | Fan selling old merch | NIP-99 | One-off classified ad | | Pre-order for upcoming release | NIP-15 | Product with future availability date, structured edition data | ## Use Case 1: Artist and Label Merch Stores Every artist and label on Musiquay can run a merch store directly from their profile. No third-party platform. No embedded Shopify. No platform cut. ### What Can Be Sold Anything band-related: - **Apparel** — T-shirts, hoodies, long sleeves, tank tops, socks, undies, hats, beanies - **Accessories** — patches, pins, stickers, tote bags, lanyards, keychains - **Prints and art** — posters, screen prints, art prints, zines - **Physical music** — vinyl, cassettes, CDs (links to [edition data from FEATURES_CREDITS.md](./FEATURES_CREDITS.md)) - **Oddities** — skateboards, candles, coffee, hot sauce, whatever bands sell. The protocol doesn't care. - **Bundles** — album + T-shirt, vinyl + poster, etc. ### Structured Product Data NIP-15 product specs handle the complexity of physical goods: ```json { "id": "bnd-tshirt-skull-2026", "stall_id": "band-name-merch", "name": "Skull Design T-Shirt", "description": "Screen printed on heavyweight cotton. Design by [tagged designer].", "images": ["https://blossom.musiquay.com/", "https://blossom.musiquay.com/"], "currency": "EUR", "price": 25.00, "quantity": 150, "specs": [ ["sizes", "S, M, L, XL, XXL"], ["color", "Black"], ["material", "100% heavyweight cotton"], ["print-method", "Screen print"], ["designer", ""] ], "shipping": [ {"id": "eu", "cost": 5.00}, {"id": "worldwide", "cost": 12.00} ] } ``` ### Physical Releases in the Merch Store When an artist or label sells physical music, the product **links to the edition data** from the [release credits system](./FEATURES_CREDITS.md): ```json { "id": "album-vinyl-first-press", "stall_id": "band-name-releases", "name": "Album Name — Vinyl (First Pressing)", "description": "180g black vinyl in gatefold sleeve. Mastered for vinyl by [tagged engineer].", "images": ["https://blossom.musiquay.com/"], "currency": "EUR", "price": 28.00, "quantity": 200, "specs": [ ["format", "vinyl"], ["weight", "180g"], ["color", "black"], ["sleeve", "gatefold"], ["catalog", "ABC-001"], ["a", "32216::"], ["a", "32211::"] ], "shipping": [ {"id": "eu", "cost": 6.00}, {"id": "worldwide", "cost": 15.00} ] } ``` The `a` tags link directly to the [edition event (32216)](./FEATURES_CREDITS.md) and [album event (32211)](./FEATURES_MUSIC.md) — full provenance. Pressing plant, mastering engineer, catalog number, batch size — it's all there, one tap away from the product listing. ### Pre-Orders Artists can list products with future availability: - Upcoming vinyl pressing — list it now, ship when it arrives from the plant. - New merch drop — create a product before the design is printed. Build anticipation. - Release bundles — album + merch combo available for pre-order ahead of release date. Ties into [release countdowns from FEATURES_CALENDAR.md](./FEATURES_CALENDAR.md) — the countdown event and the pre-order listing can reference the same release. ### Credits on Merch The merch itself has credits, connecting to the [roster](./FEATURES_ROSTER.md) and [credits](./FEATURES_CREDITS.md) systems: - The designer who created the T-shirt artwork is tagged (via the `designer` spec linking to a pubkey). - The screen printer / merch company that produced the shirts can be tagged. - The pressing plant for a vinyl release is already documented in the edition event. Everyone who made the physical object gets credited. The screen printer is part of the scene too. ## Use Case 2: Record Shops This is huge. Independent record shops have always struggled with web presence and online sales. Building a website is expensive. Setting up payment processing is a pain. Maintaining an online catalog is a full-time job. Musiquay gives them all of this for free. ### Record Shops as First-Class Participants A record shop is a Nostr identity on Musiquay — a keypair with a profile, just like an artist, a venue, or a promoter. Their profile includes: - Shop name, description, location - Opening hours - Geohash for location-based discovery - Lightning address for payments - Links to their NIP-15 stalls (their inventory) ### Structured Inventory A record shop's inventory is one or more NIP-15 stalls. Each product (record) is structured: ```json { "id": "stock-item-12345", "stall_id": "loja-do-som-vinyl", "name": "Artist Name — Album Title", "description": "Original 1st pressing. Sleeve VG+, media NM. Includes insert.", "images": ["https://blossom.musiquay.com/"], "currency": "EUR", "price": 35.00, "quantity": 1, "specs": [ ["format", "vinyl"], ["condition-media", "NM"], ["condition-sleeve", "VG+"], ["pressing", "1st pressing, 1987"], ["catalog", "SST-065"], ["includes", "insert"], ["a", "32211::"], ["a", "32216::"] ], "shipping": [ {"id": "local-pickup", "cost": 0}, {"id": "pt", "cost": 4.00}, {"id": "eu", "cost": 8.00} ] } ``` **Key features for record shops:** - **Condition grading** — structured specs for media and sleeve condition (Mint, NM, VG+, VG, G+, G, Fair, Poor). Standard Goldmine grading. - **Edition linking** — when the record exists in Musiquay's credits system, the product links to the edition event (32216). Full provenance: credits, pressing plant, catalog number. - **New and used** — shops sell both. The condition specs distinguish them. - **Local pickup** — shipping zone with zero cost for walk-in customers. - **Format variety** — vinyl, CD, cassette, 7", 10", 12", box set — all handled by specs. ### Location-Based Discovery Record shops are physical places. The [calendar and location system](./FEATURES_CALENDAR.md) applies: - **Find record shops near you** — geohash-powered discovery. "Record shops within 10km." - **Browse by specialty** — shops can tag their stalls by genre. "Jazz vinyl shops in Lisbon." - **In-store events** — a record shop can publish calendar events for in-store performances, listening parties, Record Store Day events. The shop is both a retail participant and a venue participant. ### No More Website Struggle A record shop's Musiquay presence IS their web presence: - Their profile is their homepage. - Their stalls are their catalog. - Lightning + Stripe is their payment processing. - The Nostr protocol is their backend. - No hosting fees. No web developer. No Shopify subscription. No WooCommerce plugin hell. They list records. People find them. People buy. Money goes directly to the shop's Lightning address or custodial account. Done. ## Use Case 3: Distros Distribution labels and independent distributors occupy a unique niche — they're the connective tissue between artists/labels and the wider world. ### Distros as Participants A distro is a Nostr identity that: - Catalogs what they currently carry (NIP-15 stalls organized by label, genre, or format). - Makes their catalog discoverable to fans and other shops. - Connects with artists and labels who are looking for distribution. - Ships physical product to customers and retail accounts. ### Discovery and Connection The distro system creates matchmaking between creators and distributors: - **Artists/labels find distros** — "Which distros carry post-punk vinyl in Europe?" Searchable by genre, format, territory. - **Distros find new releases** — they can follow labels and artists on the protocol. When a new release is published with a vinyl edition, distros who carry that genre see it. - **Cross-border discovery** — "Find distros in Japan that carry European punk." Opening up distribution channels that are currently invisible. ### Integration with Services Marketplace Distro relationships overlap with the [services marketplace](./FEATURES_MARKETPLACE.md): - A label posting "Looking for EU distribution for our catalog" is a marketplace listing. - A distro posting "Now accepting submissions from indie labels" is a marketplace listing. - The merch system handles the actual catalog and sales once the relationship exists. ## Use Case 4: Resale and Second-Hand Market Fans resell merch and physical music. This is where the Discogs marketplace angle lives — but on Nostr, with Lightning payments. ### NIP-99 for One-Off Listings Resale uses NIP-99 classified listings (kind 30402) — the same protocol as the services marketplace, applied to physical goods: ```json { "kind": 30402, "pubkey": "", "content": "Selling my copy. Played a handful of times, basically mint. Shipping from Porto.", "tags": [ ["d", "resale-album-vinyl-001"], ["title", "Artist Name — Album Title (Vinyl, 1st Pressing)"], ["summary", "NM/VG+. Original 1st pressing with insert."], ["published_at", "1740000000"], ["location", "Porto, Portugal"], ["g", "ez3qe"], ["price", "45", "EUR"], ["t", "vinyl"], ["t", "resale"], ["t", "post-punk"], ["t", "1st-pressing"], ["image", "https://blossom.musiquay.com/"], ["status", "active"], ["a", "32216::", "wss://relay.musiquay.com"] ] } ``` ### Edition Provenance When a resale listing references an edition event from [FEATURES_CREDITS.md](./FEATURES_CREDITS.md), the buyer gets full provenance: - Which pressing (first, second, reissue) - Which plant pressed it - Who mastered this specific edition - Original pressing quantity - Catalog number and format details This is what Discogs does, but on an open protocol with cryptographic identity. The seller is a real Nostr pubkey with a scene graph history, not an anonymous username. ### Collector's Market The combination of edition tracking and resale listings creates a collector's paradise: - **Rare pressings** are discoverable — "find all resale listings for first pressings of Album X." - **Limited editions** have full documentation — pressing quantity, original price, format details. - **Price history** — over time, completed sales create a record of what things sell for. Market intelligence for collectors. - **Provenance** — the seller's Nostr identity provides social context. A seller with a long scene history and confirmed roster entries is more trustworthy than a faceless account. ### Merch Resale Not just records — fans resell all kinds of merch: - Vintage tour T-shirts - Out-of-print posters - Limited-edition patches and pins - Festival merch from past years The same NIP-99 listing format handles all of it. Tags categorize by type, condition, and relevance. ## New Participant Types The merchandise system introduces new participant types to the [scene graph](./ARCHITECTURE.md#identity-and-the-scene-graph): | Role | Description | Example Activity | |------|-------------|------------------| | **Record Shop** | Independent physical retail | Catalog inventory, sell new and used records, host in-store events | | **Distro** | Distribution label / service | Catalog carried titles, connect with labels, ship to customers and retail | | **Merch Company** | Screen printers, merch manufacturers | Print T-shirts, produce physical merch. Get credited on merch products. | These join the existing participant types. A record shop is also potentially a venue (in-store events). A distro is also potentially a label. A merch company shows up on event rosters (produced the tour merch) and on product credits (printed the T-shirts). The scene graph handles the overlap naturally — it's all just Nostr identities with roles. ## Payments Same infrastructure, same principles: - **Lightning payments** for instant settlement. Artist sells a T-shirt → money arrives in seconds. - **Stripe on-ramp** for buyers paying with credit cards. Same custodial flow as everywhere else on Musiquay. - **Direct to seller** — sovereign sellers with their own Lightning wallets receive payments directly. Zero platform involvement. - **Zero platform cut.** Musiquay takes nothing from merch, record, or resale transactions. The infrastructure exists to serve the scene. ### Shipping and Fulfillment Musiquay does NOT handle shipping or fulfillment. Sellers handle their own logistics — the same way they do on Bandcamp, Discogs, or any direct-sales model. The protocol structures the shipping zones and costs; the actual shipping is between seller and buyer. Communication between buyer and seller happens via Nostr direct messages (NIP-17, NIP-44 encrypted) — address details, tracking numbers, delivery confirmations. Peer-to-peer, no platform involvement. ## Integration with Other Pillars ### Release Credits Physical releases for sale link to their [edition data](./FEATURES_CREDITS.md): - A vinyl listed in an artist's merch store links to the edition event → full credits, pressing plant, catalog number. - A record shop listing a used copy links to the same edition → buyer sees the complete provenance. - A resale listing for a rare pressing links to the edition → collector gets full details. The merch system is the **storefront** for the credits system's **catalog**. One documents the record's history; the other sells it. ### Event Calendar Merch and events are deeply connected: - **Show merch** — "available at tonight's show." An artist can flag which merch will be at the merch table for a specific event. - **Exclusive event merch** — limited items only available at a specific show or festival. Listed as products tied to a calendar event. - **Record Store Day** — shops can publish calendar events for special releases and in-store events. - **Pre-order drops** tied to [release countdowns](./FEATURES_CALENDAR.md#release-countdowns). ### Event Roster The merch supply chain gets credited: - The screen printer who made the tour T-shirts gets tagged on the product. - The merch company appears on event rosters when they're handling the merch table at shows. - The pressing plant is already credited on the edition event — and the merch listing links to it. ### Services Marketplace The merch ecosystem generates marketplace activity: - Merch companies post availability on the [services marketplace](./FEATURES_MARKETPLACE.md): "Screen printing available, minimum run 50 units." - Pressing plants, CD replication services, and cassette duplicators list their services. - Artists looking for merch production find providers through the marketplace; the resulting products get listed in the merch store. ### Scene Graph Every merch transaction and listing enriches the scene graph: - A record shop that sells releases from 50 labels has a connection to each of them. - A distro that carries artists from a specific scene becomes a node linking that scene to buyers elsewhere. - A merch company that prints for 30 bands has a professional network visible in the graph. - A fan who buys from specific artists and shops has purchasing patterns that inform their social profile (optional, privacy-respecting). ## What Musiquay Is Not (Merch Edition) Boundaries, clearly stated: - **Not an escrow service.** Buyer and seller handle the transaction directly. Musiquay structures the listing and processes the payment, but does not hold goods or mediate disputes. - **Not a fulfillment center.** No warehousing, no shipping, no returns processing. Sellers handle their own logistics. - **Not a marketplace with fees.** Zero cut. Zero commission. The infrastructure is free because the infrastructure is for the scene. - **Not competing with Bandcamp/Discogs merch.** Musiquay has its own vision. This is the same decentralized, protocol-native approach applied to physical goods. Not positioning against anyone. ## NIP Strategy | Concept | NIP | Notes | |---------|-----|-------| | **Stall (product collection)** | NIP-15, kind 30017 | Merch stores, record shop inventory, distro catalogs | | **Product (item for sale)** | NIP-15, kind 30018 | Individual merch items, records, physical releases with structured specs | | **Resale listing** | NIP-99, kind 30402 | One-off second-hand sales. Same protocol as services marketplace. | | **Direct messages (buyer↔seller)** | NIP-17 / NIP-44 | Shipping details, order communication | | **Edition linking** | Custom (from FEATURES_CREDITS.md) | Product specs reference edition events for full provenance | The merchandise system requires **zero new custom event kinds.** It reuses NIP-15 (structured marketplace) and NIP-99 (classifieds) entirely, with Musiquay-specific conventions for how specs and tags are used. This is the reuse-first NIP strategy at its best. **Open point — checkout transport.** NIP-15 defines its `type` 0/1/2 checkout payloads inside NIP-04 messages, which are deprecated and are not available in the musiquay reference client (MLS only). The payloads themselves are fine; the transport needs re-homing to NIP-17 or MLS before implementation. See [PROTOCOL_FLOWS.md](./PROTOCOL_FLOWS.md). ## UI Concepts ### Artist/Label Profile — Shop Tab - Merch stalls displayed alongside music catalog. - Products browseable by category (apparel, physical music, accessories, etc.). - Physical releases link to their full credits and edition data. - Lightning checkout — instant payment, no cart abandonment. ### Record Shop Profile - Full inventory browseable by format, genre, condition, price. - Location prominent — map, address, opening hours. - In-store events from the calendar displayed alongside the catalog. - "New arrivals" feed — recently listed products surface for followers. ### Distro Profile - Catalog browseable by label, genre, format, territory. - "Now carrying" feed — new pickups announced to followers. - Contact for wholesale/retail inquiries via Nostr DM. ### Resale Browse - Location-based: "vinyl for sale near me." - Format and genre filtering. - Edition provenance displayed for items linked to the credits system. - Seller reputation visible from the scene graph (not a separate rating system). ### Discovery - **"Record shops near you"** — map view, powered by geohash. - **"New merch from artists you follow"** — feed of product listings from followed artists and labels. - **"Rare pressings for sale"** — resale listings for limited editions and out-of-print releases. - **"Distros carrying [genre] in [region]"** — discover distribution channels.