Product Management

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: 2025-09-23
Version: v1.0

Short Description: The Product Management API provides comprehensive functionality for managing products within shops on the NextGate platform. It supports advanced features including group buying, installment payments, color variations, specifications, comprehensive search and filtering capabilities with role-based access control.

Hints:

Endpoints

1. Create Product

Purpose: Creates a new product in a shop with support for all advanced features including group buying, installments, color variations, and specifications

Endpoint: POST /api/v1/shops/{shopId}/products

Access Level: 🔒 Protected (Requires shop owner or system admin role)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	application/json

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	ID of the shop to create product in	Valid UUID format, shop must exist and be active

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
action	ReqAction	Yes	Action to perform on product	SAVE_DRAFT, SAVE_PUBLISH	None

Request JSON Sample:

{
  "productName": "iPhone 15 Pro Max 256GB",
  "productDescription": "The most advanced iPhone ever, featuring the groundbreaking A17 Pro chip, titanium design, and the most versatile Pro camera system. With a 6.7-inch Super Retina XDR display, Action Button, and up to 29 hours of video playback battery life.",
  "shortDescription": "Premium 6.7-inch iPhone with A17 Pro chip and titanium design",
  "price": 1199.00,
  "comparePrice": 1299.00,
  "stockQuantity": 25,
  "lowStockThreshold": 5,
  "categoryId": "123e4567-e89b-12d3-a456-426614174000",
  "brand": "Apple",
  "condition": "NEW",
  "productImages": [
    "https://example.com/images/iphone15-pro-max-main.jpg",
    "https://example.com/images/iphone15-pro-max-side.jpg",
    "https://example.com/images/iphone15-pro-max-back.jpg",
    "https://example.com/images/iphone15-pro-max-camera.jpg"
  ],
  "tags": ["smartphone", "apple", "premium", "5g", "titanium", "pro-camera"],
  "specifications": {
    "Display": "6.7-inch Super Retina XDR OLED",
    "Chip": "A17 Pro with 6-core GPU",
    "Storage": "256GB",
    "RAM": "8GB",
    "Rear Camera": "48MP Main, 12MP Ultra Wide, 12MP Telephoto",
    "Front Camera": "12MP TrueDepth",
    "Battery Life": "Up to 29 hours video playback",
    "Operating System": "iOS 17",
    "Connectivity": "5G, Wi-Fi 6E, Bluetooth 5.3",
    "Materials": "Titanium frame, Ceramic Shield front",
    "Water Resistance": "IP68 (6 meters for up to 30 minutes)",
    "Dimensions": "159.9 x 76.7 x 8.25 mm",
    "Weight": "221 grams"
  },
  "colors": [
    {
      "name": "Natural Titanium",
      "hex": "#F5F5DC",
      "images": [
        "https://example.com/colors/iphone-natural-titanium-1.jpg",
        "https://example.com/colors/iphone-natural-titanium-2.jpg"
      ],
      "priceAdjustment": 0.00
    },
    {
      "name": "Blue Titanium",
      "hex": "#4A90E2",
      "images": [
        "https://example.com/colors/iphone-blue-titanium-1.jpg",
        "https://example.com/colors/iphone-blue-titanium-2.jpg"
      ],
      "priceAdjustment": 0.00
    },
    {
      "name": "White Titanium",
      "hex": "#FFFFFF",
      "images": [
        "https://example.com/colors/iphone-white-titanium-1.jpg",
        "https://example.com/colors/iphone-white-titanium-2.jpg"
      ],
      "priceAdjustment": 0.00
    },
    {
      "name": "Black Titanium",
      "hex": "#1C1C1E",
      "images": [
        "https://example.com/colors/iphone-black-titanium-1.jpg",
        "https://example.com/colors/iphone-black-titanium-2.jpg"
      ],
      "priceAdjustment": 50.00
    }
  ],
  "minOrderQuantity": 1,
  "maxOrderQuantity": 3,
  "maxPerCustomer": 2,
  "requiresApproval": false,
  "groupBuyingEnabled": true,
  "groupMinSize": 10,
  "groupMaxSize": 50,
  "groupPrice": 1099.00,
  "groupTimeLimitHours": 72,
  "groupRequiresMinimum": true,
  "installmentEnabled": true,
  "installmentPlans": [
    {
      "duration": 6,
      "interval": "MONTHS",
      "interestRate": 0.00,
      "description": "6 months interest-free installment"
    },
    {
      "duration": 12,
      "interval": "MONTHS",
      "interestRate": 2.90,
      "description": "12 months with low interest rate"
    },
    {
      "duration": 24,
      "interval": "MONTHS",
      "interestRate": 5.90,
      "description": "24 months extended payment plan"
    }
  ],
  "downPaymentRequired": true,
  "minDownPaymentPercentage": 20.00,
  "trackInventory": true,
  "isFeatured": true,
  "isDigital": false,
  "requiresShipping": true,
  "metaTitle": "iPhone 15 Pro Max 256GB - Premium Titanium Smartphone | TechStore Pro",
  "metaDescription": "Buy the latest iPhone 15 Pro Max with 256GB storage, A17 Pro chip, and titanium design. Available with group buying discounts and flexible installment plans."
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
productName	string	Yes	Unique name of the product within shop	Min: 2, Max: 100 characters
productDescription	string	Yes	Detailed product description	Min: 10, Max: 1000 characters
price	decimal	Yes	Product selling price	Min: 0.01, Max: 8 digits with 2 decimal places
stockQuantity	integer	Yes	Available stock quantity	Min: 0
categoryId	UUID	Yes	Product category identifier	Must exist and be active
shortDescription	string	No	Brief product summary	Max: 200 characters
comparePrice	decimal	No	Original price for discount display	Must be greater than price if provided
lowStockThreshold	integer	No	Low stock alert threshold	Min: 1, Max: 1000, Default: 5
brand	string	No	Product brand name	Max: 100 characters
sku	string	No	Custom Stock Keeping Unit	Max: 50 characters, auto-generated if not provided
condition	ProductCondition	No	Product condition	NEW, USED_LIKE_NEW, USED_GOOD, USED_FAIR, REFURBISHED, FOR_PARTS
status	ProductStatus	No	Initial product status	DRAFT, ACTIVE, INACTIVE, OUT_OF_STOCK, ARCHIVED
productImages	array	Yes	Product image URLs	Valid URLs, cannot be empty, at least 1 required
tags	array	No	Product tags for categorization	Max 50 characters per tag
specifications	object	No	Technical product specifications	Key: max 100 chars, Value: max 500 chars
colors	array	No	Available color variations	Color objects with name, hex, images, priceAdjustment
minOrderQuantity	integer	No	Minimum order quantity	Min: 1, Default: 1
maxOrderQuantity	integer	No	Maximum order quantity per order	Min: 1, must be >= minOrderQuantity
maxPerCustomer	integer	No	Maximum quantity per customer	Min: 1
requiresApproval	boolean	No	Requires manual approval for orders	Default: false
groupBuyingEnabled	boolean	No	Enable group buying feature	Default: false
groupMinSize	integer	No	Minimum group participants	Min: 2, required if groupBuyingEnabled=true
groupMaxSize	integer	No	Maximum group participants	Min: 2, must be >= groupMinSize
groupPrice	decimal	No	Discounted group price	Must be less than regular price
groupTimeLimitHours	integer	No	Group formation time limit	Min: 1, Max: 8760 (1 year)
groupRequiresMinimum	boolean	No	Group must reach minimum size	Default: true
installmentEnabled	boolean	No	Enable installment payments	Default: false
installmentPlans	array	No	Available payment plans	Required if installmentEnabled=true
installmentPlans[].duration	integer	Yes	Payment plan duration	Min: 1
installmentPlans[].interval	string	Yes	Payment interval	DAYS, WEEKS, MONTHS
installmentPlans[].interestRate	decimal	Yes	Interest rate percentage	Min: 0, Max: 100, 2 decimal places
installmentPlans[].description	string	No	Plan description	Max: 200 characters
downPaymentRequired	boolean	No	Require down payment	Default: false
minDownPaymentPercentage	decimal	No	Minimum down payment percentage	Min: 0, Max: 100, 2 decimal places
trackInventory	boolean	No	Track inventory changes	Default: true
isFeatured	boolean	No	Mark as featured product	Default: false
isDigital	boolean	No	Digital product (no shipping)	Default: false
requiresShipping	boolean	No	Physical shipping required	Default: true
metaTitle	string	No	SEO meta title	Max: 100 characters
metaDescription	string	No	SEO meta description	Max: 200 characters

Color Request Object Structure:

{
  "name": "Color Name",
  "hex": "#HEXCODE",
  "images": ["url1", "url2"],
  "priceAdjustment": 0.00
}

Installment Plan Request Object Structure:

{
  "duration": 12,
  "interval": "MONTHS",
  "interestRate": 2.90,
  "description": "12 months low interest"
}

Response JSON Sample:

{
  "success": true,
  "message": "Product created successfully",
  "data": null
}

Response Fields:

Field	Description
success	Boolean indicating operation success
message	Human-readable success message
data	Additional response data (null for create operation)

Business Rules:

Product name must be unique within the shop
If comparePrice is provided, it must be greater than price
Group buying requires groupMinSize ≤ groupMaxSize
Group price must be less than regular price
Installment plans required when installmentEnabled=true
At least one installment plan must be provided
Color hex codes must be valid 6-digit hex format
All image URLs must be valid and accessible
Category must exist and be active
Shop must exist and be active
User must be shop owner or system admin

Validation Rules:

@AssertTrue Group maximum size must be greater than minimum size
@AssertTrue Group price must be less than regular price
@AssertTrue Maximum order quantity must be greater than minimum order quantity
@AssertTrue Compare price must be greater than regular price
@AssertTrue At least one installment plan required when installments enabled
@AssertTrue Group buying settings required when group buying enabled

Error Responses:

400 Bad Request: Invalid request data, validation errors, or business rule violations
401 Unauthorized: Authentication required or invalid token
403 Forbidden: Insufficient permissions (shop owner or system admin required)
404 Not Found: Shop not found or category not found/inactive
409 Conflict: Product with same name, brand, price, and specifications already exists in shop
422 Unprocessable Entity: Validation errors with detailed field-level messages
500 Internal Server Error: Server error during product creation

2. Update Product

Purpose: Updates an existing product with support for all advanced features and partial updates

Endpoint: PUT /api/v1/shops/{shopId}/products/{productId}

Access Level: 🔒 Protected (Requires shop owner or system admin role)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	application/json

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	ID of the shop	Valid UUID format, shop must exist
productId	UUID	Yes	ID of the product to update	Valid UUID format, product must exist in shop

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
action	ReqAction	Yes	Action to perform after update	SAVE_DRAFT, SAVE_PUBLISH	None

Request JSON Sample:

{
  "productName": "iPhone 15 Pro Max 512GB - Updated",
  "price": 1399.00,
  "comparePrice": 1499.00,
  "stockQuantity": 15,
  "groupPrice": 1299.00,
  "specifications": {
    "Display": "6.7-inch Super Retina XDR OLED",
    "Storage": "512GB",
    "RAM": "8GB",
    "New Feature": "Enhanced Night Mode"
  },
  "installmentPlans": [
    {
      "duration": 6,
      "interval": "MONTHS",
      "interestRate": 0.00,
      "description": "6 months interest-free"
    },
    {
      "duration": 18,
      "interval": "MONTHS",
      "interestRate": 4.50,
      "description": "18 months flexible payment"
    }
  ],
  "tags": ["smartphone", "apple", "premium", "5g", "512gb", "pro-max"]
}

Request Body Parameters: All parameters are optional for updates. Only provided fields will be updated.

Parameter	Type	Required	Description	Validation
productName	string	No	Updated product name	Min: 2, Max: 100 characters, unique in shop
productDescription	string	No	Updated description	Min: 10, Max: 1000 characters
shortDescription	string	No	Updated short description	Max: 200 characters
price	decimal	No	Updated selling price	Min: 0.01, Max: 8 digits with 2 decimal places
comparePrice	decimal	No	Updated original price	Must be greater than price if provided
stockQuantity	integer	No	Updated stock quantity	Min: 0
lowStockThreshold	integer	No	Updated low stock threshold	Min: 1, Max: 1000
brand	string	No	Updated brand name	Max: 100 characters
sku	string	No	Updated SKU	Max: 50 characters, unique if changed
condition	ProductCondition	No	Updated condition	NEW, USED_LIKE_NEW, USED_GOOD, USED_FAIR, REFURBISHED, FOR_PARTS
status	ProductStatus	No	Updated status	DRAFT, ACTIVE, INACTIVE, OUT_OF_STOCK, ARCHIVED
categoryId	UUID	No	Updated category	Must exist and be active
productImages	array	No	Updated image URLs	Valid URLs
tags	array	No	Updated tags	Max 50 characters per tag
specifications	object	No	Updated specifications	Completely replaces existing specifications
colors	array	No	Updated color variations	Completely replaces existing colors
minOrderQuantity	integer	No	Updated minimum order	Min: 1
maxOrderQuantity	integer	No	Updated maximum order	Min: 1, must be >= minOrderQuantity
requiresApproval	boolean	No	Updated approval requirement	true/false
groupBuyingEnabled	boolean	No	Enable/disable group buying	true/false
groupMinSize	integer	No	Updated group minimum	Min: 2, required if enabling group buying
groupMaxSize	integer	No	Updated group maximum	Min: 2, must be >= groupMinSize
groupPrice	decimal	No	Updated group price	Must be less than regular price
groupTimeLimitHours	integer	No	Updated group time limit	Min: 1, Max: 8760
groupRequiresMinimum	boolean	No	Updated group requirement	true/false
installmentEnabled	boolean	No	Enable/disable installments	true/false
installmentPlans	array	No	Updated installment plans	Replaces existing plans, required if enabling
downPaymentRequired	boolean	No	Updated down payment requirement	true/false
minDownPaymentPercentage	decimal	No	Updated down payment percentage	Min: 0, Max: 100
isFeatured	boolean	No	Updated featured status	true/false
isDigital	boolean	No	Updated digital product flag	true/false
requiresShipping	boolean	No	Updated shipping requirement	true/false
metaTitle	string	No	Updated SEO title	Max: 100 characters
metaDescription	string	No	Updated SEO description	Max: 200 characters

Response JSON Sample:

{
  "success": true,
  "message": "Product updated successfully and published",
  "data": {
    "productId": "456e7890-e89b-12d3-a456-426614174001",
    "productName": "iPhone 15 Pro Max 512GB - Updated",
    "productSlug": "iphone-15-pro-max-512gb-updated",
    "price": 1399.00,
    "comparePrice": 1499.00,
    "status": "ACTIVE",
    "stockQuantity": 15,
    "updatedAt": "2025-09-23T14:30:00Z",
    "sku": "SHP12345678-ELE-APP-512-0001"
  }
}

Business Rules for Updates:

Product name uniqueness checked only if name is being changed
SKU uniqueness validated only if SKU is being changed
Group buying settings must be complete when enabling feature
Installment plans required when enabling installment feature
Category must exist and be active if being changed
Action parameter determines final status regardless of status field

Error Responses:

400 Bad Request: Invalid update data or validation errors
401 Unauthorized: Authentication required
403 Forbidden: Insufficient permissions
404 Not Found: Shop or product not found
409 Conflict: Updated product name or SKU already exists
422 Unprocessable Entity: Validation errors

3. Publish Product

Purpose: Publishes a draft product making it active and publicly available

Endpoint: PATCH /api/v1/shops/{shopId}/products/{productId}/publish

Access Level: 🔒 Protected (Requires shop owner or system admin role)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	ID of the shop	Valid UUID format, shop must exist
productId	UUID	Yes	ID of the product to publish	Valid UUID format, product must exist and be draft

Response JSON Sample:

{
  "success": true,
  "message": "Product 'iPhone 15 Pro Max 512GB' published successfully",
  "data": {
    "productId": "456e7890-e89b-12d3-a456-426614174001",
    "productName": "iPhone 15 Pro Max 512GB",
    "productSlug": "iphone-15-pro-max-512gb",
    "status": "ACTIVE",
    "publishedAt": "2025-09-23T14:45:00Z",
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "TechStore Pro"
  }
}

Publishing Validation Requirements:

Product name must not be empty
Product description must not be empty
Price must be greater than 0
Stock quantity must be >= 0
Category must be assigned and active
At least one product image required
Group buying settings complete if enabled
Installment plans present if installments enabled

Error Responses:

400 Bad Request: Product already published or missing required fields for publishing
401 Unauthorized: Authentication required
403 Forbidden: Insufficient permissions
404 Not Found: Shop or product not found

4. Delete Product

Purpose: Deletes a product using different strategies based on product status

Endpoint: DELETE /api/v1/shops/{shopId}/products/{productId}

Access Level: 🔒 Protected (Requires shop owner or system admin role)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	ID of the shop	Valid UUID format, shop must exist
productId	UUID	Yes	ID of the product to delete	Valid UUID format, product must exist

Response JSON Sample (Soft Delete):

{
  "success": true,
  "message": "Product 'iPhone 15 Pro Max 512GB' has been deleted and will be permanently removed after 30 days",
  "data": {
    "message": "Product 'iPhone 15 Pro Max 512GB' has been deleted and will be permanently removed after 30 days",
    "productName": "iPhone 15 Pro Max 512GB",
    "productId": "456e7890-e89b-12d3-a456-426614174001",
    "previousStatus": "ACTIVE",
    "deletedAt": "2025-09-23T15:00:00Z",
    "deletionType": "SOFT_DELETE",
    "note": "Product will be permanently deleted after 30 days"
  }
}

Response JSON Sample (Hard Delete):

{
  "success": true,
  "message": "Draft product 'iPhone 15 Pro Max 512GB' has been permanently deleted",
  "data": null
}

Deletion Logic:

Draft Products: Hard delete (permanently removed from database)
Published Products: Soft delete (marked as deleted, status changed to ARCHIVED)
Soft Deleted Products: Marked with deletion timestamp and deleted by user ID
Recovery Period: 30 days for soft-deleted products before permanent removal

Error Responses:

401 Unauthorized: Authentication required
403 Forbidden: Insufficient permissions
404 Not Found: Shop or product not found

5. Restore Product

Purpose: Restores a soft-deleted product back to draft status

Endpoint: PATCH /api/v1/shops/{shopId}/products/{productId}/restore

Access Level: 🔒 Protected (Requires shop owner or system admin role)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	ID of the shop	Valid UUID format, shop must exist
productId	UUID	Yes	ID of the product to restore	Valid UUID format, product must be soft-deleted

Response JSON Sample:

{
  "success": true,
  "message": "Product 'iPhone 15 Pro Max 512GB' has been restored successfully",
  "data": {
    "productId": "456e7890-e89b-12d3-a456-426614174001",
    "productName": "iPhone 15 Pro Max 512GB",
    "productSlug": "iphone-15-pro-max-512gb",
    "status": "DRAFT",
    "restoredAt": "2025-09-23T15:30:00Z",
    "isDeleted": false,
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "note": "Product restored as draft. Publish to make it active again."
  }
}

Restoration Process:

Sets isDeleted flag to false
Clears deletedAt and deletedBy fields
Sets status to DRAFT for safety (requires manual publishing)
Updates editedBy and updatedAt timestamps

Error Responses:

400 Bad Request: Product is not deleted and cannot be restored
401 Unauthorized: Authentication required
403 Forbidden: Insufficient permissions
404 Not Found: Shop or product not found

6. Get Product Detailed (Owner/Admin View)

Purpose: Retrieves comprehensive product details with all features and management information

Endpoint: GET /api/v1/shops/{shopId}/products/{productId}/detailed

Access Level: 🔒 Protected (Requires shop owner or system admin role)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	ID of the shop	Valid UUID format, shop must exist
productId	UUID	Yes	ID of the product	Valid UUID format, product must exist in shop

Response JSON Sample:

{
  "success": true,
  "message": "Product details retrieved successfully",
  "data": {
    "productId": "456e7890-e89b-12d3-a456-426614174001",
    "productName": "iPhone 15 Pro Max 512GB",
    "productSlug": "iphone-15-pro-max-512gb",
    "productDescription": "The most advanced iPhone ever, featuring the groundbreaking A17 Pro chip...",
    "shortDescription": "Premium 6.7-inch iPhone with A17 Pro chip and titanium design",
    "productImages": [
      "https://example.com/images/iphone15-pro-max-main.jpg",
      "https://example.com/images/iphone15-pro-max-side.jpg"
    ],
    "price": 1199.00,
    "comparePrice": 1299.00,
    "discountAmount": 100.00,
    "discountPercentage": 7.69,
    "isOnSale": true,
    "stockQuantity": 25,
    "lowStockThreshold": 5,
    "isInStock": true,
    "isLowStock": false,
    "trackInventory": true,
    "brand": "Apple",
    "sku": "SHP12345678-ELE-APP-512-0001",
    "condition": "NEW",
    "status": "ACTIVE",
    "tags": ["smartphone", "apple", "premium", "5g", "titanium"],
    "metaTitle": "iPhone 15 Pro Max 512GB - Premium Titanium Smartphone",
    "metaDescription": "Buy the latest iPhone 15 Pro Max with 512GB storage...",
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "TechStore Pro",
    "shopSlug": "techstore-pro",
    "categoryId": "789e0123-e89b-12d3-a456-426614174002",
    "categoryName": "Smartphones",
    "isFeatured": true,
    "isDigital": false,
    "requiresShipping": true,
    "createdAt": "2025-09-23T10:30:00Z",
    "updatedAt": "2025-09-23T14:30:00Z",
    "createdBy": "111e2222-e89b-12d3-a456-426614174003",
    "editedBy": "111e2222-e89b-12d3-a456-426614174003",
    "specifications": {
      "Display": "6.7-inch Super Retina XDR OLED",
      "Chip": "A17 Pro with 6-core GPU",
      "Storage": "512GB",
      "RAM": "8GB",
      "Battery Life": "Up to 29 hours video playback",
      "Water Resistance": "IP68"
    },
    "hasSpecifications": true,
    "specificationCount": 6,
    "colors": [
      {
        "name": "Natural Titanium",
        "hex": "#F5F5DC",
        "images": ["https://example.com/colors/natural-titanium.jpg"],
        "priceAdjustment": 0.00,
        "finalPrice": 1199.00,
        "hasExtraFee": false,
        "extraFeeReason": null
      },
      {
        "name": "Black Titanium",
        "hex": "#1C1C1E",
        "images": ["https://example.com/colors/black-titanium.jpg"],
        "priceAdjustment": 50.00,
        "finalPrice": 1249.00,
        "hasExtraFee": true,
        "extraFeeReason": "Premium color finish"
      }
    ],
    "hasMultipleColors": true,
    "colorCount": 2,
    "priceRange": {
      "minPrice": 1199.00,
      "maxPrice": 1249.00,
      "priceStartsFrom": 1199.00,
      "hasPriceVariations": true
    },
    "orderingLimits": {
      "minOrderQuantity": 1,
      "maxOrderQuantity": 3,
      "requiresApproval": false,
      "canOrderQuantity": 3,
      "maxAllowedQuantity": 3,
      "hasOrderingLimits": true
    },
    "groupBuying": {
      "isEnabled": true,
      "isAvailable": true,
      "minGroupSize": 10,
      "maxGroupSize": 50,
      "currentGroupSize": 7,
      "remainingSlots": 43,
      "progressPercentage": 70.0,
      "groupPrice": 1099.00,
      "groupDiscount": 100.00,
      "groupDiscountPercentage": 8.34,
      "timeLimitHours": 72,
      "timeRemainingHours": 48,
      "expiresAt": "2025-09-25T10:30:00Z",
      "requiresMinimum": true,
      "status": "PENDING",
      "canJoinGroup": true
    },
    "installmentOptions": {
      "isEnabled": true,
      "isAvailable": true,
      "downPaymentRequired": true,
      "minDownPaymentPercentage": 20.00,
      "eligibilityStatus": "ELIGIBLE",
      "creditCheckRequired": false,
      "plans": [
        {
          "planId": "plan-6m",
          "duration": 6,
          "interval": "MONTHS",
          "interestRate": 0.00,
          "description": "6 months interest-free installment",
          "isPopular": true,
          "calculations": {
            "downPayment": 239.80,
            "remainingAmount": 959.20,
            "totalInterest": 0.00,
            "paymentAmount": 159.87,
            "totalAmount": 1199.00
          },
          "paymentSchedule": [
            {
              "paymentNumber": 1,
              "amount": 159.87,
              "dueDate": "2025-10-23T00:00:00Z",
              "description": "Month 1 payment"
            },
            {
              "paymentNumber": 2,
              "amount": 159.87,
              "dueDate": "2025-11-23T00:00:00Z",
              "description": "Month 2 payment"
            }
          ]
        }
      ]
    },
    "purchaseOptions": {
      "canBuyNow": true,
      "canJoinGroup": true,
      "canPayInstallment": true,
      "recommendedOption": "GROUP_BUYING",
      "bestDeal": {
        "option": "GROUP_BUYING",
        "savings": 100.00,
        "finalPrice": 1099.00
      }
    }
  }
}

Response Fields:

Field	Description
Basic product information	productId, productName, productSlug, descriptions, images
Pricing details	price, comparePrice, discount calculations, sale status
Inventory information	stock quantities, availability status, tracking settings
Product details	brand, SKU, condition, status, category information
Shop information	shopId, shopName, shopSlug
Advanced features	specifications, colors, group buying, installments
Management data	creation/update timestamps, user IDs, featured status
Purchase options	available buying methods and recommendations

Error Responses:

401 Unauthorized: Authentication required
403 Forbidden: Insufficient permissions (shop owner or admin required)
404 Not Found: Shop or product not found

7. Get Shop Products (Management View)

Purpose: Retrieves all products for shop management with summary statistics

Endpoint: GET /api/v1/shops/{shopId}/products/all

Access Level: 🔒 Protected (Requires shop owner or system admin role)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	ID of the shop	Valid UUID format, shop must exist

Response JSON Sample:

{
  "success": true,
  "message": "Retrieved 47 products from shop: TechStore Pro",
  "data": {
    "shop": {
      "shopId": "123e4567-e89b-12d3-a456-426614174000",
      "shopName": "TechStore Pro",
      "shopSlug": "techstore-pro",
      "logoUrl": "https://example.com/logos/techstore-pro.png",
      "isVerified": true,
      "isApproved": true,
      "isMyShop": true
    },
    "summary": {
      "totalProducts": 47,
      "activeProducts": 35,
      "draftProducts": 8,
      "outOfStockProducts": 4,
      "featuredProducts": 12,
      "lowStockProducts": 6,
      "averagePrice": 649.75,
      "totalInventoryValue": 89543.25,
      "productsWithGroupBuying": 18,
      "productsWithInstallments": 25,
      "productsWithMultipleColors": 14
    },
    "products": [
      {
        "productId": "456e7890-e89b-12d3-a456-426614174001",
        "productName": "iPhone 15 Pro Max 512GB",
        "productSlug": "iphone-15-pro-max-512gb",
        "shortDescription": "Premium 6.7-inch iPhone with A17 Pro chip",
        "primaryImage": "https://example.com/images/iphone15-pro-max-main.jpg",
        "price": 1199.00,
        "comparePrice": 1299.00,
        "finalPrice": 1199.00,
        "isOnSale": true,
        "discountPercentage": 7.69,
        "stockQuantity": 25,
        "isInStock": true,
        "isLowStock": false,
        "brand": "Apple",
        "sku": "SHP12345678-ELE-APP-512-0001",
        "condition": "NEW",
        "status": "ACTIVE",
        "isFeatured": true,
        "isDigital": false,
        "hasGroupBuying": true,
        "hasInstallments": true,
        "hasMultipleColors": true,
        "groupPrice": 1099.00,
        "startingFromPrice": 1199.00,
        "createdAt": "2025-09-23T10:30:00Z"
      }
    ],
    "totalProducts": 47
  }
}

Summary Statistics Fields:

Field	Description
totalProducts	Total number of products in shop
activeProducts	Products with ACTIVE status
draftProducts	Products with DRAFT status
outOfStockProducts	Products with zero stock
featuredProducts	Products marked as featured
lowStockProducts	Products below low stock threshold
averagePrice	Average price of all products
totalInventoryValue	Total value of inventory (price × stock)
productsWithGroupBuying	Products with group buying enabled
productsWithInstallments	Products with installment options
productsWithMultipleColors	Products with color variations

Error Responses:

401 Unauthorized: Authentication required
403 Forbidden: Insufficient permissions
404 Not Found: Shop not found or deleted

8. Get Shop Products Paginated (Management View)

Purpose: Retrieves shop products with pagination for management dashboard

Endpoint: GET /api/v1/shops/{shopId}/products/all-paged

Access Level: 🔒 Protected (Requires shop owner or system admin role)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	ID of the shop	Valid UUID format, shop must exist

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-indexed)	Min: 1	1
size	integer	No	Items per page	Min: 1, Max: 100	10

