Marketplace Overview
The CardNexus Marketplace is where users come to buy and sell trading cards directly with each other. Think of it as a peer-to-peer marketplace specifically designed for the trading card community — handling everything from browsing listings to secure payments to dispute resolution.
This documentation will help you understand how all the pieces fit together, whether you’re debugging an order issue, adding a new feature, or just trying to understand the business logic.
What You’ll Learn
Key Concepts
Before diving into the details, here are the core concepts you’ll encounter throughout the marketplace:
| Term | Description |
|---|---|
| Transaction | A single payment from a buyer. If they’re buying from multiple sellers, one transaction creates multiple orders. |
| Order | What a seller fulfills. One order = one seller’s items from a transaction. |
| Cart | A buyer’s shopping cart. It has constraints — single currency, single region, all sellers must ship to the buyer’s country. |
| Seller Profile | A user’s selling configuration — their Stripe Connect account, shipping rates, and status. |
| Dispute | When a buyer has an issue with their order. We have a structured proposal/acceptance flow to resolve these. |
| Review Window | The 7-day period after an order completes where both parties can review each other. |
How Everything Connects
Here’s a bird’s-eye view of the marketplace architecture. Don’t worry about memorizing this — we’ll go deeper into each piece in the following pages.
Regional Structure
The marketplace operates in two distinct regions. This matters because NA and EU use separate Stripe accounts, so they can’t be combined in a single checkout. Each region operates as its own payment ecosystem.
A cart can only contain items from sellers in the same region. If a buyer tries to add an item from a different region, they’ll need to checkout their current cart first or clear it.
| Region | Countries | Currencies |
|---|---|---|
| North America | US, CA | USD, CAD |
| Europe | AT, BE, CY, CH, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IT, LT, LU, LV, MT, NL, NO, PL, PT, SE, SI, SK | EUR, GBP, CHF, SEK, DKK, NOK, PLN, HUF |
The buyer’s selected country determines their currency. For example, a buyer in Germany pays in EUR, while a buyer in the UK pays in GBP.
Fee Structure
We charge fees to sustain the platform. The structure is straightforward:
Seller fees are a percentage of each order (subtotal + shipping):
| Region | Seller Fee |
|---|---|
| Europe | 5% |
| North America | 8% |
Buyer fees are calculated per transaction as a percentage plus a small fixed amount. The exact rates are configured in the system and may vary by currency.
Fees are calculated at checkout time and “snapshotted” — if we later change fee rates, existing orders aren’t affected.
Where to Find the Code
Here’s a quick reference for the main code locations. Each subsequent page will point to more specific files.
| Component | Location | Purpose |
|---|---|---|
| Models | packages/core/db/src/mongo/marketplace/ | MongoDB schemas for Order, Transaction, Cart, OrderReview |
| Order Domain | packages/backend/domains/order/ | Pure business logic for order rules |
| Rating Domain | packages/backend/domains/rating/ | Review windows and rating aggregation |
| Checkout Feature | packages/backend/features/checkout/ | Checkout session creation |
| Orders Feature | packages/backend/features/orders/ | Order orchestration, refunds, fund release |
| API Contracts | packages/core/api-dtos/src/lib/marketplace/ | oRPC contracts for all endpoints |
| API Handlers | packages/backend/api/src/lib/orpc/handlers/marketplace/ | Handler implementations |
The Happy Path
Before we get into edge cases and error handling, here’s what a successful transaction looks like:
Most transactions follow this path. The complexity comes from handling the exceptions — cancellations, disputes, refunds — which we’ll cover in the following pages.
Next Steps
Ready to dive deeper? Here’s the recommended reading order:
Order Lifecycle
Start here to understand how orders move through their various states, from creation to completion (or cancellation).
Checkout Flow
Learn how a cart becomes a paid transaction, including Stripe integration and webhook handling.
Seller Onboarding
Understand how users become sellers through Stripe Connect, including the differences between Individual and Pro sellers.
Disputes & Refunds
See how we handle problems — from simple cancellations to complex dispute resolution.
Ratings & Reviews
Discover our “simultaneous reveal” review system that keeps feedback honest.
Fund Management
Finally, understand how money flows through the system and when sellers get paid.