Product Management

Author: Josh S. Sakweli
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 group buying, installment payments, color variations, specifications, search, filtering, and role-based access control.

Hints:

• All shop-related endpoints require the shopId path parameter
• Shop owners and system admins can manage products; public users can only view active products
• Products support advanced features: group buying, installments, color variations, and specifications
• Action parameter (SAVE_DRAFT/SAVE_PUBLISH) determines product status on create/update
• Search supports multi-word queries with enhanced pattern matching
• Pagination is 1-indexed (page starts from 1)
• Products are soft-deleted (marked as deleted rather than permanently removed)
• Product slugs are unique within each shop scope
• SKUs are auto-generated and unique across the system

---

Endpoints

1. Create Product

Purpose: Creates a new product in a shop with advanced features support

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

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",
  "productDescription": "Latest iPhone with advanced camera system and titanium design. Features a 6.1-inch Super Retina XDR display with ProMotion technology, A17 Pro chip, and professional camera system.",
  "shortDescription": "Premium smartphone with Pro camera features",
  "price": 999.00,
  "comparePrice": 1099.00,
  "stockQuantity": 50,
  "lowStockThreshold": 10,
  "categoryId": "123e4567-e89b-12d3-a456-426614174000",
  "brand": "Apple",
  "condition": "NEW",
  "productImages": [
    "https://example.com/images/iphone15-pro-1.jpg",
    "https://example.com/images/iphone15-pro-2.jpg"
  ],
  "tags": ["smartphone", "apple", "premium", "5g"],
  "specifications": {
    "Screen Size": "6.1 inches",
    "Storage": "256GB",
    "RAM": "8GB",
    "Camera": "48MP Triple Camera",
    "Battery": "3274 mAh",
    "OS": "iOS 17"
  },
  "colors": [
    {
      "name": "Space Black",
      "hex": "#1D1D1F",
      "images": ["https://example.com/images/iphone-black.jpg"],
      "priceAdjustment": 0.00
    },
    {
      "name": "Deep Purple",
      "hex": "#5856D6",
      "images": ["https://example.com/images/iphone-purple.jpg"],
      "priceAdjustment": 50.00
    }
  ],
  "minOrderQuantity": 1,
  "maxOrderQuantity": 5,
  "groupBuyingEnabled": true,
  "groupMinSize": 10,
  "groupMaxSize": 50,
  "groupPrice": 899.00,
  "groupTimeLimitHours": 48,
  "installmentEnabled": true,
  "installmentPlans": [
    {
      "duration": 6,
      "interval": "MONTHS",
      "interestRate": 0.00,
      "description": "6 months interest-free"
    },
    {
      "duration": 12,
      "interval": "MONTHS",
      "interestRate": 5.90,
      "description": "12 months with low interest"
    }
  ],
  "downPaymentRequired": true,
  "minDownPaymentPercentage": 20.00,
  "trackInventory": true,
  "isFeatured": false,
  "isDigital": false,
  "requiresShipping": true,
  "metaTitle": "iPhone 15 Pro - Premium Smartphone",
  "metaDescription": "Get the latest iPhone 15 Pro with advanced features and premium design"
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
productName	string	Yes	Name of the product	Min: 2, Max: 100 characters
productDescription	string	Yes	Detailed product description	Min: 10, Max: 1000 characters
price	decimal	Yes	Product price	Min: 0.01, Max: 8 digits, 2 decimal places
stockQuantity	integer	Yes	Available stock quantity	Min: 0
categoryId	UUID	Yes	Product category ID	Must exist and be active
shortDescription	string	No	Brief product description	Max: 200 characters
comparePrice	decimal	No	Original price for discount display	Must be greater than price
brand	string	No	Product brand	Max: 100 characters
condition	ProductCondition	No	Product condition	NEW, USED_LIKE_NEW, USED_GOOD, USED_FAIR, REFURBISHED, FOR_PARTS
productImages	array	Yes	Product image URLs	Valid URLs, cannot be empty
tags	array	No	Product tags	Max 50 characters each
specifications	object	No	Product specifications	Key-value pairs, max 100 char keys, 500 char values
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	Min: 1
groupBuyingEnabled	boolean	No	Enable group buying	Default: false
groupMinSize	integer	No	Minimum group size	Min: 2, required if group buying enabled
groupMaxSize	integer	No	Maximum group size	Min: 2, must be >= groupMinSize
groupPrice	decimal	No	Group buying price	Must be < regular price
groupTimeLimitHours	integer	No	Group time limit in hours	Min: 1, Max: 8760
installmentEnabled	boolean	No	Enable installment payments	Default: false
installmentPlans	array	No	Available installment plans	Required if installments enabled
downPaymentRequired	boolean	No	Require down payment	Default: false
minDownPaymentPercentage	decimal	No	Minimum down payment %	Min: 0, Max: 100
isFeatured	boolean	No	Mark as featured product	Default: false
isDigital	boolean	No	Digital product flag	Default: false
requiresShipping	boolean	No	Requires shipping	Default: true
metaTitle	string	No	SEO meta title	Max: 100 characters
metaDescription	string	No	SEO meta description	Max: 200 characters