Response JSON Sample:

{
  "success": true,
  "message": "Retrieved 10 products from shop: TechStore Pro (Page 1 of 5)",
  "data": {
    "contents": {
      "shop": {
        "shopId": "123e4567-e89b-12d3-a456-426614174000",
        "shopName": "TechStore Pro",
        "shopSlug": "techstore-pro",
        "logoUrl": "https://example.com/logos/techstore-pro.png",
        "isVerified": true,
        "isApproved": true,
        "isMyShop": true
      },
      "summary": {
        "totalProducts": 47,
        "activeProducts": 35,
        "draftProducts": 8,
        "averagePrice": 649.75,
        "totalInventoryValue": 89543.25
      },
      "products": [
        {
          "productId": "456e7890-e89b-12d3-a456-426614174001",
          "productName": "iPhone 15 Pro Max 512GB",
          "price": 1199.00,
          "stockQuantity": 25,
          "status": "ACTIVE",
          "isInStock": true,
          "hasGroupBuying": true,
          "hasInstallments": true,
          "createdAt": "2025-09-23T10:30:00Z"
        }
      ],
      "totalProducts": 10
    },
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 47,
    "totalPages": 5,
    "hasNext": true,
    "hasPrevious": false
  }
}

Pagination Fields:

Field	Description
currentPage	Current page number (1-indexed)
pageSize	Number of items per page
totalElements	Total number of products
totalPages	Total number of pages
hasNext	Whether there is a next page
hasPrevious	Whether there is a previous page

