Product Management

Product Management API Documentation

Author: ~~Josh~~NextGate S.Development ~~Sakweli~~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 ~~like~~including group buying, installment payments, color variations, specifications, ~~search,~~comprehensive ~~filtering,~~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 ~~support~~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~~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"Pro Max 256GB",
  "productDescription": "LatestThe most advanced iPhone withever, advancedfeaturing the groundbreaking A17 Pro chip, titanium design, and the most versatile Pro camera systemsystem. and titanium design. FeaturesWith a 6.1-7-inch Super Retina XDR displaydisplay, withAction ProMotion technology, A17 Pro chip,Button, and professionalup camerato system.29 hours of video playback battery life.",
  "shortDescription": "Premium smartphone6.7-inch iPhone with A17 Pro camerachip features"and titanium design",
  "price": 999.1199.00,
  "comparePrice": 1099.1299.00,
  "stockQuantity": 50,25,
  "lowStockThreshold": 10,5,
  "categoryId": "123e4567-e89b-12d3-a456-426614174000",
  "brand": "Apple",
  "condition": "NEW",
  "productImages": [
    "https://example.com/images/iphone15-pro-1.max-main.jpg",
    "https://example.com/images/iphone15-pro-2.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": {
    "Screen Size"Display": "6.17-inch inches"Super Retina XDR OLED",
    "Chip": "A17 Pro with 6-core GPU",
    "Storage": "256GB",
    "RAM": "8GB",
    "Rear Camera": "48MP TripleMain, Camera"12MP Ultra Wide, 12MP Telephoto",
    "Battery"Front Camera": "327412MP mAh"TrueDepth",
    "OS"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": "SpaceNatural Black"Titanium",
      "hex": "#1D1D1F"#F5F5DC",
      "images": [
        "https://example.com/images/colors/iphone-black.natural-titanium-1.jpg",
        "https://example.com/colors/iphone-natural-titanium-2.jpg"
      ],
      "priceAdjustment": 0.00
    },
    {
      "name": "DeepBlue Purple"Titanium",
      "hex": "#5856D6"#4A90E2",
      "images": [
        "https://example.com/images/colors/iphone-purple.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": 5,3,
  "maxPerCustomer": 2,
  "requiresApproval": false,
  "groupBuyingEnabled": true,
  "groupMinSize": 10,
  "groupMaxSize": 50,
  "groupPrice": 899.1099.00,
  "groupTimeLimitHours": 48,72,
  "groupRequiresMinimum": true,
  "installmentEnabled": true,
  "installmentPlans": [
    {
      "duration": 6,
      "interval": "MONTHS",
      "interestRate": 0.00,
      "description": "6 months interest-free"free installment"
    },
    {
      "duration": 12,
      "interval": "MONTHS",
      "interestRate": 5.2.90,
      "description": "12 months with low interest"interest rate"
    },
    {
      "duration": 24,
      "interval": "MONTHS",
      "interestRate": 5.90,
      "description": "24 months extended payment plan"
    }
  ],
  "downPaymentRequired": true,
  "minDownPaymentPercentage": 20.00,
  "trackInventory": true,
  "isFeatured": false,true,
  "isDigital": false,
  "requiresShipping": true,
  "metaTitle": "iPhone 15 Pro Max 256GB - Premium Smartphone"Titanium Smartphone | TechStore Pro",
  "metaDescription": "GetBuy the latest iPhone 15 Pro Max with advanced256GB featuresstorage, A17 Pro chip, and premiumtitanium design"design. Available with group buying discounts and flexible installment plans."
}

Request Body Parameters:

~~enabled~~

Parameter	Type	Required	Description	Validation
productName	string	Yes	~~Name~~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,~~digits with 2 decimal places
stockQuantity	integer	Yes	Available stock quantity	Min: 0
categoryId	UUID	Yes	Product category IDidentifier	Must exist and be active
shortDescription	string	No	Brief product ~~description~~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~~empty, at least 1 required
tags	array	No	Product tags for categorization	Max 50 characters ~~each~~per tag
specifications	object	No	~~Product~~Technical product specifications	~~Key-value pairs,~~Key: max 100 ~~char~~chars, ~~keys,~~Value: max 500 ~~char values~~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 ~~size~~participants	Min: 2, required if ~~group buying enabled~~groupBuyingEnabled=true
groupMaxSize	integer	No	Maximum group ~~size~~participants	Min: 2, must be >= groupMinSize
groupPrice	decimal	No	~~Group~~Discounted ~~buying~~group price	Must be <less than regular price
groupTimeLimitHours	integer	No	Group formation time limit ~~in hours~~	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 ~~installment~~payment plans	Required if ~~installments~~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~~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 ~~flag~~(no shipping)	Default: false
requiresShipping	boolean	No	~~Requires~~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~~data, validation errors, or ~~validation~~business ~~errors~~rule violations
401 Unauthorized: Authentication required or invalid token
403 Forbidden: Insufficient permissions (shop ~~owner/~~owner or system admin required)
404 Not Found: Shop not found or category not ~~found~~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~~format, shop must exist
productId	UUID	Yes	ID of the product to update	Valid UUID ~~format~~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"Max 512GB - Updated",
  "price": 1199.1399.00,
  "comparePrice": 1499.00,
  "stockQuantity": 30,15,
  "groupPrice": 1099.1299.00,
  "specifications": {
    "Display": "6.7-inch Super Retina XDR OLED",
    "Storage": "512GB",
    "RAM": "8GB",
    "New Feature": "Enhanced Night Mode"
  },
  "installmentPlans": [
    {
      "duration": 24,6,
      "interval": "MONTHS",
      "interestRate": 3.0.00,
      "description": "6 months interest-free"
    },
    {
      "duration": 18,
      "interval": "MONTHS",
      "interestRate": 4.50,
      "description": "2418 months lowflexible interest plan"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"Max 512GB - Updated",
    "productSlug": "iphone-15-pro-max-512gb-updated",
    "price": 1199.1399.00,
    "comparePrice": 1499.00,
    "status": "ACTIVE",
    "stockQuantity": 15,
    "updatedAt": "2025-09-23T11:45:00"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 ~~request~~update data or validation errors
401 Unauthorized: Authentication required
403 Forbidden: Insufficient permissions
404 Not Found: Shop or product not found
409 Conflict: ~~Product~~Updated product name or SKU already exists
422 Unprocessable Entity: Validation errors

3. GetPublish Product Detailed

Purpose: ~~Retrieves~~Publishes ~~comprehensive~~a draft product ~~details~~making ~~with~~it ~~all~~active ~~features~~and publicly available

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

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~~format, shop must exist
productId	UUID	Yes	ID of the product to publish	Valid UUID ~~format~~format, product must exist and be draft

Response JSON Sample:

{
  "success": true,
  "message": "Product details'iPhone retrieved15 Pro Max 512GB' published successfully",
  "data": {
    "productId": "456e7890-e89b-12d3-a456-426614174001",
    "productName": "iPhone 15 Pro"Pro Max 512GB",
    "productSlug": "iphone-15-pro",
    "productDescription": "Latest iPhone with advanced camera system",
    "shortDescription": "Premium smartphone with Pro camera features",
    "productImages": ["https://example.com/images/iphone15-pro-1.jpg"],
    "price": 999.00,
    "comparePrice": 1099.00,
    "discountAmount": 100.00,
    "discountPercentage": 9.09,
    "isOnSale": true,
    "stockQuantity": 50,
    "isInStock": true,
    "isLowStock": false,
    "brand": "Apple",
    "sku": "SHP12345678-ELE-APP-256-0001",
    "condition": "NEW"max-512gb",
    "status": "ACTIVE",
    "tags"publishedAt": ["smartphone", "apple", "premium"]2025-09-23T14:45:00Z",
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "TechStore Pro",
    "categoryId": "789e0123-e89b-12d3-a456-426614174002",
    "categoryName": "Smartphones",
    "specifications": {
      "Screen Size": "6.1 inches",
      "Storage": "256GB",
      "RAM": "8GB"
    },
    "hasSpecifications": true,
    "specificationCount": 3,
    "colors": [
      {
        "name": "Space Black",
        "hex": "#1D1D1F",
        "images": ["https://example.com/images/iphone-black.jpg"],
        "priceAdjustment": 0.00,
        "finalPrice": 999.00,
        "hasExtraFee": false
      }
    ],
    "hasMultipleColors": false,
    "colorCount": 1,
    "priceRange": {
      "minPrice": 999.00,
      "maxPrice": 999.00,
      "hasPriceVariations": false
    },
    "groupBuying": {
      "isEnabled": true,
      "isAvailable": true,
      "minGroupSize": 10,
      "maxGroupSize": 50,
      "currentGroupSize": 7,
      "remainingSlots": 43,
      "groupPrice": 899.00,
      "groupDiscount": 100.00,
      "groupDiscountPercentage": 10.01,
      "timeLimitHours": 48,
      "timeRemainingHours": 24,
      "status": "PENDING",
      "canJoinGroup": true
    },
    "installmentOptions": {
      "isEnabled": true,
      "isAvailable": true,
      "downPaymentRequired": true,
      "minDownPaymentPercentage": 20.00,
      "plans": [
        {
          "planId": "plan-6m",
          "duration": 6,
          "interval": "MONTHS",
          "interestRate": 0.00,
          "description": "6 months interest-free",
          "calculations": {
            "downPayment": 199.80,
            "remainingAmount": 799.20,
            "paymentAmount": 133.20,
            "totalAmount": 999.00
          },
          "isPopular": true
        }
      ]
    },
    "purchaseOptions": {
      "canBuyNow": true,
      "canJoinGroup": true,
      "canPayInstallment": true,
      "recommendedOption": "GROUP_BUYING",
      "bestDeal": {
        "option": "GROUP_BUYING",
        "savings": 100.00,
        "finalPrice": 899.00
      }
    },
    "createdAt": "2025-09-23T10:30:00",
    "updatedAt": "2025-09-23T11:45:00"
  }
}

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. GetDelete Shop Products (Owner View)Product

Purpose: ~~Retrieves~~Deletes ~~all~~a ~~products~~product ~~for~~using ~~shop~~different ~~management~~strategies based on product status

Endpoint: ~~GET~~DELETE /api/v1/shops/{shopId}/products/all{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~~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": "RetrievedProduct 25'iPhone products15 fromPro shop:Max TechStore512GB' Pro"has been deleted and will be permanently removed after 30 days",
  "data": {
    "shop": {
      "shopId"message": "123e4567-e89b-12d3-a456-426614174000"Product 'iPhone 15 Pro Max 512GB' has been deleted and will be permanently removed after 30 days",
    "shopName"productName": "TechStoreiPhone Pro"15 Pro Max 512GB",
      "shopSlug": "techstore-pro",
      "logoUrl": "https://example.com/logos/techstore.png",
      "isVerified": true,
      "isApproved": true
    },
    "summary": {
      "totalProducts": 25,
      "activeProducts": 20,
      "draftProducts": 3,
      "outOfStockProducts": 2,
      "featuredProducts": 5,
      "lowStockProducts": 4,
      "averagePrice": 599.50,
      "totalInventoryValue": 14987.50,
      "productsWithGroupBuying": 8,
      "productsWithInstallments": 12,
      "productsWithMultipleColors": 6
    },
    "products": [
      {
    "productId": "456e7890-e89b-12d3-a456-426614174001",
    "productName": "iPhone 15 Pro",
        "productSlug": "iphone-15-pro",
        "primaryImage": "https://example.com/images/iphone15-pro-1.jpg",
        "price": 999.00,
        "comparePrice": 1099.00,
        "finalPrice": 999.00,
        "isOnSale": true,
        "discountPercentage": 9.09,
        "stockQuantity": 50,
        "isInStock": true,
        "isLowStock": false,
        "brand": "Apple",
        "sku": "SHP12345678-ELE-APP-256-0001",
        "status"previousStatus": "ACTIVE",
    "isFeatured": false,
        "hasGroupBuying": true,
        "hasInstallments": true,
        "hasMultipleColors": true,
        "groupPrice": 899.00,
        "startingFromPrice": 999.00,
        "createdAt"deletedAt": "2025-09-23T10:30:00"
      }
    ]23T15:00:00Z",
    "totalProducts"deletionType": 25"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. GetRestore Shop Products (Paginated)Product

Purpose: ~~Retrieves~~Restores ~~shop~~a ~~products~~soft-deleted ~~with~~product ~~pagination~~back ~~for~~to ~~management~~draft status

Endpoint: ~~GET~~PATCH /api/v1/shops/{shopId}/products/all-paged{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~~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: 11, 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",
          "summary"productName": {"iPhone 15 Pro Max 512GB",
          "price": 1199.00,
          "isOnSale": true,
          "isInStock": true,
          "hasGroupBuying": true,
          "hasInstallments": true,
          "createdAt": "2025-09-23T10:30:00Z"
        }
      ],
      "totalProducts": 25,
        "activeProducts": 20
      }10
    },
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 25,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~~found, not approved, or not ~~available~~active

12. Search Products

Purpose: Searches products within a shop ~~with~~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~~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, ~~productName~~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&page=1&size=10

# 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 812 products matching 'iphone'dell precision'",
  "data": {
    "contents": {
      "shop": {
        "shopId": "123e4567-e89b-12d3-a456-426614174000",
        "shopName": "TechStore Pro",
        "shopSlug": "techstore-pro",
        "logoUrl": "https://example.com/logos/techstore.techstore-pro.png",
        "isVerified": truetrue,
        "isApproved": true,
        "isMyShop": false
      },
      "products": [
        {
          "productId": "456e7890-789e0123-e89b-12d3-a456-426614174001"426614174002",
          "productName": "iPhoneDell 15Precision Pro"7770 Mobile Workstation",
          "productSlug": "iphone-15-pro"dell-precision-7770-mobile-workstation",
          "shortDescription": "Professional mobile workstation with Intel Xeon processor",
          "primaryImage": "https://example.com/images/iphone15-pro-1.dell-precision-7770.jpg",
          "price": 999.2499.00,
          "comparePrice": 1099.2799.00,
          "finalPrice": 2499.00,
          "isOnSale": true,
          "discountPercentage": 9.09,10.72,
          "stockQuantity": 8,
          "isInStock": true,
          "isLowStock": true,
          "brand": "Apple"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-23T10:30:00"21T09:45:00Z"
        }
      ],
      "totalProducts": 8,12,
      "searchMetadata": {
        "searchQuery": "iphone"dell precision",
        "searchedStatuses": ["ACTIVE"],
        "userType": "PUBLIC",
        "canSearchAllStatuses": false
      }
    },
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 8,12,
    "totalPages": 1,2,
    "hasNext": false,true,
    "hasPrevious": false
  }
}

Search ~~Features~~Metadata Fields:

~~Multi-word~~

~~queries~~

~~"dell~~

~~precision"~~

~~searches~~

~~for~~

~~products~~

~~containing~~

~~both~~

~~"dell"~~

~~name,~~

~~description,~~

~~brand,~~

~~and~~

Field	Description
searchQuery	The ~~and "precision"~~ ~~Partial matching~~~~: "iph" will match "iPhone"~~ ~~Cross-field~~original search: ~~Searches~~query provided
searchedStatuses	Product statuses included in ~~product~~search
userType	User ~~tags~~type: ~~Status~~PUBLIC, ~~filtering~~:AUTHENTICATED, ~~Shop~~SHOP_OWNER, ~~owners/admins~~ADMIN
canSearchAllStatuses	Whether user can search ~~draft~~draft/inactive products

~~Relevance~~User ~~sorting~~Access Levels:

~~Products~~

~~matching~~

~~query~~

~~terms~~

~~ranked~~

User ~~are~~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: ~~Invalid search~~Search query (too ~~short/long)~~short (< 2 characters), too long (> 100 characters), or invalid parameters
404 Not Found: Shop not found or not ~~available~~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~~format, shop must be accessible

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
minPrice	decimal	No	Minimum price filter	Min: 00, Max: 8 digits	None
maxPrice	decimal	No	Maximum price filter	Min: 00, 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, ~~etc.~~USED_GOOD, USED_FAIR, REFURBISHED, FOR_PARTS	None
categoryId	UUID	No	Category filter	Valid ~~UUID~~UUID, category must exist	None
tags	string[]	No	Tag filters (OR logic)	Multiple values allowed	None
inStock	boolean	No	Filter by stock availability	~~true/~~true (in stock), false (out of stock)	None
onSale	boolean	No	Filter by sale status	~~true/~~true (on sale), false (not on sale)	None
hasGroupBuying	boolean	No	Filter by group buying availability	~~true/~~true (has group buying), false (no group buying)	None
hasInstallments	boolean	No	Filter by installment availability	~~true/~~true (has installments), false (no installments)	None
hasMultipleColors	boolean	No	Filter by color variations	~~true/~~true (multiple colors), false (single/no colors)	None
isFeatured	boolean	No	Filter by featured status	~~true/~~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, ~~productName,~~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&brand=

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

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

# Category and condition filter
GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/advanced-filter?categoryId=123e4567-e89b-12d3-a456-426614174000&hasInstallments=truecondition=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 1218 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.techstore-pro.png",
        "isVerified": truetrue,
        "isApproved": true,
        "isMyShop": false
      },
      "products": [
        {
          "productId": "456e7890-e89b-12d3-a456-426614174001",
          "productName": "iPhone 15 Pro"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": 999.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,
          "isFeatured"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": 12,18,
      "filterMetadata": {
        "appliedFilters": {
          "minPrice": 500.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": 12,18,
    "totalPages": 2,
    "hasNext": true,
    "hasPrevious": false
  }
}

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

Filter ~~Combinations~~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:

~~Price~~Filters ~~Range~~:use minPrice=100&maxPrice=500database ~~filters~~indexing ~~products~~for ~~between~~optimal ~~$100-$500~~performance
~~Multiple~~Complex ~~Brands~~:filter brand=Apple&brand=Samsungcombinations ~~shows~~are ~~products~~optimized ~~from~~with ~~Apple~~JPA ~~OR Samsung~~Specifications
~~Feature~~Page ~~Combinations~~:size hasGroupBuying=true&hasInstallments=truelimited ~~shows~~to ~~products~~50 ~~with~~items ~~both~~to ~~features~~prevent performance issues
~~Stock + Sale~~: inStock=true&onSale=true ~~shows available products on sale~~

~~Category + Condition~~~~: Combine category~~Popular filter ~~with~~combinations ~~product~~are ~~condition~~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~~found, category not found, or shop not ~~available~~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

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/failed~~required, invalid token, or expired token
403 Forbidden: Insufficient permissions (shop ~~owner/~~owner or system admin required)
404 Not Found: Resource not ~~found~~found, shop not accessible, or product not available
409 Conflict: Duplicate product name/~~SKU~~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 ~~URL~~HTTP/HTTPS ~~format~~URLs for product images and color images
Colors: Hex format (#1D1D1F) for color ~~codes~~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)

~~(not~~

~~public)~~

~~Product is live~~

~~Product temporarily~~

~~Product~~

~~Product no~~

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 isinventory ~~out~~available	Visible with "Out of ~~stock~~Stock"	Restock (auto-activates)
ARCHIVED:	No longer ~~sold but~~sold, kept for history	Hidden	Restore, View only

Product Conditions

Condition	Description	Typical Use Case
NEW:	Brand ~~new~~new, unused product	New retail items
USED_LIKE_NEW:	Minimal use, ~~like new~~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/~~parts or repair only	Non-functional items

ReqAction Values & Effects

~~(status:~~

~~DRAFT)~~

~~Save~~

~~shop~~

Action	Effect on Status	Use Case
SAVE_DRAFT:	Sets status to DRAFT	Save ~~product~~work asin ~~draft~~progress
SAVE_PUBLISH:	Sets ~~and publish product (status: ACTIVE)~~ ~~Role-Based Access Control~~ ~~Public Users~~~~: Can view active products, search, and filter~~ ~~Shop Owners~~~~: Full CRUD operations on their shop products~~ ~~System Admins~~~~: Full access~~status to ~~all~~ACTIVE	Immediate ~~products~~publication

Action

Effect on Status

Use Case

SAVE_DRAFT:

Sets status to DRAFT

Save ~~product~~work asin ~~draft~~progress

SAVE_PUBLISH:

Sets ~~and publish product (status: ACTIVE)~~

Role-Based Access Control

~~Public Users~~~~: Can view active products, search, and filter~~

~~Shop Owners~~~~: Full CRUD operations on their shop products~~

~~System Admins~~~~: Full access~~status to ~~all~~ACTIVE

Immediate ~~products~~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:

~~Allows~~groupMinSize: ~~customers~~Minimum toparticipants (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 ~~together~~fails

Successful groups lock in the discount for ~~bulk~~all ~~pricing~~

~~Requires minimum and maximum group size~~

~~Time-limited offers with countdown~~

~~Automatic price reduction when group requirements met~~participants

Installment Payment System

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

Payment Intervals:

~~Multiple~~DAYS: ~~payment~~Daily ~~plan options~~payments (3,short-term ~~6, 12, 24 months)~~financing)
~~Configurable~~WEEKS: ~~interest~~Weekly ~~rates~~payments (flexible scheduling)
~~Down~~MONTHS: ~~payment~~Monthly ~~support~~payments ~~with~~(standard ~~percentage requirements~~

~~Payment schedule generation~~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:

~~Multiple~~minPrice: Lowest price across all color ~~options per product~~variations
~~Price~~maxPrice: ~~adjustments~~Highest ~~per~~price across all color variations
~~Separate~~startingFromPrice: ~~image~~Same ~~sets~~as minPrice for ~~each~~customer ~~color~~

~~Price range calculations (starting from $X)~~

Product Specifications

~~Key-value specification pairs~~

~~Used for product comparisons~~

~~Searchable attributes~~

~~Technical product details~~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

~~Product~~Group ~~Name~~Size Logic: ~~2-100~~groupMaxSize characters,>= unique within shop

Description: 10-1000 characters requiredgroupMinSize
Price Logic: ~~Minimum~~comparePrice $0.01,> maximumprice 8AND ~~digits~~groupPrice with< 2 decimalsprice
~~Stock~~Order Quantity Logic: ~~Non-negative~~maxOrderQuantity integer>= minOrderQuantity
~~Group~~Installment ~~Buying~~~~: Group max size >= min size, group price < regular price~~

~~Installments~~Logic: At least one plan required when enabled
~~Colors~~Publishing Requirements: ~~Valid hex color codes, optional price adjustments~~

~~Images~~~~: Valid URLs, at least one image required~~

Search & Filter Features

~~Multi-word Search~~~~: "dell precision" matches products with both terms~~

~~Cross-field Search~~~~: Searches name,~~Name, description, ~~brand, tags, specifications~~

~~Price Range Filtering~~~~: Min/max price boundaries~~

~~Multi-brand Filtering~~~~: OR logic for multiple brand selections~~

~~Feature Filtering~~~~: Group buying, installments, multiple colors~~

~~Availability Filtering~~~~: In~~price, stock, oncategory, ~~sale,~~images ~~featured products~~

~~Status Filtering~~~~: Available to shop owners/admins only~~required

SKU Generation FormatSystem

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

~~Example:~~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:

~~SHP12345678:~~Database ~~Shop~~indexes ~~prefix~~on: ~~with~~shop_id, ~~8-char~~status, ~~UUID~~price, brand, category_id
~~ELE:~~JPA ~~Electronics~~Specifications ~~category~~for dynamic query building
~~APP:~~Page ~~Apple~~size ~~brand~~limits (max 50 for public, max 100 for management)
~~256:~~Query ~~256GB~~result ~~storage~~caching ~~attribute~~

for

~~0001:~~popular ~~Sequential~~filter ~~number~~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/updating~~creating products
Use ~~appropriate~~SAVE_DRAFT action during product ~~status~~creation process

Use SAVE_PUBLISH action ~~based~~only onwhen ~~readiness~~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 ~~results~~discoverability
Use high-quality ~~product~~ images ~~for~~(minimum ~~better~~800x600 ~~conversion~~pixels recommended)
Implement proper inventory tracking to ~~avoid~~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 ~~low~~product ~~stock~~conditions ~~thresholds~~based on actual state

Maintain SEO-friendly slugs for ~~reorder~~better ~~alerts~~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