Product Management Service

Author: Products Team, NextGate Backend Last Updated: 2025-09-22 Version: v1.0

Short Description: The Products Management API provides comprehensive endpoints for managing e-commerce products and their categories within the NexGate platform. This service enables shop owners to create, manage, and organize their product catalogs with advanced features like group buying, installment options, and dynamic specifications.

Hints:

• All product operations require shop ownership or admin privileges

• Products support hierarchical categories with parent-child relationships

• Advanced features include group buying, installment plans, and color variations

• File uploads for product images should be handled separately via file service

• Products use soft deletion - drafts are hard deleted, published products are archived

• Search and filtering support multiple criteria and real-time inventory tracking

---

API Structure Overview

Product Categories Management

• File: product-categories-api.md

• Base Path: /api/v1/products/categories

• Features: CRUD operations for hierarchical product categories with parent-child relationships

Products Management

• File: products-api.md

• Base Path: /api/v1/shops/{shopId}/products

• Features: Complete product lifecycle management with advanced e-commerce features

---

Key Features Covered

Product Categories

• ✅ Create, update, delete categories

• ✅ Hierarchical category structure (parent/child)

• ✅ Category activation/deactivation

• ✅ Icon URL support for visual representation

• ✅ Pagination support for large category lists

Products Management

• ✅ Draft and publish workflow

• ✅ Rich product specifications (JSON-based)

• ✅ Multiple color variations with price adjustments

• ✅ Group buying functionality with time limits

• ✅ Installment payment plans with interest calculations

• ✅ Advanced search and filtering

• ✅ Inventory tracking with low-stock alerts

• ✅ SEO optimization fields

• ✅ Soft/hard deletion based on product status

Access Control

• 🔒 Shop Owners: Full access to their shop's products

• 🔒 System Admins: Global access across all shops

• 🌐 Public Users: Read-only access to active products only

• 🔐 Authenticated Users: Enhanced browsing capabilities

---

Quick Navigation

Feature	Endpoint Pattern	Documentation
Categories	/api/v1/products/categories/**	product-categories-api.md
Products	/api/v1/shops/{shopId}/products/**	products-api.md

---

Authentication Requirements

• Bearer Token: Required for all create, update, delete operations

• API Key: Optional for enhanced rate limits

• Public Access: Available for browsing active products

• Role-Based: Different access levels based on user roles

---

Rate Limiting

• Authenticated Users: 1000 requests per hour

• Public Users: 100 requests per hour

• File Uploads: 50 uploads per hour

• Search Operations: 200 searches per hour

---

Common Response Formats

All endpoints return responses in the standard NextGate format:

{
  "status": "success",
  "message": "Operation completed successfully",
  "data": { /* Response data */ },
  "timestamp": "2025-09-22T14:30:00Z"
}

Error Handling

Standard HTTP status codes with detailed error messages:

• 400 - Validation errors or bad request data

• 401 - Authentication required

• 403 - Insufficient permissions

• 404 - Resource not found

• 409 - Conflict (duplicate names, etc.)

• 422 - Business logic validation errors

---

Getting Started

1. Authentication: Obtain a valid Bearer token

2. Shop Setup: Ensure your shop exists and is approved

3. Categories: Create product categories first

4. Products: Create products within those categories

5. Publishing: Publish products to make them publicly available

For detailed endpoint documentation, refer to the specific API files linked above.