API Reference
This page documents all marketplace-related API endpoints. All endpoints follow our oRPC contract-first pattern — contracts are defined in @repo/api-dtos and handlers are implemented in @repo/api.
For details on how each feature works, see the relevant documentation pages. This is a quick reference for developers integrating with the API.
Cart Endpoints
The cart is where buyers collect items before checkout. Each user has one cart.
Listings Search
listings.search
Query the listings index (OpenSearch) with product and listing filters. Returns paginated products for sale with embedded listing info (min price per currency, listing count). Use this for searching what’s actually for sale; the marketplace router is reserved for other marketplace features (sales, purchases, orders, etc.).
| Field | Value |
|---|---|
| Auth | Not required (public) |
| Output | { pagination, products } — products include listing: { minPrice, listingCount } |
Input:
- product (optional): Product-level filters.
- gameSlug, expansionSlug, nameSlug: Identity (exact match on slugs).
- category: Exact match on product category.
- type: Product type filter (e.g. card, sealed). In the API this is
product.type; the index field isproduct.productType. - market: Price and change filters (
priceUs,priceEu,change24hUs,change24hEu,change7dUs,change7dEu,change30dUs,change30dEu). - attributes: Game-specific filters (e.g. rarity, color). Game is inferred from
product.gameSlugwhen building the query.
- listing (optional): Listing-level filters:
priceRange,condition,language,shipsTo,currency,graded,gradingService,quantity,sellerId,sellerUsername. - limit: Page size (required).
- offset (optional): Pagination offset.
- sort (optional): Array of
[field, "asc" \| "desc"](e.g.[["product.minPriceUs", "asc"]]).
Checkout Endpoints
Checkout creates a Stripe payment session from the cart.
Create Checkout
checkout.create
Create a Stripe Checkout Session from the current cart.
| Field | Value |
|---|---|
| Auth | Required |
| Output | { sessionUrl, transactionId } |
Possible Errors:
CART_EMPTY— No items in cartITEMS_UNAVAILABLE— Some items no longer availableSHIPPING_UNAVAILABLE— Seller doesn’t ship to buyer’s country
Order Endpoints
Orders are created after checkout succeeds. Buyers and sellers have different views and actions.
Viewing Orders
| Endpoint | Who uses it | Description |
|---|---|---|
order.getOrder | Buyer or Seller | Get a single order by ID |
order.getPurchases | Buyer | List orders where you’re the buyer |
order.getSales | Seller | List orders where you’re the seller |
All list endpoints support:
status(string[]) — Filter by order statuscursor(string) — For paginationlimit(number) — Page size (default 20)
Seller Actions
Buyer Actions
Dispute Endpoints
Disputes handle problems with orders. See Disputes & Refunds for the full flow.
Opening & Managing Disputes
Open Dispute
order.openDispute
Open a dispute on an order.
| Parameter | Type | Required | Description |
|---|---|---|---|
orderId | string | Yes | Order to dispute |
issueCategories | string[] | Yes | What’s wrong (see categories below) |
issueDescription | string | Yes | Detailed explanation |
evidenceUrls | string[] | No | Photos or other proof |
preferredOutcome | string | No | What you’d like to happen |
Issue Categories: missing_item, wrong_condition, counterfeit_resealed, wrong_product, damaged, not_received, other
Requires: Buyer role, order is shipped or delivered, within 30 days
Rating Endpoints
Reviews are submitted after orders complete. See Ratings & Reviews for the simultaneous reveal system.
Seller Endpoints
Seller onboarding and configuration. See Seller Onboarding for the full flow.
Error Handling
All endpoints use typed errors from the contract. In the frontend, you can handle them type-safely:
const [error, data] = await safe(mutation.mutateAsync(input))
if (isDefinedError(error)) {
switch (error.code) {
case 'ORDER_NOT_FOUND':
console.log('Missing order:', error.data.orderId) // Typed!
break
case 'ITEM_NOT_AVAILABLE':
showToast('This item is no longer available')
break
// ... handle other errors
}
}Each error includes typed data with relevant context. Check the contract definitions for the exact shape of each error’s data.
Admin Order Endpoints
These endpoints are used by the internal admin dashboard (marketplace-admin). They require admin authentication.
List Orders
adminOrders.listOrders
List and filter orders for the admin dashboard.
| Parameter | Type | Required | Description |
|---|---|---|---|
page | number | No | Page number (default: 1) |
limit | number | No | Page size (default: 50, max: 100) |
status | string[] | No | Filter by order statuses |
search | string | No | Search by order number or username |
region | string | No | "NA" or "EU" |
hasDispute | boolean | No | Filter orders with disputes |
isEscalated | boolean | No | Filter escalated disputes |
shippingStatus | string | No | Filter by tracking status |
fundOperationStatus | string | No | Filter by fund operation state |
dateFrom / dateTo | string | No | Date range filter (ISO datetime) |
sortBy | string | No | "createdAt", "updatedAt", "orderNumber", or "subtotal" |
sortOrder | string | No | "asc" or "desc" |
Returns { orders, total, page, totalPages }.