Response JSON Sample:

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

Error Responses:

• 400 Bad Request: Invalid request data or validation errors
• 401 Unauthorized: Authentication required
• 403 Forbidden: Insufficient permissions (shop owner/admin required)
• 404 Not Found: Shop or category not found
• 409 Conflict: Product with same name, brand, price, and specifications exists

---

2. Update Product

Purpose: Updates an existing product with advanced features

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
productId	UUID	Yes	ID of the product to update	Valid UUID format

Query Parameters:

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

Request JSON Sample:

{
  "productName": "iPhone 15 Pro Max",
  "price": 1199.00,
  "stockQuantity": 30,
  "groupPrice": 1099.00,
  "installmentPlans": [
    {
      "duration": 24,
      "interval": "MONTHS",
      "interestRate": 3.50,
      "description": "24 months low interest plan"
    }
  ]
}

Response JSON Sample:

{
  "success": true,
  "message": "Product updated successfully and published",
  "data": {
    "productId": "456e7890-e89b-12d3-a456-426614174001",
    "productName": "iPhone 15 Pro Max",
    "price": 1199.00,
    "status": "ACTIVE",
    "updatedAt": "2025-09-23T11:45:00"
  }
}

Error Responses:

• 400 Bad Request: Invalid request data or validation errors
• 401 Unauthorized: Authentication required
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Shop or product not found
• 409 Conflict: Product name or SKU already exists

---

3. Get Product Detailed

Purpose: Retrieves comprehensive product details with all features

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

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

Authentication: Bearer Token

Path Parameters:

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

Response JSON Sample:

{
  "success": true,
  "message": "Product details retrieved successfully",
  "data": {
    "productId": "456e7890-e89b-12d3-a456-426614174001",
    "productName": "iPhone 15 Pro",
    "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",
    "status": "ACTIVE",
    "tags": ["smartphone", "apple", "premium"],
    "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"
  }
}

Error Responses:

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

---

4. Get Shop Products (Owner View)

Purpose: Retrieves all products for shop management

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

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

Authentication: Bearer Token

Path Parameters:

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

Response JSON Sample:

{
  "success": true,
  "message": "Retrieved 25 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.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": "ACTIVE",
        "isFeatured": false,
        "hasGroupBuying": true,
        "hasInstallments": true,
        "hasMultipleColors": true,
        "groupPrice": 899.00,
        "startingFromPrice": 999.00,
        "createdAt": "2025-09-23T10:30:00"
      }
    ],
    "totalProducts": 25
  }
}

Error Responses:

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

---

5. Get Shop Products (Paginated)

Purpose: Retrieves shop products with pagination for management

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

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

Authentication: Bearer Token

Path Parameters:

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

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	10

Response JSON Sample:

{
  "success": true,
  "message": "Retrieved 10 products from shop: TechStore Pro (Page 1 of 3)",
  "data": {
    "contents": {
      "shop": {
        "shopId": "123e4567-e89b-12d3-a456-426614174000",
        "shopName": "TechStore Pro"
      },
      "products": [],
      "summary": {
        "totalProducts": 25,
        "activeProducts": 20
      }
    },
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 25,
    "totalPages": 3,
    "hasNext": true,
    "hasPrevious": false
  }
}

Error Responses:

• 404 Not Found: Shop not found or not available

---

12. Search Products

Purpose: Searches products within a shop with enhanced query matching

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

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