Error Responses:

401 Unauthorized: Authentication required
403 Forbidden: Insufficient permissions
404 Not Found: Shop not found

9. Get Public Product by ID

Purpose: Retrieves a single active product for public viewing with customer-focused information

Endpoint: GET /api/v1/shops/{shopId}/products/{productId}

Access Level: 🌐 Public (No authentication required)

Authentication: None

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	ID of the shop	Valid UUID format, shop must be active and approved
productId	UUID	Yes	ID of the product	Valid UUID format, product must be active

Response JSON Sample:

{
  "success": true,
  "message": "Product retrieved successfully",
  "data": {
    "productId": "456e7890-e89b-12d3-a456-426614174001",
    "productName": "iPhone 15 Pro Max 512GB",
    "productSlug": "iphone-15-pro-max-512gb",
    "productDescription": "The most advanced iPhone ever, featuring the groundbreaking A17 Pro chip...",
    "shortDescription": "Premium 6.7-inch iPhone with A17 Pro chip and titanium design",
    "productImages": [
      "https://example.com/images/iphone15-pro-max-main.jpg",
      "https://example.com/images/iphone15-pro-max-side.jpg"
    ],
    "price": 1199.00,
    "comparePrice": 1299.00,
    "discountAmount": 100.00,
    "discountPercentage": 7.69,
    "isOnSale": true,
    "isInStock": true,
    "isLowStock": false,
    "stockQuantity": 25,
    "brand": "Apple",
    "condition": "NEW",
    "tags": ["smartphone", "apple", "premium", "5g", "titanium"],
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "TechStore Pro",
    "shopSlug": "techstore-pro",
    "shopLogoUrl": "https://example.com/logos/techstore-pro.png",
    "categoryId": "789e0123-e89b-12d3-a456-426614174002",
    "categoryName": "Smartphones",
    "isDigital": false,
    "requiresShipping": true,
    "specifications": {
      "Display": "6.7-inch Super Retina XDR OLED",
      "Storage": "512GB",
      "Chip": "A17 Pro with 6-core GPU",
      "Battery Life": "Up to 29 hours video playback"
    },
    "hasSpecifications": true,
    "colors": [
      {
        "name": "Natural Titanium",
        "hex": "#F5F5DC",
        "images": ["https://example.com/colors/natural-titanium.jpg"],
        "priceAdjustment": 0.00,
        "finalPrice": 1199.00
      },
      {
        "name": "Black Titanium",
        "hex": "#1C1C1E",
        "images": ["https://example.com/colors/black-titanium.jpg"],
        "priceAdjustment": 50.00,
        "finalPrice": 1249.00
      }
    ],
    "hasMultipleColors": true,
    "priceRange": {
      "minPrice": 1199.00,
      "maxPrice": 1249.00,
      "hasPriceVariations": true
    },
    "groupBuying": {
      "isAvailable": true,
      "minGroupSize": 10,
      "maxGroupSize": 50,
      "groupPrice": 1099.00,
      "groupDiscount": 100.00,
      "groupDiscountPercentage": 8.34,
      "timeLimitHours": 72
    },
    "installmentOptions": {
      "isAvailable": true,
      "downPaymentRequired": true,
      "minDownPaymentPercentage": 20.00,
      "plans": [
        {
          "duration": 6,
          "interval": "MONTHS",
          "interestRate": 0.00,
          "description": "6 months interest-free installment"
        },
        {
          "duration": 12,
          "interval": "MONTHS",
          "interestRate": 2.90,
          "description": "12 months with low interest rate"
        }
      ]
    },
    "createdAt": "2025-09-23T10:30:00Z"
  }
}

