Marketplace API

Endpoints for buying and selling beers through the marketplace, including listings and transactions.

The Marketplace API enables users to create beer listings for sale, browse available listings, and complete transactions.

Endpoints

GET /api/v1/marketplace/listings

Retrieve marketplace listings with optional filtering.

Query Parameters:

Parameter	Type	Description
q	string	Search query for beer name or description
countryCode	string	Filter by seller country
beerStyle	string	Filter by beer style
minPrice	number	Minimum price
maxPrice	number	Maximum price
condition	string	Item condition (new, like_new, good, fair)
sortBy	string	Sort field (created_at, price, etc.)
sortOrder	string	Sort order (ASC, DESC)
limit	number	Results per page (default: 20)
offset	number	Pagination offset

Response (200 OK):

JSON

{
  "success": true,
  "data": {
    "listings": [
      {
        "id": "uuid",
        "title": "Rare Vintage Beer",
        "description": "Excellent condition vintage beer",
        "price": 25.99,
        "currency": "USD",
        "condition": "like_new",
        "quantityAvailable": 1,
        "beer": {
          "id": "uuid",
          "name": "Vintage Beer",
          "brewery": "Historic Brewery"
        },
        "seller": {
          "id": "uuid",
          "username": "beercollector",
          "rating": 4.8
        },
        "locationCountry": "US",
        "shippingOptions": ["standard", "express"],
        "createdAt": "2024-01-15T10:00:00Z"
      }
    ],
    "pagination": {
      "total": 150,
      "limit": 20,
      "offset": 0
    }
  }
}

POST /api/v1/marketplace/listings

Create a new marketplace listing.

Request Body:

JSON

{
  "collectionItemId": "uuid",
  "title": "Rare Beer for Sale",
  "description": "Mint condition, stored properly",
  "price": 29.99,
  "currency": "USD",
  "condition": "like_new",
  "quantityAvailable": 1,
  "shippingOptions": ["standard", "express"],
  "locationCountry": "US",
  "locationPostalCode": "12345"
}

Response (201 Created):

JSON

{
  "success": true,
  "data": {
    "id": "uuid",
    "title": "Rare Beer for Sale",
    "price": 29.99,
    "status": "active",
    "createdAt": "2024-01-15T10:00:00Z"
  },
  "message": "Listing created successfully"
}

GET /api/v1/marketplace/listings/:id

Retrieve detailed information about a specific listing.

Path Parameters:

id: Listing UUID

Response (200 OK):

JSON

{
  "success": true,
  "data": {
    "id": "uuid",
    "title": "Rare Beer for Sale",
    "description": "Mint condition, stored properly",
    "price": 29.99,
    "currency": "USD",
    "condition": "like_new",
    "quantityAvailable": 1,
    "beer": {
      "id": "uuid",
      "name": "Rare Beer",
      "brewery": "Premium Brewery",
      "style": "Imperial Stout"
    },
    "seller": {
      "id": "uuid",
      "username": "beercollector",
      "rating": 4.8,
      "totalSales": 45
    },
    "photos": ["https://example.com/photo1.jpg"],
    "shippingOptions": [
      {
        "type": "standard",
        "cost": 5.99,
        "estimatedDays": 3
      }
    ],
    "locationCountry": "US",
    "viewCount": 25,
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

POST /api/v1/marketplace/transactions

Create a new transaction (purchase).

Request Body:

JSON

{
  "listingId": "uuid",
  "quantity": 1,
  "currency": "USD",
  "shippingAddress": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "postalCode": "12345",
    "country": "US"
  }
}

Response (201 Created):

JSON

{
  "success": true,
  "data": {
    "id": "uuid",
    "listingId": "uuid",
    "buyerId": "uuid",
    "sellerId": "uuid",
    "quantity": 1,
    "totalAmount": 35.98,
    "currency": "USD",
    "status": "pending",
    "shippingAddress": {
      "street": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "postalCode": "12345",
      "country": "US"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "message": "Transaction created successfully"
}

Listing Conditions

new - Never opened, perfect condition
like_new - Opened but in excellent condition
good - Some wear but fully functional
fair - Noticeable wear but still drinkable

Transaction Status

pending - Awaiting seller confirmation
confirmed - Seller confirmed, payment processing
shipped - Item has been shipped
delivered - Item delivered to buyer
completed - Transaction successfully completed
cancelled - Transaction cancelled

Shipping Options

Type	Description
standard	Standard shipping (3-5 business days)
express	Express shipping (1-2 business days)
overnight	Overnight delivery
pickup	Local pickup only

Error Codes

Code	Description
VALIDATION_ERROR	Invalid request data
NOT_FOUND	Listing not found
UNAUTHORIZED	User not authorized
INSUFFICIENT_QUANTITY	Not enough items available
INVALID_CONDITION	Invalid item condition

Next Steps

Collection API - Manage your beer inventory
Payments API - Handle payment processing
Authentication API - User authentication