Authentication: Optional Bearer Token

Path Parameters:

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

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, price, productName	relevance
sortDir	string	No	Sort direction	asc, desc	desc

Request URL Examples:

GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/search?q=iphone&page=1&size=10
GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/search?q=dell%20precision&sortBy=price&sortDir=asc
GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/search?q=smartphone&status=ACTIVE&status=DRAFT

Response JSON Sample:

{
  "success": true,
  "message": "Found 8 products matching 'iphone'",
  "data": {
    "contents": {
      "shop": {
        "shopId": "123e4567-e89b-12d3-a456-426614174000",
        "shopName": "TechStore Pro",
        "logoUrl": "https://example.com/logos/techstore.png",
        "isVerified": true
      },
      "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,
          "isOnSale": true,
          "discountPercentage": 9.09,
          "isInStock": true,
          "brand": "Apple",
          "status": "ACTIVE",
          "hasGroupBuying": true,
          "hasInstallments": true,
          "createdAt": "2025-09-23T10:30:00"
        }
      ],
      "totalProducts": 8,
      "searchMetadata": {
        "searchQuery": "iphone",
        "searchedStatuses": ["ACTIVE"],
        "userType": "PUBLIC",
        "canSearchAllStatuses": false
      }
    },
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 8,
    "totalPages": 1,
    "hasNext": false,
    "hasPrevious": false
  }
}

Search Features:

• Multi-word queries: "dell precision" searches for products containing both "dell" and "precision"
• Partial matching: "iph" will match "iPhone"
• Cross-field search: Searches in product name, description, brand, and tags
• Status filtering: Shop owners/admins can search draft products
• Relevance sorting: Products matching query terms are ranked by relevance

Error Responses:

• 400 Bad Request: Invalid search query (too short/long)
• 404 Not Found: Shop not found or not available

---

13. Advanced Product Filter

Purpose: Filters products using multiple criteria with complex combinations

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

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

Authentication: Optional Bearer Token

Path Parameters:

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

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
minPrice	decimal	No	Minimum price filter	Min: 0	None
maxPrice	decimal	No	Maximum price filter	Min: 0	None
brand	string[]	No	Brand names to filter	Multiple values allowed	None
condition	ProductCondition	No	Product condition	NEW, USED_LIKE_NEW, etc.	None
categoryId	UUID	No	Category filter	Valid UUID	None
tags	string[]	No	Tag filters	Multiple values allowed	None
inStock	boolean	No	Filter by stock availability	true/false	None
onSale	boolean	No	Filter by sale status	true/false	None
hasGroupBuying	boolean	No	Filter by group buying availability	true/false	None
hasInstallments	boolean	No	Filter by installment availability	true/false	None
hasMultipleColors	boolean	No	Filter by color variations	true/false	None
isFeatured	boolean	No	Filter by featured status	true/false	None
status	ProductStatus[]	No	Product status filter	Multiple statuses	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, price, productName, brand	createdAt
sortDir	string	No	Sort direction	asc, desc	desc

Request URL Examples:

GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/advanced-filter?minPrice=500&maxPrice=1500&brand=Apple&brand=Samsung&inStock=true

GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/advanced-filter?onSale=true&hasGroupBuying=true&sortBy=price&sortDir=asc

GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/advanced-filter?categoryId=123e4567-e89b-12d3-a456-426614174000&hasInstallments=true&isFeatured=true

Response JSON Sample:

{
  "success": true,
  "message": "Found 12 products matching your filters",
  "data": {
    "contents": {
      "shop": {
        "shopId": "123e4567-e89b-12d3-a456-426614174000",
        "shopName": "TechStore Pro",
        "logoUrl": "https://example.com/logos/techstore.png",
        "isVerified": true
      },
      "products": [
        {
          "productId": "456e7890-e89b-12d3-a456-426614174001",
          "productName": "iPhone 15 Pro",
          "price": 999.00,
          "isOnSale": true,
          "isInStock": true,
          "brand": "Apple",
          "condition": "NEW",
          "hasGroupBuying": true,
          "hasInstallments": true,
          "hasMultipleColors": true,
          "isFeatured": false,
          "status": "ACTIVE"
        }
      ],
      "totalProducts": 12,
      "filterMetadata": {
        "appliedFilters": {
          "minPrice": 500.00,
          "maxPrice": 1500.00,
          "brands": ["Apple", "Samsung"],
          "inStock": true,
          "hasGroupBuying": true
        },
        "userType": "PUBLIC",
        "hasActiveFilters": true
      }
    },
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 12,
    "totalPages": 2,
    "hasNext": true,
    "hasPrevious": false
  }
}