Public Response Features:

Only shows active products from approved shops
Hides internal management data (SKU, creation user IDs, etc.)
Shows stock quantity only if product is in stock
Includes customer-focused information (shipping, features, pricing)
Full specifications and color variations for customer decision making

Error Responses:

404 Not Found: Shop not found, not approved, or product not found/not active

10. Get Public Shop Products

Purpose: Retrieves all active products from a shop for public browsing

Endpoint: GET /api/v1/shops/{shopId}/products/public-view/all

Access Level: 🌐 Public (No authentication required)

Authentication: None

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	ID of the shop	Valid UUID format, shop must be active and approved

Response JSON Sample:

{
  "success": true,
  "message": "Retrieved 23 products from TechStore Pro",
  "data": {
    "shop": {
      "shopId": "123e4567-e89b-12d3-a456-426614174000",
      "shopName": "TechStore Pro",
      "shopSlug": "techstore-pro",
      "logoUrl": "https://example.com/logos/techstore-pro.png",
      "isVerified": true,
      "isApproved": true,
      "isMyShop": false
    },
    "products": [
      {
        "productId": "456e7890-e89b-12d3-a456-426614174001",
        "productName": "iPhone 15 Pro Max 512GB",
        "productSlug": "iphone-15-pro-max-512gb",
        "shortDescription": "Premium 6.7-inch iPhone with A17 Pro chip",
        "primaryImage": "https://example.com/images/iphone15-pro-max-main.jpg",
        "price": 1199.00,
        "comparePrice": 1299.00,
        "finalPrice": 1199.00,
        "isOnSale": true,
        "discountPercentage": 7.69,
        "isInStock": true,
        "brand": "Apple",
        "condition": "NEW",
        "hasGroupBuying": true,
        "hasInstallments": true,
        "hasMultipleColors": true,
        "groupPrice": 1099.00,
        "startingFromPrice": 1199.00,
        "createdAt": "2025-09-23T10:30:00Z"
      }
    ],
    "totalProducts": 23
  }
}

