Products API

List Products

Retrieve a paginated list of products with optional filtering and sorting.

GET /api/products

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number (1-indexed)
limit	number	20	Items per page (max: 100)
categoryId	number	-	Filter by category ID
categorySlug	string	-	Filter by category slug
minPrice	number	-	Minimum price filter
maxPrice	number	-	Maximum price filter
search	string	-	Search in title and description
sortBy	string	createdAt	Sort field: `price`, `title`, `createdAt`, `rating`
sortOrder	string	desc	Sort direction: `asc`, `desc`
inStock	boolean	-	Filter to in-stock items only
featured	boolean	-	Filter to featured products

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "Elegant Evening Gown",
      "slug": "elegant-evening-gown",
      "description": "A stunning floor-length gown perfect for formal events.",
      "price": 299.99,
      "discountedPrice": 249.99,
      "stock": 15,
      "sku": "EEG-001",
      "images": [
        {
          "id": 1,
          "url": "https://res.cloudinary.com/.../gown-1.jpg",
          "thumbnailUrl": "https://res.cloudinary.com/.../gown-1-thumb.jpg",
          "order": 0
        }
      ],
      "category": {
        "id": 3,
        "title": "Formal Wear",
        "slug": "formal-wear"
      },
      "_count": {
        "reviews": 24
      },
      "avgRating": 4.5,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 156,
      "totalPages": 8,
      "hasMore": true
    }
  }
}

Example Requests

# Get first page of products
curl "https://elite-events.dcsuniverse.com/api/products"

# Search products
curl "https://elite-events.dcsuniverse.com/api/products?search=evening+gown"

# Filter by category and price
curl "https://elite-events.dcsuniverse.com/api/products?categorySlug=formal-wear&minPrice=100&maxPrice=500"

# Sort by price ascending
curl "https://elite-events.dcsuniverse.com/api/products?sortBy=price&sortOrder=asc"

Get Product

Retrieve detailed information about a single product by slug.

GET /api/products/[slug]

Path Parameters

Parameter	Type	Description
slug	string	Product URL slug

Response

{
  "success": true,
  "data": {
    "id": 1,
    "title": "Elegant Evening Gown",
    "slug": "elegant-evening-gown",
    "description": "A stunning floor-length gown perfect for formal events.",
    "details": "Made from premium silk blend fabric with hand-sewn embellishments...",
    "price": 299.99,
    "discountedPrice": 249.99,
    "stock": 15,
    "sku": "EEG-001",
    "specifications": {
      "material": "Silk Blend",
      "care": "Dry Clean Only",
      "sizes": ["XS", "S", "M", "L", "XL"]
    },
    "images": [
      {
        "id": 1,
        "url": "https://res.cloudinary.com/.../gown-1.jpg",
        "thumbnailUrl": "https://res.cloudinary.com/.../gown-1-thumb.jpg",
        "order": 0
      },
      {
        "id": 2,
        "url": "https://res.cloudinary.com/.../gown-2.jpg",
        "thumbnailUrl": "https://res.cloudinary.com/.../gown-2-thumb.jpg",
        "order": 1
      }
    ],
    "category": {
      "id": 3,
      "title": "Formal Wear",
      "slug": "formal-wear",
      "parent": {
        "id": 1,
        "title": "Women's Fashion",
        "slug": "womens-fashion"
      }
    },
    "reviews": {
      "count": 24,
      "avgRating": 4.5,
      "distribution": {
        "5": 15,
        "4": 6,
        "3": 2,
        "2": 1,
        "1": 0
      }
    },
    "relatedProducts": [
      {
        "id": 5,
        "title": "Classic Cocktail Dress",
        "slug": "classic-cocktail-dress",
        "price": 189.99,
        "discountedPrice": 159.99,
        "image": "https://res.cloudinary.com/.../dress-thumb.jpg"
      }
    ],
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-02-20T14:22:00.000Z"
  }
}

Error Response (404)

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Product not found"
  }
}

Get Featured Products

Retrieve products marked as featured for homepage display.

GET /api/products/featured

Query Parameters

Parameter	Type	Default	Description
limit	number	8	Number of products to return

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "Elegant Evening Gown",
      "slug": "elegant-evening-gown",
      "price": 299.99,
      "discountedPrice": 249.99,
      "image": "https://res.cloudinary.com/.../gown-thumb.jpg",
      "category": "Formal Wear"
    }
  ]
}