Filter Combinations:

• Price Range: minPrice=100&maxPrice=500 filters products between $100-$500
• Multiple Brands: brand=Apple&brand=Samsung shows products from Apple OR Samsung
• Feature Combinations: hasGroupBuying=true&hasInstallments=true shows products with both features
• Stock + Sale: inStock=true&onSale=true shows available products on sale
• Category + Condition: Combine category filter with product condition

Error Responses:

• 404 Not Found: Shop not found or not available

---

Quick Reference Guide

Common HTTP Status Codes

• 200 OK: Successful GET/PUT/PATCH request
• 201 Created: Successful POST request
• 400 Bad Request: Invalid request data, validation errors, or business rule violations
• 401 Unauthorized: Authentication required/failed
• 403 Forbidden: Insufficient permissions (shop owner/admin required)
• 404 Not Found: Resource not found or not available
• 409 Conflict: Duplicate product name/SKU or business constraint violation
• 500 Internal Server Error: Server error

Authentication Types

• Bearer Token: Include Authorization: Bearer your_token in headers
• None: No authentication required for public product viewing

Data Format Standards

• Dates: Use ISO 8601 format (2025-09-23T14:30:00Z)
• Prices: Use decimal with 2 decimal places (999.00)
• UUIDs: Use standard UUID format (123e4567-e89b-12d3-a456-426614174000)
• Pagination: 1-indexed pages (page starts from 1)
• URLs: Must be valid URL format for product images
• Colors: Hex format (#1D1D1F) for color codes

Product Status Lifecycle

• DRAFT: Product being created/edited (not public)
• ACTIVE: Product is live and available for purchase
• INACTIVE: Product temporarily unavailable
• OUT_OF_STOCK: Product is out of stock
• ARCHIVED: Product no longer sold but kept for history

Product Conditions

• NEW: Brand new product
• USED_LIKE_NEW: Minimal use, like new condition
• USED_GOOD: Good condition with minor wear
• USED_FAIR: Fair condition with noticeable wear
• REFURBISHED: Professionally restored
• FOR_PARTS: Sold for parts/repair only

ReqAction Values

• SAVE_DRAFT: Save product as draft (status: DRAFT)
• SAVE_PUBLISH: Save 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 to all shop products

Advanced Features

Group Buying

• Allows customers to group together for bulk pricing
• Requires minimum and maximum group size
• Time-limited offers with countdown
• Automatic price reduction when group requirements met

Installment Payments

• Multiple payment plan options (3, 6, 12, 24 months)
• Configurable interest rates
• Down payment support with percentage requirements
• Payment schedule generation

Color Variations

• Multiple color options per product
• Price adjustments per color
• Separate image sets for each color
• Price range calculations (starting from $X)

Product Specifications

• Key-value specification pairs
• Used for product comparisons
• Searchable attributes
• Technical product details

Validation Rules

• Product Name: 2-100 characters, unique within shop
• Description: 10-1000 characters required
• Price: Minimum $0.01, maximum 8 digits with 2 decimals
• Stock: Non-negative integer
• Group Buying: Group max size >= min size, group price < regular price
• Installments: At least one plan required when enabled
• Colors: 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, 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 stock, on sale, featured products
• Status Filtering: Available to shop owners/admins only

SKU Generation Format

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

Example: SHP12345678-ELE-APP-256-0001

• SHP12345678: Shop prefix with 8-char UUID
• ELE: Electronics category
• APP: Apple brand
• 256: 256GB storage attribute
• 0001: Sequential number

Best Practices

1. Always validate required fields before creating/updating products
2. Use appropriate product status based on readiness
3. Enable group buying for bulk products to increase sales
4. Set up installments for high-value items to improve accessibility
5. Add comprehensive specifications for better search results
6. Use high-quality product images for better conversion
7. Implement proper inventory tracking to avoid overselling
8. Set appropriate low stock thresholds for reorder alerts