Public Shop Information:

Only shows active products (ACTIVE status)
Shop verification and approval status displayed
No internal management statistics
Customer-focused product information
Simplified product cards optimized for browsing

Error Responses:

404 Not Found: Shop not found, not approved, or not active

11. Get Public Shop Products Paginated

Purpose: Retrieves active products from a shop with pagination for public browsing

Endpoint: GET /api/v1/shops/{shopId}/products/public-view/all-paged

Access Level: 🌐 Public (No authentication required)

Authentication: None

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	ID of the shop	Valid UUID format, shop must be active and approved

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-indexed)	Min: 1	1
size	integer	No	Items per page	Min: 1, Max: 50	10

Response JSON Sample:

{
  "success": true,
  "message": "Retrieved 10 products from TechStore Pro (Page 1 of 3)",
  "data": {
    "contents": {
      "shop": {
        "shopId": "123e4567-e89b-12d3-a456-426614174000",
        "shopName": "TechStore Pro",
        "shopSlug": "techstore-pro",
        "logoUrl": "https://example.com/logos/techstore-pro.png",
        "isVerified": true,
        "isApproved": true,
        "isMyShop": false
      },
      "products": [
        {
          "productId": "456e7890-e89b-12d3-a456-426614174001",
          "productName": "iPhone 15 Pro Max 512GB",
          "price": 1199.00,
          "isOnSale": true,
          "isInStock": true,
          "hasGroupBuying": true,
          "hasInstallments": true,
          "createdAt": "2025-09-23T10:30:00Z"
        }
      ],
      "totalProducts": 10
    },
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 23,
    "totalPages": 3,
    "hasNext": true,
    "hasPrevious": false
  }
}

Public Pagination Limits:

Maximum page size limited to 50 items for performance
Only active products included in pagination count
Shop must be approved and active to show any products

Error Responses:

404 Not Found: Shop not found, not approved, or not active

12. Search Products

Purpose: Searches products within a shop using enhanced multi-word query matching across multiple fields

Endpoint: GET /api/v1/shops/{shopId}/products/search

Access Level: 🌐 Public (Enhanced features for authenticated users)

Authentication: Optional Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	No	Bearer token for authentication (enables additional features)

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	ID of the shop to search in	Valid UUID format, shop must be accessible

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
q	string	Yes	Search query	Min: 2, Max: 100 characters	None
status	ProductStatus[]	No	Product statuses to search	DRAFT, ACTIVE, INACTIVE, OUT_OF_STOCK, ARCHIVED	ACTIVE (public users)
page	integer	No	Page number (1-indexed)	Min: 1	1
size	integer	No	Items per page	Min: 1, Max: 50	10
sortBy	string	No	Sort field	relevance, createdAt, updatedAt, productName, price, stockQuantity, brand	relevance
sortDir	string	No	Sort direction	asc, desc	desc

Request URL Examples:

# Basic search for "iphone"
GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/search?q=iphone

# Multi-word search for "dell precision"
GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/search?q=dell%20precision&sortBy=price&sortDir=asc

# Search with status filter (requires authentication)
GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/search?q=smartphone&status=ACTIVE&status=DRAFT

# Search with pagination and sorting
GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/search?q=laptop&page=2&size=20&sortBy=price&sortDir=asc

# Partial word search
GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/search?q=macbook&sortBy=relevance

Search Features & Behavior:

Feature	Description	Example
Multi-word Search	Searches for products containing ALL words	"dell precision" finds products with both "dell" AND "precision"
Partial Matching	Matches partial words	"iph" matches "iPhone"
Cross-field Search	Searches across multiple product fields	Query matches productName, description, shortDescription, brand, tags, specifications
Case Insensitive	Search is case-insensitive	"APPLE" matches "apple" and "Apple"
Special Characters	Removes harmful characters	Automatically sanitized for security
Relevance Scoring	Orders by relevance when sortBy=relevance	Products with exact matches ranked higher

Response JSON Sample:

{
  "success": true,
  "message": "Found 12 products matching 'dell precision'",
  "data": {
    "contents": {
      "shop": {
        "shopId": "123e4567-e89b-12d3-a456-426614174000",
        "shopName": "TechStore Pro",
        "shopSlug": "techstore-pro",
        "logoUrl": "https://example.com/logos/techstore-pro.png",
        "isVerified": true,
        "isApproved": true,
        "isMyShop": false
      },
      "products": [
        {
          "productId": "789e0123-e89b-12d3-a456-426614174002",
          "productName": "Dell Precision 7770 Mobile Workstation",
          "productSlug": "dell-precision-7770-mobile-workstation",
          "shortDescription": "Professional mobile workstation with Intel Xeon processor",
          "primaryImage": "https://example.com/images/dell-precision-7770.jpg",
          "price": 2499.00,
          "comparePrice": 2799.00,
          "finalPrice": 2499.00,
          "isOnSale": true,
          "discountPercentage": 10.72,
          "stockQuantity": 8,
          "isInStock": true,
          "isLowStock": true,
          "brand": "Dell",
          "sku": "SHP87654321-LAP-DEL-PRE-0005",
          "condition": "NEW",
          "status": "ACTIVE",
          "isFeatured": true,
          "isDigital": false,
          "hasGroupBuying": false,
          "hasInstallments": true,
          "hasMultipleColors": false,
          "groupPrice": null,
          "startingFromPrice": 2499.00,
          "createdAt": "2025-09-22T15:20:00Z"
        },
        {
          "productId": "890e1234-e89b-12d3-a456-426614174003",
          "productName": "Dell Precision 5570 Laptop",
          "productSlug": "dell-precision-5570-laptop",
          "shortDescription": "Compact precision laptop for professionals",
          "primaryImage": "https://example.com/images/dell-precision-5570.jpg",
          "price": 1899.00,
          "comparePrice": null,
          "finalPrice": 1899.00,
          "isOnSale": false,
          "discountPercentage": 0.00,
          "stockQuantity": 15,
          "isInStock": true,
          "isLowStock": false,
          "brand": "Dell",
          "sku": "SHP87654321-LAP-DEL-PRE-0006",
          "condition": "NEW",
          "status": "ACTIVE",
          "isFeatured": false,
          "isDigital": false,
          "hasGroupBuying": true,
          "hasInstallments": true,
          "hasMultipleColors": true,
          "groupPrice": 1749.00,
          "startingFromPrice": 1899.00,
          "createdAt": "2025-09-21T09:45:00Z"
        }
      ],
      "totalProducts": 12,
      "searchMetadata": {
        "searchQuery": "dell precision",
        "searchedStatuses": ["ACTIVE"],
        "userType": "PUBLIC",
        "canSearchAllStatuses": false
      }
    },
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 12,
    "totalPages": 2,
    "hasNext": true,
    "hasPrevious": false
  }
}

Search Metadata Fields:

Field	Description
searchQuery	The original search query provided
searchedStatuses	Product statuses included in search
userType	User type: PUBLIC, AUTHENTICATED, SHOP_OWNER, ADMIN
canSearchAllStatuses	Whether user can search draft/inactive products

User Access Levels:

User Type	Searchable Statuses	Additional Features
Public User	ACTIVE only	Basic search functionality
Authenticated User	ACTIVE only	Same as public (unless shop owner/admin)
Shop Owner	All statuses	Can search drafts, inactive products, view management data
System Admin	All statuses	Can search all products across all statuses

Sort Options:

Sort Field	Description	Best Used For
relevance	Orders by search relevance	Default search results
createdAt	Orders by creation date	Finding newest/oldest products
updatedAt	Orders by last update	Finding recently modified products
productName	Alphabetical order	Browsing products alphabetically
price	Orders by price	Price comparison
stockQuantity	Orders by stock level	Inventory management
brand	Orders by brand name	Brand-based organization