Get Product Reviews

Retrieve reviews for a specific product.

GET /api/reviews/product/[productId]

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	10	Reviews per page
sortBy	string	createdAt	Sort by: `createdAt`, `rating`, `helpful`
sortOrder	string	desc	Sort direction
rating	number	-	Filter by star rating (1-5)

Response

{
  "success": true,
  "data": [
    {
      "id": 42,
      "rating": 5,
      "comment": "Absolutely beautiful dress! The quality exceeded my expectations.",
      "user": {
        "id": 15,
        "name": "Sarah M.",
        "image": "https://..."
      },
      "helpful": {
        "yes": 12,
        "no": 1
      },
      "createdAt": "2024-02-10T16:45:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 24,
      "totalPages": 3
    },
    "summary": {
      "avgRating": 4.5,
      "totalReviews": 24,
      "distribution": {
        "5": 15,
        "4": 6,
        "3": 2,
        "2": 1,
        "1": 0
      }
    }
  }
}

Create Review (Authenticated)

Submit a product review.

POST /api/reviews

Request Body

{
  "productId": 1,
  "rating": 5,
  "comment": "Absolutely beautiful dress! The quality exceeded my expectations."
}

Validation Rules

Field	Rules
productId	Required, must exist
rating	Required, integer 1-5
comment	Optional, max 2000 characters

Response (201)

{
  "success": true,
  "data": {
    "id": 43,
    "productId": 1,
    "rating": 5,
    "comment": "Absolutely beautiful dress!",
    "createdAt": "2024-03-01T09:15:00.000Z"
  }
}

Error Response (409 - Already Reviewed)

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "You have already reviewed this product"
  }
}

Admin: Create Product

Create a new product (Admin only).

POST /api/admin/products

Request Body

{
  "title": "New Evening Gown",
  "slug": "new-evening-gown",
  "description": "A beautiful new addition to our collection.",
  "details": "Extended product details...",
  "price": 349.99,
  "discountedPrice": 299.99,
  "stock": 50,
  "sku": "NEG-001",
  "categoryId": 3,
  "specifications": {
    "material": "Silk",
    "sizes": ["S", "M", "L"]
  },
  "images": [
    {
      "url": "https://res.cloudinary.com/.../image1.jpg",
      "thumbnailUrl": "https://res.cloudinary.com/.../image1-thumb.jpg"
    }
  ]
}

Response (201)

{
  "success": true,
  "data": {
    "id": 157,
    "title": "New Evening Gown",
    "slug": "new-evening-gown",
    "createdAt": "2024-03-01T10:00:00.000Z"
  }
}

Admin: Update Product

Update an existing product (Admin only).

PUT /api/admin/products/[id]

Request Body

All fields are optional. Only provided fields will be updated.

{
  "title": "Updated Title",
  "price": 399.99,
  "stock": 25
}

Response

{
  "success": true,
  "data": {
    "id": 1,
    "title": "Updated Title",
    "price": 399.99,
    "stock": 25,
    "updatedAt": "2024-03-01T11:00:00.000Z"
  }
}

Admin: Delete Product

Delete a product (Admin only). Products with order history are soft-deleted.

DELETE /api/admin/products/[id]

Response (204)

No content on success.

Error Response (409 - Has Orders)

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Cannot delete product with existing orders. Product has been deactivated instead."
  }
}

Admin: Bulk Update Stock

Update stock for multiple products at once.

POST /api/admin/products/bulk-stock

Request Body

{
  "updates": [
    { "productId": 1, "stock": 100 },
    { "productId": 2, "stock": 50 },
    { "productId": 3, "stock": 0 }
  ]
}

Response

{
  "success": true,
  "data": {
    "updated": 3,
    "products": [
      { "id": 1, "stock": 100 },
      { "id": 2, "stock": 50 },
      { "id": 3, "stock": 0 }
    ]
  }
}

Product Image Upload

Upload product images via Cloudinary.

POST /api/admin/products/upload-image

Request

Multipart form data with image file.

Content-Type: multipart/form-data

file: <binary image data>
productId: 1 (optional)

Response

{
  "success": true,
  "data": {
    "url": "https://res.cloudinary.com/.../image.jpg",
    "thumbnailUrl": "https://res.cloudinary.com/.../image-thumb.jpg",
    "publicId": "elite-events/products/abc123"
  }
}