Release & Sales Mapping
Use this page as the canonical crosswalk between product language, API types, and Verse Elements integration requirements.
Release Model Mapping
| Product language | Primary GraphQL signal | Key fields | Purchase payload requirements |
|---|---|---|---|
| Generative release | Artwork.artworkKind -> GenerativeProjectArtworkKind | iframeUrl, aspectRatio, allowUserCuration | Standard openPurchaseDialog() payload |
| Artist-curated release | Artwork.artworkKind -> ProjectArtworkKind | items, allowUserSelection, withRepetitions | If allowUserSelection=true, pass userInput[{ key: "$curated_project:item_id", value: <ProjectItem.id> }] |
| Collector-curated release | Artwork.artworkKind -> GenerativeProjectArtworkKind with curated flow in Elements | Collector saves preferred output before checkout | Call createBookmark() and pass userInput[{ key: "$user_hash", value: <signedToken> }] |
| Edition / fixed media release | Artwork.artworkKind may be null or non-project-specific | Listing strategy determines sale flow | Standard openPurchaseDialog() payload |
| Unique 1/1 release | Usually single-edition configuration with auction/listing strategy | Strategy and listing windows | Standard payload, often auction UX |
Primary Sale Strategy Mapping
| Product language | GraphQL type (PrimaryMarketListing.strategy) | Key fields | Integration notes |
|---|---|---|---|
| Limited Edition | PMBuyNowLimitedEditionStrategy | price, maxEditions, reservedEditions, stats.issuedEditions | Supports add-ons like Dutch Auction and Decreasing Supply |
| Open Edition | PMBuyNowOpenEditionStrategy | price, stats.issuedEditions | Time-window driven, no fixed max editions in strategy |
| 1/1 Auction | PMAuctionStrategy | minimumBid, bids, stats, extensionSettings | Bidding flow handled by purchase dialog |
| Ranked Auction | PMAuctionStrategy + rankedAuctionSettings | rankedAuctionSettings.topNWinners, lowestWinningBid | Multiple winners at clearing logic |
Supplementary Mechanics Mapping
| Product language | GraphQL field/query | Where it appears | Integration impact |
|---|---|---|---|
| Dutch Auction | dutchAuction | PMBuyNowLimitedEditionStrategy and PMBuyNowOpenEditionStrategy | UI should show dynamic bracketed pricing/timing |
| Decreasing Supply | decreasingSupply | PMBuyNowLimitedEditionStrategy | UI should show shrinking available supply over time |
| Mint Pass | mintPassConfiguration(pmListingId) query | Separate query by listing | Gate purchase UI until eligibility is confirmed |
| Reserve List | checkReserves(artworkId[, reserveId]) via Elements | Authenticated check | Use reserveAccess.reserveRequired + reserveAccess.hasAccess to decide CTA state |
Listing Lifecycle Mapping
| Concept | GraphQL field | Notes |
|---|---|---|
| Active listing window | PrimaryMarketListing.startsAt, endsAt | Primary source for countdown and availability windows |
| Listing status outcome | PrimaryMarketListing.endReason | Common values include TIME_IS_OUT and SOLD_OUT |
| Current active listing | primaryMarketListing(artworkId) | Use for primary CTA |
| Listing history | primaryMarketListings(artworkId) | Use for past sales/history views |
Practical Integration Rules
- Treat product labels as presentation-only; drive logic from GraphQL union/enum types.
- Resolve strategy first, then apply supplementary mechanics.
- For curated flows, always branch from
allowUserSelectionand requireduserInputkeys. - Run reserve checks for gated sales before opening checkout.
- Keep this mapping and Glossary and Name Mapping as your canonical integration references.