Error Responses:

400 Bad Request: Search query too short (< 2 characters), too long (> 100 characters), or invalid parameters
404 Not Found: Shop not found or not accessible (for public users, shop must be active and approved)

13. Advanced Product Filter

Purpose: Filters products using multiple criteria with complex combinations and boolean logic

Endpoint: GET /api/v1/shops/{shopId}/products/advanced-filter

Access Level: 🌐 Public (Enhanced features for authenticated users)

Authentication: Optional Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	No	Bearer token for authentication (enables additional filters)

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	ID of the shop to filter in	Valid UUID format, shop must be accessible

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
minPrice	decimal	No	Minimum price filter	Min: 0, Max: 8 digits	None
maxPrice	decimal	No	Maximum price filter	Min: 0, Max: 8 digits, must be >= minPrice	None
brand	string[]	No	Brand names to filter (OR logic)	Multiple values allowed	None
condition	ProductCondition	No	Product condition filter	NEW, USED_LIKE_NEW, USED_GOOD, USED_FAIR, REFURBISHED, FOR_PARTS	None
categoryId	UUID	No	Category filter	Valid UUID, category must exist	None
tags	string[]	No	Tag filters (OR logic)	Multiple values allowed	None
inStock	boolean	No	Filter by stock availability	true (in stock), false (out of stock)	None
onSale	boolean	No	Filter by sale status	true (on sale), false (not on sale)	None
hasGroupBuying	boolean	No	Filter by group buying availability	true (has group buying), false (no group buying)	None
hasInstallments	boolean	No	Filter by installment availability	true (has installments), false (no installments)	None
hasMultipleColors	boolean	No	Filter by color variations	true (multiple colors), false (single/no colors)	None
isFeatured	boolean	No	Filter by featured status	true (featured), false (not featured)	None
status	ProductStatus[]	No	Product status filter (OR logic)	Multiple statuses allowed	ACTIVE (public users)
page	integer	No	Page number (1-indexed)	Min: 1	1
size	integer	No	Items per page	Min: 1, Max: 50	10
sortBy	string	No	Sort field	createdAt, updatedAt, productName, price, stockQuantity, brand	createdAt
sortDir	string	No	Sort direction	asc, desc	desc

Request URL Examples:

# Price range filter
GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/advanced-filter?minPrice=500&maxPrice=1500

# Multiple brand filter (Apple OR Samsung)
GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/advanced-filter?brand=Apple&brand=Samsung&inStock=true

# Feature combination filter
GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/advanced-filter?hasGroupBuying=true&hasInstallments=true&onSale=true

# Category and condition filter
GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/advanced-filter?categoryId=123e4567-e89b-12d3-a456-426614174000&condition=NEW&isFeatured=true

# Complex filter with sorting
GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/advanced-filter?minPrice=100&maxPrice=2000&brand=Apple&brand=Dell&hasInstallments=true&sortBy=price&sortDir=asc

# Tag-based filtering
GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/advanced-filter?tags=premium&tags=5g&inStock=true

# Status filtering (requires authentication)
GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/advanced-filter?status=ACTIVE&status=DRAFT&hasGroupBuying=true

Filter Logic & Combinations:

Filter Type	Logic	Example
Price Range	AND (both minPrice AND maxPrice)	Products between $500 AND $1500
Multiple Brands	OR (Apple OR Samsung OR Dell)	Products from any of the specified brands
Multiple Tags	OR (premium OR 5g OR wireless)	Products with any of the specified tags
Multiple Statuses	OR (ACTIVE OR DRAFT)	Products with any of the specified statuses
Feature Flags	AND (all must be true/false)	Products that have group buying AND installments
Combined Filters	AND (between different filter types)	Price range AND brand AND features

Response JSON Sample:

{
  "success": true,
  "message": "Found 18 products matching your filters",
  "data": {
    "contents": {
      "shop": {
        "shopId": "123e4567-e89b-12d3-a456-426614174000",
        "shopName": "TechStore Pro",
        "shopSlug": "techstore-pro",
        "logoUrl": "https://example.com/logos/techstore-pro.png",
        "isVerified": true,
        "isApproved": true,
        "isMyShop": false
      },
      "products": [
        {
          "productId": "456e7890-e89b-12d3-a456-426614174001",
          "productName": "iPhone 15 Pro Max 512GB",
          "productSlug": "iphone-15-pro-max-512gb",
          "shortDescription": "Premium 6.7-inch iPhone with A17 Pro chip",
          "primaryImage": "https://example.com/images/iphone15-pro-max.jpg",
          "price": 1199.00,
          "comparePrice": 1299.00,
          "finalPrice": 1199.00,
          "isOnSale": true,
          "discountPercentage": 7.69,
          "stockQuantity": 25,
          "isInStock": true,
          "isLowStock": false,
          "brand": "Apple",
          "sku": "SHP12345678-ELE-APP-512-0001",
          "condition": "NEW",
          "status": "ACTIVE",
          "isFeatured": true,
          "isDigital": false,
          "hasGroupBuying": true,
          "hasInstallments": true,
          "hasMultipleColors": true,
          "groupPrice": 1099.00,
          "startingFromPrice": 1199.00,
          "createdAt": "2025-09-23T10:30:00Z"
        },
        {
          "productId": "567e8901-e89b-12d3-a456-426614174002",
          "productName": "Samsung Galaxy S24 Ultra",
          "productSlug": "samsung-galaxy-s24-ultra",
          "shortDescription": "Premium Android flagship with S Pen",
          "primaryImage": "https://example.com/images/samsung-s24-ultra.jpg",
          "price": 1099.00,
          "comparePrice": 1199.00,
          "finalPrice": 1099.00,
          "isOnSale": true,
          "discountPercentage": 8.34,
          "stockQuantity": 12,
          "isInStock": true,
          "isLowStock": false,
          "brand": "Samsung",
          "sku": "SHP12345678-ELE-SAM-ULT-0007",
          "condition": "NEW",
          "status": "ACTIVE",
          "isFeatured": true,
          "isDigital": false,
          "hasGroupBuying": true,
          "hasInstallments": true,
          "hasMultipleColors": true,
          "groupPrice": 999.00,
          "startingFromPrice": 1099.00,
          "createdAt": "2025-09-22T14:15:00Z"
        }
      ],
      "totalProducts": 18,
      "filterMetadata": {
        "appliedFilters": {
          "minPrice": 800.00,
          "maxPrice": 1500.00,
          "brands": ["Apple", "Samsung"],
          "inStock": true,
          "onSale": true,
          "hasGroupBuying": true,
          "hasInstallments": true,
          "isFeatured": true
        },
        "userType": "PUBLIC",
        "searchedStatuses": ["ACTIVE"],
        "hasActiveFilters": true
      }
    },
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 18,
    "totalPages": 2,
    "hasNext": true,
    "hasPrevious": false
  }
}

Applied Filters Metadata: The appliedFilters object shows exactly which filters were applied:

Filter Category	Possible Values	Logic
Price Filters	minPrice, maxPrice	Range filtering (between values)
Brand Filters	brands array	OR logic (any of the brands)
Availability Filters	inStock, onSale	Boolean filtering
Feature Filters	hasGroupBuying, hasInstallments, hasMultipleColors, isFeatured	Boolean filtering
Category Filter	categoryId	Exact match
Condition Filter	condition	Exact match
Tag Filters	tags array	OR logic (any of the tags)
Status Filters	status array	OR logic (any of the statuses)

Filter Validation Rules:

Filter	Validation	Error Behavior
minPrice/maxPrice	Must be positive numbers, maxPrice >= minPrice	400 Bad Request
brand	Must be non-empty strings	Ignored if empty
categoryId	Must be valid UUID and existing category	404 Not Found
tags	Must be non-empty strings	Ignored if empty
condition	Must be valid ProductCondition enum	400 Bad Request
status	Must be valid ProductStatus enum values	400 Bad Request
Boolean filters	Must be true/false	400 Bad Request

Performance Considerations:

Filters use database indexing for optimal performance
Complex filter combinations are optimized with JPA Specifications
Page size limited to 50 items to prevent performance issues
Popular filter combinations are cached for better response times

User Permission Differences:

User Type	Available Status Filters	Additional Features
Public User	ACTIVE only	Basic filtering
Shop Owner/Admin	All statuses	Can filter draft, inactive, archived products
System Admin	All statuses	Full access to all filter combinations

Error Responses:

400 Bad Request: Invalid filter values, price range errors, or invalid parameters
404 Not Found: Shop not found, category not found, or shop not accessible
422 Unprocessable Entity: Filter combination validation errors

Common Filter Use Cases:

Price Shopping: minPrice=500&maxPrice=1000&sortBy=price&sortDir=asc
Brand Comparison: brand=Apple&brand=Samsung&hasInstallments=true
Feature Shopping: hasGroupBuying=true&hasInstallments=true&onSale=true
Category Browsing: categoryId=UUID&inStock=true&sortBy=price
Premium Products: isFeatured=true&hasMultipleColors=true&minPrice=500
Sale Items: onSale=true&inStock=true&sortBy=discountPercentage&sortDir=desc

14. Get Public Product by Slug

Purpose: Retrieves a single active product for public viewing with customer-focused information by slug

Endpoint: GET /api/v1/shops/{shopId}/products/find-by-slug/{slug}

Access Level: 🌐 Public (No authentication required)

Authentication: None

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	ID of the shop	Valid UUID format, shop must be active and approved
slug	String	Yes	Slug of the product	N/A

Response JSON Sample:

{
  "success": true,
  "message": "Product retrieved successfully",
  "data": {
    "productId": "456e7890-e89b-12d3-a456-426614174001",
    "productName": "iPhone 15 Pro Max 512GB",
    "productSlug": "iphone-15-pro-max-512gb",
    "productDescription": "The most advanced iPhone ever, featuring the groundbreaking A17 Pro chip...",
    "shortDescription": "Premium 6.7-inch iPhone with A17 Pro chip and titanium design",
    "productImages": [
      "https://example.com/images/iphone15-pro-max-main.jpg",
      "https://example.com/images/iphone15-pro-max-side.jpg"
    ],
    "price": 1199.00,
    "comparePrice": 1299.00,
    "discountAmount": 100.00,
    "discountPercentage": 7.69,
    "isOnSale": true,
    "isInStock": true,
    "isLowStock": false,
    "stockQuantity": 25,
    "brand": "Apple",
    "condition": "NEW",
    "tags": ["smartphone", "apple", "premium", "5g", "titanium"],
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "TechStore Pro",
    "shopSlug": "techstore-pro",
    "shopLogoUrl": "https://example.com/logos/techstore-pro.png",
    "categoryId": "789e0123-e89b-12d3-a456-426614174002",
    "categoryName": "Smartphones",
    "isDigital": false,
    "requiresShipping": true,
    "specifications": {
      "Display": "6.7-inch Super Retina XDR OLED",
      "Storage": "512GB",
      "Chip": "A17 Pro with 6-core GPU",
      "Battery Life": "Up to 29 hours video playback"
    },
    "hasSpecifications": true,
    "colors": [
      {
        "name": "Natural Titanium",
        "hex": "#F5F5DC",
        "images": ["https://example.com/colors/natural-titanium.jpg"],
        "priceAdjustment": 0.00,
        "finalPrice": 1199.00
      },
      {
        "name": "Black Titanium",
        "hex": "#1C1C1E",
        "images": ["https://example.com/colors/black-titanium.jpg"],
        "priceAdjustment": 50.00,
        "finalPrice": 1249.00
      }
    ],
    "hasMultipleColors": true,
    "priceRange": {
      "minPrice": 1199.00,
      "maxPrice": 1249.00,
      "hasPriceVariations": true
    },
    "groupBuying": {
      "isAvailable": true,
      "minGroupSize": 10,
      "maxGroupSize": 50,
      "groupPrice": 1099.00,
      "groupDiscount": 100.00,
      "groupDiscountPercentage": 8.34,
      "timeLimitHours": 72
    },
    "installmentOptions": {
      "isAvailable": true,
      "downPaymentRequired": true,
      "minDownPaymentPercentage": 20.00,
      "plans": [
        {
          "duration": 6,
          "interval": "MONTHS",
          "interestRate": 0.00,
          "description": "6 months interest-free installment"
        },
        {
          "duration": 12,
          "interval": "MONTHS",
          "interestRate": 2.90,
          "description": "12 months with low interest rate"
        }
      ]
    },
    "createdAt": "2025-09-23T10:30:00Z"
  }
}

Public Response Features:

Only shows active products from approved shops
Hides internal management data (SKU, creation user IDs, etc.)
Shows stock quantity only if product is in stock
Includes customer-focused information (shipping, features, pricing)
Full specifications and color variations for customer decision making

Error Responses:

404 Not Found: Shop not found, not approved, or product not found/not active

Quick Reference Guide

Common HTTP Status Codes

200 OK: Successful GET/PUT/PATCH request with response data
201 Created: Successful POST request, resource created
204 No Content: Successful DELETE request (hard delete)
400 Bad Request: Invalid request data, validation errors, or business rule violations
401 Unauthorized: Authentication required, invalid token, or expired token
403 Forbidden: Insufficient permissions (shop owner or system admin required)
404 Not Found: Resource not found, shop not accessible, or product not available
409 Conflict: Duplicate product name/SKU, or business constraint violation
422 Unprocessable Entity: Validation errors with detailed field-level messages
429 Too Many Requests: Rate limit exceeded (search/filter endpoints)
500 Internal Server Error: Server error during processing

Authentication Types

Bearer Token: Include Authorization: Bearer your_token in headers
None: No authentication required for public product viewing
Optional: Enhanced features available with authentication

User Access Levels & Permissions

User Type	Product Management	Search/Filter	Status Access	Special Features
Public User	View active products only	Basic search/filter	ACTIVE only	No management data
Authenticated User	View active products only	Basic search/filter	ACTIVE only	Same as public unless shop owner
Shop Owner	Full CRUD on own shop	Enhanced search/filter	All statuses	Management statistics, draft products
System Admin	Full CRUD on all shops	Enhanced search/filter	All statuses	Cross-shop access, system statistics

Data Format Standards

Dates: Use ISO 8601 format (2025-09-23T14:30:00Z)
Prices: Use decimal with 2 decimal places (999.00), stored as BigDecimal
UUIDs: Use standard UUID format (123e4567-e89b-12d3-a456-426614174000)
Pagination: 1-indexed pages (page parameter starts from 1)
URLs: Must be valid HTTP/HTTPS URLs for product images and color images
Colors: Hex format (#1D1D1F) for color codes, case insensitive
Percentages: Decimal format (20.00 for 20%), max 2 decimal places
Currency: Use shop's base currency, no currency symbols in API

Product Status Lifecycle

DRAFT → ACTIVE → INACTIVE → ARCHIVED
  ↑       ↓         ↓         ↑
  └── RESTORE ──────┴─────────┘

OUT_OF_STOCK ←→ ACTIVE (automatic based on inventory)

Status	Description	Public Visibility	Management Actions
DRAFT	Product being created/edited	Hidden	Edit, Publish, Hard Delete
ACTIVE	Live and available for purchase	Visible	Edit, Deactivate, Soft Delete
INACTIVE	Temporarily unavailable	Hidden	Edit, Activate, Soft Delete
OUT_OF_STOCK	No inventory available	Visible with "Out of Stock"	Restock (auto-activates)
ARCHIVED	No longer sold, kept for history	Hidden	Restore, View only

Product Conditions

Condition	Description	Typical Use Case
NEW	Brand new, unused product	New retail items
USED_LIKE_NEW	Minimal use, perfect condition	Returns, demo units
USED_GOOD	Good condition with minor wear	Refurbished items
USED_FAIR	Fair condition with noticeable wear	Budget/economy items
REFURBISHED	Professionally restored to working order	Certified refurbished
FOR_PARTS	Sold for parts or repair only	Non-functional items

ReqAction Values & Effects

Action	Effect on Status	Use Case
SAVE_DRAFT	Sets status to DRAFT	Save work in progress
SAVE_PUBLISH	Sets status to ACTIVE	Immediate publication

Advanced Features Overview

Group Buying System

Group Formation → Time Limit → Minimum Check → Price Activation
     ↓               ↓            ↓               ↓
  Users Join → Countdown Timer → Min Size Met → Discount Applied

Requirements:

groupMinSize: Minimum participants (min: 2)
groupMaxSize: Maximum participants (must be >= groupMinSize)
groupPrice: Discounted price (must be < regular price)
groupTimeLimitHours: Formation time limit (1-8760 hours)
groupRequiresMinimum: Whether minimum size is mandatory

Business Rules:

Group price must be less than regular price
Time limit starts when first user joins
If minimum not reached and required, group fails
Successful groups lock in the discount for all participants

Installment Payment System

Product Price → Down Payment → Remaining Amount → Monthly Payments
      ↓             ↓              ↓                    ↓
   $1000.00    →  $200.00    →   $800.00         →  $133.33 x 6

Payment Intervals:

DAYS: Daily payments (short-term financing)
WEEKS: Weekly payments (flexible scheduling)
MONTHS: Monthly payments (standard installments)

Calculation Formula:

Down Payment = Product Price × (Min Down Payment % ÷ 100)
Remaining Amount = Product Price - Down Payment
Interest Amount = Remaining Amount × (Interest Rate ÷ 100)
Total Installment Amount = Remaining Amount + Interest Amount
Payment Per Interval = Total Installment Amount ÷ Duration

Color Variations System

Price Calculation:

Base Price + Color Price Adjustment = Final Color Price
$999.00 + $50.00 = $1049.00 (Premium Color)
$999.00 + $0.00 = $999.00 (Standard Color)

Price Range Calculation:

minPrice: Lowest price across all color variations
maxPrice: Highest price across all color variations
startingFromPrice: Same as minPrice for customer display

Validation Rules Summary

Product Creation/Update Validation

Field	Validation Rules	Error Handling
productName	Min: 2, Max: 100 chars, unique in shop	400 Bad Request with field error
productDescription	Min: 10, Max: 1000 chars	422 Unprocessable Entity
price	Min: 0.01, Max: 8 digits, 2 decimal places	400 Bad Request
stockQuantity	Min: 0	400 Bad Request
comparePrice	Must be > price if provided	Custom validation error
groupPrice	Must be < price if group buying enabled	Custom validation error
categoryId	Must exist and be active	404 Not Found
productImages	At least 1 valid URL required	422 Unprocessable Entity
colors[].hex	Valid 6-digit hex format (#RRGGBB)	400 Bad Request
installmentPlans	Required if installmentEnabled=true	Custom validation error

Business Logic Validation

Group Size Logic: groupMaxSize >= groupMinSize
Price Logic: comparePrice > price AND groupPrice < price
Order Quantity Logic: maxOrderQuantity >= minOrderQuantity
Installment Logic: At least one plan required when enabled
Publishing Requirements: Name, description, price, stock, category, images required

SKU Generation System

Format: SHP[8-CHAR-UUID]-[CATEGORY-3]-[BRAND-3]-[ATTRIBUTE-3]-[SEQUENCE-4]

Components:

Shop Prefix: SHP + first 8 characters of shop UUID (uppercase)
Category Code: First 3 characters of category name (uppercase, alphanumeric only)
Brand Code: First 3 characters of brand name (uppercase, alphanumeric only)
Attribute Code: Main product attribute from specifications or name (3 chars)
Sequence Number: 4-digit sequential number within shop (0001, 0002, etc.)

Examples:

SHP12345678-ELE-APP-256-0001 (Apple iPhone with 256GB storage)
SHP87654321-LAP-DEL-PRE-0005 (Dell Precision laptop)
SHP11223344-CLO-NIK-XLA-0012 (Nike XL clothing)

Search & Filter Capabilities

Search Query Processing

Query Type	Processing	Example	Result
Single Word	`%word%` pattern	"iphone"	Matches "iPhone 15 Pro"
Multi-word	`%word1%word2%` pattern	"dell precision"	Matches products with both "dell" AND "precision"
Partial Match	Automatic partial matching	"macb"	Matches "MacBook"
Cross-field	Searches multiple fields	"apple"	Matches brand, name, description, tags

Filter Combinations Logic

AND Logic (between different filter types):
Price Range AND Brand Filter AND Feature Filters

OR Logic (within same filter type):
Brand: Apple OR Samsung OR Dell
Tags: premium OR 5g OR wireless
Status: ACTIVE OR DRAFT OR INACTIVE

Performance Optimizations:

Database indexes on: shop_id, status, price, brand, category_id
JPA Specifications for dynamic query building
Page size limits (max 50 for public, max 100 for management)
Query result caching for popular filter combinations

Error Handling Guidelines

Error Response Format

{
  "success": false,
  "message": "Human-readable error message",
  "error": {
    "code": "ERROR_CODE",
    "details": "Detailed error information",
    "field": "fieldName (if field-specific)",
    "timestamp": "2025-09-23T14:30:00Z"
  }
}

Common Error Scenarios

Scenario	HTTP Code	Response Strategy
Invalid Product Name	400	Field-specific validation message
Product Not Found	404	Generic "Product not found" (security)
Insufficient Permissions	403	"Insufficient permissions" without details
Duplicate Product	409	"Product with similar details already exists"
Publishing Validation	400	List all missing required fields
Rate Limiting	429	Include retry-after header

Best Practices for API Usage

Product Management Best Practices

Always validate required fields before creating products
Use SAVE_DRAFT action during product creation process
Use SAVE_PUBLISH action only when product is complete
Set appropriate low stock thresholds for inventory alerts
Enable group buying for bulk products to increase sales volume
Set up installments for high-value items (>$500) to improve accessibility
Add comprehensive specifications for better search discoverability
Use high-quality images (minimum 800x600 pixels recommended)
Implement proper inventory tracking to prevent overselling
Regular price updates to maintain competitiveness

Search & Filter Optimization

Use pagination for better performance and user experience
Implement client-side caching for popular search queries
Provide search suggestions based on common queries
Use filter combinations intelligently to reduce result sets
Sort by relevance for search results, by price for filters
Implement infinite scroll for mobile applications
Show filter result counts before applying filters
Provide clear filter reset functionality
Use debouncing for real-time search input
Cache filter metadata for faster subsequent requests

Security Best Practices

Always validate user permissions before product operations
Sanitize search queries to prevent injection attacks
Rate limit search endpoints to prevent abuse
Validate all file uploads (images) before processing
Use HTTPS for all API requests containing sensitive data
Implement proper session management for authenticated users
Log all product management actions for audit trails
Validate price inputs to prevent negative or invalid values
Check shop ownership before allowing product modifications
Implement request throttling for high-frequency operations

Performance Optimization

Use appropriate page sizes (10-20 for mobile, 50+ for desktop)
Implement database indexing on frequently queried fields
Cache expensive calculations (group buying status, installment calculations)
Use CDN for product images to improve load times
Implement lazy loading for non-critical product details
Optimize database queries using JPA Specifications efficiently
Use compression for large response payloads
Implement response caching for public product listings
Monitor API response times and optimize slow endpoints
Use connection pooling for database connections

Business Logic Guidelines

Maintain price consistency across all product variations
Validate group buying economics (ensure profitability)
Set realistic installment terms based on product value
Implement inventory alerts at appropriate thresholds
Use soft delete for published products to maintain order history
Hard delete only draft products to keep database clean
Validate category assignments for proper product organization
Implement price change logging for audit purposes
Set appropriate product conditions based on actual state
Maintain SEO-friendly slugs for better discoverability

API Integration Examples

Creating a Complete Product (Recommended Flow)

1. POST /shops/{shopId}/products (action=SAVE_DRAFT)
   - Create basic product structure
   - Validate required fields
   
2. PUT /shops/{shopId}/products/{productId} (action=SAVE_DRAFT)
   - Add advanced features (group buying, installments)
   - Upload and set product images
   - Add specifications and color variations
   
3. PATCH /shops/{shopId}/products/{productId}/publish
   - Final validation check
   - Publish to make publicly available

Search Implementation Pattern

1. Basic Search: GET /shops/{shopId}/products/search?q=query
2. Add Filters: GET /shops/{shopId}/products/advanced-filter?brand=X&minPrice=Y
3. Combine Both: Use search for text matching, filters for refinement
4. Pagination: Always include page and size parameters
5. Sort Results: Use appropriate sortBy based on user intent

Error Recovery Strategies

400 Errors: Validate input client-side, show field-specific errors
401 Errors: Refresh authentication token, redirect to login
403 Errors: Show access denied message, don't retry automatically  
404 Errors: Handle gracefully, suggest alternatives
409 Errors: Show conflict resolution options to user
429 Errors: Implement exponential backoff retry strategy
500 Errors: Log error details, show generic error message to user

Shop Categories Management

Shop Management

Shop Rating

Shop Review

Product Management

Cart Management

Wishlist Management

Wallet

Transaction History

Installment Purchase - Customer Endpoints

Installment Purchase - Public & Plan Endpoints

Installment Plan Management - Admin/Shop Endpoints

Product Management

Endpoints

1. Create Product

2. Update Product

3. Publish Product

4. Delete Product

5. Restore Product

6. Get Product Detailed (Owner/Admin View)

7. Get Shop Products (Management View)

8. Get Shop Products Paginated (Management View)

9. Get Public Product by ID

10. Get Public Shop Products

11. Get Public Shop Products Paginated

12. Search Products

13. Advanced Product Filter

14. Get Public Product by Slug

Quick Reference Guide

Common HTTP Status Codes

Authentication Types

User Access Levels & Permissions

Data Format Standards

Product Status Lifecycle

Product Conditions

ReqAction Values & Effects

Advanced Features Overview

Group Buying System

Installment Payment System

Color Variations System

Validation Rules Summary

Product Creation/Update Validation

Business Logic Validation

SKU Generation System

Search & Filter Capabilities

Search Query Processing

Filter Combinations Logic

Error Handling Guidelines

Error Response Format

Common Error Scenarios

Best Practices for API Usage

Product Management Best Practices

Search & Filter Optimization

Security Best Practices

Performance Optimization

Business Logic Guidelines

API Integration Examples

Creating a Complete Product (Recommended Flow)

Search Implementation Pattern

Error Recovery Strategies