Product Management

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: 2025-09-232026-05-19
Version: v1.v2.0

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

Hints:

• All shop-related endpoints requireuse the shopIdprefix path parameterapi/v1/e-commerce/shops/{shopId}/products
• Shop owners and system admins have full product management access
• Public users can only view active products from approved, active shops
• Products supporthave advanceda features:productType: groupPHYSICAL buying,(shipping installments,+ colordelivery variations,confirmation) andor specificationsDIGITAL (instant download after payment)
• Action parameter (SAVE_DRAFT/SAVE_PUBLISH)SAVE_DRAFT/SAVE_PUBLISH) determines product status on create/update operations
• Search supports multi-word queries with enhanced pattern matching across multiple fields
• Pagination is 1-indexed (page parameter starts from 1)
• Products use soft-delete (marked as deleted rather than permanently removed, except drafts)
• Product slugs are unique within each shop scope
• SKUs are auto-generated using shop, category, brand, and sequence information
• Group buying requires minimuma participantsmaximum participant count, a group price, and hasa time limitslimit
• Installment plans supportare multiplemanaged paymentseparately intervalsvia withthe configurableInstallment interestPlan ratesConfig endpoints
• Color variations can have individual price adjustments and separate image sets
• Digital products require uploading files via the Digital File Management endpoints before buyers can download

---

Endpoints

1. Create Product

Purpose: Creates a new product in a shopshop, with support for all advanced features includingsupporting group buying, installments, color variations, specifications, and specificationsdigital product rules.

Endpoint: POST /api/v1/e-commerce/shops/{shopId}/products

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

Authentication: Bearer Token

Request Headers:

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

Path Parameters:

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

Query Parameters:

Parameter	Type	Required	DescriptionDefault	Validation	DefaultDescription
action	ReqAction	Yes	Action to perform on product—	SAVE_DRAFT,SAVE_DRAFT or SAVE_PUBLISH	None

Request JSON Sample:

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

Request Body Parameters:

per(DIGITAL cap(DIGITAL

Parameter	Type	Required	Description	Validation
productType	ProductType	Yes	PHYSICAL or DIGITAL	Required
productName	string	Yes	Unique name of the product within shop	Min: 2, Max: 100 characterschars
productDescription	string	Yes	Detailed product description	Min: 10, Max: 1000 characterschars
price	decimal	Yes	Product sellingSelling price	Min: 0.01, Max:max 8 digits with+ 2 decimal places
stockQuantity	integer	Yes	Available stock quantity	Min: 0
categoryId	UUID	Yes	Product category identifier	Must exist and be active
shortDescription	string	No	Brief product summary	Max: 200 characters
comparePrice	decimal	No	Original price for discount display	Must be greater than> price if provided
lowStockThreshold	integer	No	Low stock alert threshold	Min: 1, Max: 1000, Default: 5
brand	string	No	Product brand name	Max: 100 characters
sku	string	No	Custom Stock Keeping Unit	Max: 50 characters, auto-generated if not provided
condition	ProductCondition	No	Product condition	NEW,NEW, USED_LIKE_NEW,USED_LIKE_NEW, USED_GOOD,USED_GOOD, USED_FAIR,USED_FAIR, REFURBISHED,REFURBISHED, FOR_PARTS
status	ProductStatus	No	Initial productstatus status(overridden by action)	DRAFT,Default: ACTIVE, INACTIVE, OUT_OF_STOCK, ARCHIVEDACTIVE
productImages	array	Yes	Product image URLs	Valid URLs, cannot be empty, at least 1 required
tags	array	No	Product tags for categorization	Max 50 characters per tag
specifications	object	No	TechnicalKey-value product specificationsspecs	Key:Key max 100 chars, Value:Value max 500 chars
colors	array	No	Available colorColor variations	See Color objectsobject with name, hex, images, priceAdjustmentbelow
minOrderQuantity	integer	No	Minimum order quantityqty	Min: 1, Default: 1
maxOrderQuantity	integer	No	Maximum order quantityqty per order	Min: 1, must be >=≥ minOrderQuantity
maxPerCustomer	integer	No	Maximum quantity per customer	Min: 1
requiresApproval	boolean	No	Requires manual approval for orders	Default: false
groupBuyingEnabled	boolean	No	Enable group buying feature	Default: false
groupMinSize	integer	No	Minimum group participants	Min: 2, required if groupBuyingEnabled=true
groupMaxSize	integer	No	Maximum group participants	Min: 2, mustrequired beif >= groupMinSizegroupBuyingEnabled
groupPrice	decimal	No	Discounted group price	Must be less than regular< price
groupTimeLimitHours	integer	No	Group formation time limit	Min: 1, Max: 8760 (1 year)
groupRequiresMinimumdownloadExpiryDays	booleaninteger	No	GroupDownload mustlink reachexpiry minimum(DIGITAL sizeonly)	Min: 1, Default: true7
installmentEnabledmaxDownloadsPerBuyer	booleaninteger	No	EnableDownload installmentattempts payments	Default:buyer false
installmentPlans	array	No	Available payment plans	Required if installmentEnabled=true
installmentPlans[].duration	integer	Yes	Payment plan durationonly)	Min: 1
installmentPlans[].intervalmaxQuantityForDigital	string	Yes	Payment interval	DAYS, WEEKS, MONTHS
installmentPlans[].interestRate	decimal	Yes	Interest rate percentage	Min: 0, Max: 100, 2 decimal places
installmentPlans[].description	stringinteger	No	PlanPurchase description	Max:per 200buyer characters
downPaymentRequired	boolean	No	Require down payment	Default: false
minDownPaymentPercentage	decimal	No	Minimum down payment percentageonly)	Min: 0, Max: 100, 2 decimal places
trackInventory	boolean	No	Track inventory changes	Default: true
isFeatured	boolean	No	Mark as featured product	Default: false
isDigital	boolean	No	Digital product (no shipping)	Default: false
requiresShipping	boolean	No	Physical shipping required	Default: true
metaTitle	string	No	SEO meta title	Max: 100 characters
metaDescription	string	No	SEO meta description	Max: 200 characters1

Color Object:

Field	Type	Required	Validation
name	string	Yes	Max: 50 chars
hex	string	Yes	Valid #RRGGBB format
images	array	No	Valid URLs
priceAdjustment	decimal	No	Min: 0.0, Default: 0

Request ObjectJSON StructureSample (PHYSICAL):

{
  "productType": "PHYSICAL",
  "productName": "iPhone 15 Pro Max 256GB",
  "productDescription": "The most advanced iPhone featuring the A17 Pro chip and titanium design.",
  "price": 1199.00,
  "comparePrice": 1299.00,
  "stockQuantity": 25,
  "lowStockThreshold": 5,
  "categoryId": "123e4567-e89b-12d3-a456-426614174000",
  "condition": "NEW",
  "productImages": [
    "https://example.com/images/iphone15-main.jpg"
  ],
  "specifications": {
    "Display": "6.7-inch Super Retina XDR OLED",
    "Chip": "A17 Pro"
  },
  "colors": [
    {
      "name": "ColorNatural Name"Titanium",
      "hex": "#HEXCODE"#F5F5DC",
      "images": ["url1", "url2"https://example.com/colors/natural-titanium.jpg"],
      "priceAdjustment": 0.00
    }
  ],
  "minOrderQuantity": 1,
  "maxOrderQuantity": 3,
  "groupBuyingEnabled": true,
  "groupMaxSize": 50,
  "groupPrice": 1099.00,
  "groupTimeLimitHours": 72
}

Installment Plan Request ObjectJSON StructureSample (DIGITAL):

{
  "duration": 12,
  "interval"productType": "MONTHS"DIGITAL",
  "interestRate": 2.90,
  "description"productName": "12UI monthsDesign lowKit interest"Pro",
  "productDescription": "A comprehensive Figma component library with 500+ components.",
  "price": 49.00,
  "stockQuantity": 1000,
  "categoryId": "123e4567-e89b-12d3-a456-426614174000",
  "productImages": ["https://example.com/images/design-kit-preview.jpg"],
  "downloadExpiryDays": 30,
  "maxDownloadsPerBuyer": 5,
  "maxQuantityForDigital": 1
}

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 pricegroupPrice must be less than regular price
• InstallmentAll plansgroup buying settings (groupMaxSize, groupPrice, groupTimeLimitHours) required when installmentEnabled=groupBuyingEnabled=true
• At least one installment planmaxOrderQuantity must be provided≥ minOrderQuantity
• ColorDigital hexdownload codesfields must(downloadExpiryDays, bemaxDownloadsPerBuyer, validmaxQuantityForDigital) 6-digitonly hexapply formatto DIGITAL products
• AllAfter imagecreation, URLsadd mustinstallment beplans validvia Installment Plan Config and accessible
digital
• Categoryfiles mustvia existDigital andFile 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 enabledManagement

Error Responses:

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

---

2. Update Product

Purpose: Updates an existing productproduct. withOnly supportprovided forfields allare advanced features and partial updatesupdated.

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

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

Authentication: Bearer Token

Request Headers:

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

Path Parameters:

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

Query Parameters:

Parameter	Type	Required	DescriptionDefault	Validation	DefaultDescription
action	ReqAction	Yes	Action to perform after update—	SAVE_DRAFT,SAVE_DRAFT or SAVE_PUBLISH	None

Request JSON Sample:

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

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

OUT_OF_STOCK,ARCHIVED URLs,replaces

Parameter	Type	Required	Description	Validation
productName	string	No	Updated product name	Min: 2, Max: 100 characters, unique in shopchars
productDescription	string	No	Updated description	Min: 10, Max: 1000 characters
shortDescription	string	No	Updated short description	Max: 200 characterschars
price	decimal	No	Updated selling price	Min: 0.01, Max: 8 digits with 2 decimal places01
comparePrice	decimal	No	Updated originalcompare 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,See USED_LIKE_NEW,enum USED_GOOD, USED_FAIR, REFURBISHED, FOR_PARTSvalues
status	ProductStatus	No	Updated status	DRAFT,Overridden ACTIVE,by INACTIVE,action
urgencyTag	UrgencyTag	Urgency badge on product	NONE, NEW_ARRIVAL, LIMITED_EDITION, LIMITED_OFFER, FEW_REMAINS
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 tagexisting
specifications	object	No	Updated specifications	Completely replaces existing specifications
colors	array	No	Updated color variations	Completely replaces existing colors
minOrderQuantity	integer	No	Updated minimummin order qty	Min: 1
maxOrderQuantity	integer	No	Updated maximummax order qty	Min: 1, must be >=≥ minOrderQuantity
requiresApproval	boolean	No	Updated approval requirement	true/falsemin
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 maximummax	Min: 2, must be >= groupMinSize2
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	NoEnable/disable installment feature toggle	Enable/disable installments	true/false—
installmentPlansmaxQuantityForInstallment	arrayinteger	NoMax qty a buyer can purchase on installment	UpdatedMin: installment plans	Replaces existing plans, required if enabling1
downPaymentRequiredshowStockAvailableToPublic	boolean	NoShow available stock count publicly	Updated down payment requirement	true/false—
minDownPaymentPercentage	decimal	No	Updated down payment percentage	Min: 0, Max: 100
isFeaturedshowSoldCountToPublic	boolean	NoShow sold count publicly	Updated featured status	true/false
isDigital	boolean	No	Updated digital product flag	true/false
requiresShipping	boolean	No	Updated shipping requirement	true/false
metaTitle	string	No	Updated SEO title	Max: 100 characters
metaDescription	string	No	Updated SEO description	Max: 200 characters—

Response JSON Sample:

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

Business Rules for Updates:

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

Error Responses:

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

---

3. Publish Product

Purpose: Publishes a draft product making it active and publicly availableavailable.

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

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

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

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

Response JSON Sample:

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

Publishing Validation Requirements:

• Product namename, mustdescription, notprice, bestock empty
quantity,
• Productcategory, descriptionand mustat notleast beone empty
• Priceimage must be greater than 0
• Stock quantity must be >= 0
• Category must be assigned and active
• At least one product image requiredpresent
• Group buying settings complete if enabled
• Installment plans present if installmentsinstallment is enabled

Error Responses:

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

---

4. Delete Product

Purpose: Deletes a productproduct. usingDraft differentproducts strategiesare basedhard-deleted; onpublished productproducts statusare soft-deleted.

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

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

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

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

Response JSON Sample (Soft Delete):

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

Response JSON Sample (Hard Delete):

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

Deletion Logic:

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

Error Responses:

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

---

5. Restore Product

Purpose: Restores a soft-deleted product back to draft statusstatus.

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

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

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

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

Response JSON Sample:

{
  "success": true,
  "message": "Product 'iPhone 15 Pro Max 512GB'Max' has been restored successfully",
  "data": {
    "productId": "456e7890-e89b-12d3-a456-426614174001",
    "productName": "iPhone 15 Pro Max 512GB",
    "productSlug": "iphone-15-pro-max-512gb"Max",
    "status": "DRAFT",
    "restoredAt": "2025-09-23T15:2026-05-19T15: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 withincluding all features and management informationinformation.

Endpoint: GET /api/v1/e-commerce/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",
    "productType": "PHYSICAL",
    "productDescription": "The most advanced iPhone ever, featuring the groundbreaking A17 Pro chip.ever...",
    "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"urgencyTag": "iPhone 15 Pro Max 512GB - Premium Titanium Smartphone",
    "metaDescription": "Buy the latest iPhone 15 Pro Max with 512GB storage..."NONE",
    "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"Pro"
    },
    "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"00
      }
    ],
    "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"groupMaxSize": 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": true72
    },
    "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"createdAt": "GROUP_BUYING"2026-05-19T10:30:00Z",
    "bestDeal": {
        "option"updatedAt": "GROUP_BUYING",
        "savings": 100.00,
        "finalPrice": 1099.00
      }
    }2026-05-19T14:30:00Z"
  }
}

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 a shop management with summary statisticsstatistics.

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

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

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

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

Response JSON Sample:

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

Summary Statistics Fields:

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

Error Responses:

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

---

8. Get Shop Products Paginated (Management View)

Purpose: Retrieves shop products with pagination for management dashboard

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

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

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

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

Query Parameters:

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

Response JSON Sample:

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

Error Responses:

• 401: Authentication required
• 403: Insufficient permissions
• 404: Shop not found

---

8. Get Shop Products Paginated (Management View)

Purpose: Retrieves shop products with pagination for management dashboard.

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

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

Authentication: Bearer Token

Path Parameters:

Parameter	Type	Required	Description
shopId	UUID	Yes	ID of the shop

Query Parameters:

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

Response JSON Sample:

{
  "success": true,
  "message": "Retrieved 10 products from shop: TechStore Pro (Page 1 of 5)",
  "data": {
    "contents": { "...same structure as /all..." },
    "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 informationviewing.

Endpoint: GET /api/v1/e-commerce/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, shopShop must be active and approved
productId	UUID	Yes	ID of the product	Valid UUID format, productProduct 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",
    "productType": "PHYSICAL",
    "productDescription": "The most advanced iPhone ever, featuring the groundbreaking A17 Pro chip.ever...",
    "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"groupMaxSize": 50,
      "groupPrice": 1099.00,
      "groupDiscount": 100.00,
      "groupDiscountPercentage": 8.34,
      "timeLimitHours": 72
    },
    "installmentOptions": {
      "isAvailable": true,
      "downPaymentRequired": true,
      "minDownPaymentPercentage": 20.00,
      "plans": [
        {
          "duration"planId": "...",
          "planName": "6-Month Interest-Free",
          "paymentFrequency": "MONTHLY",
          "numberOfPayments": 6,
          "interval": "MONTHS",
          "interestRate"apr": 0.00,
          "description"minDownPaymentPercent": "6 months interest-free installment"
        },
        {
          "duration": 12,
          "interval": "MONTHS",
          "interestRate": 2.90,
          "description": "12 months with low interest rate"20
        }
      ]
    },
    "createdAt": "2025-09-23T10:2026-05-19T10: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, found/not approved, or product not found/not active

---

10. Get Public Shop Products

Purpose: Retrieves all active products from a shop for public browsingbrowsing.

Endpoint: GET /api/v1/e-commerce/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, shopShop 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": falsetrue
    },
    "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"Max",
        "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"true
      }
    ],
    "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 browsingbrowsing.

Endpoint: GET /api/v1/e-commerce/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, shopShop must be active and approved

Query Parameters:

Parameter	Type	Required	DescriptionDefault	Validation	DefaultDescription
page	integer	No	1	Page number (1-indexed)	Min: 1	1
size	integer	No	10	Items per page	Min:(max: 1, Max: 50	1050)

Response JSON Sample:

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

Public Pagination Limits:

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

Error Responses:

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

---

12. Search Products

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

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

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

Authentication: Optional Bearer Token

Request Headers:

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

Path Parameters:

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

Query Parameters:

statuses

Parameter	Type	Required	DescriptionDefault	Validation	DefaultDescription
q	string	Yes	—	Search query	Min:(min: 2, Max:max: 100 characters	Nonechars)
status	ProductStatus[]	No	ProductACTIVE	Statuses to search	DRAFT, ACTIVE, INACTIVE, OUT_OF_STOCK, ARCHIVED	ACTIVE (publicowners/admins users)only for non-ACTIVE)
page	integer	No	Page number (1-indexed)	Min: 1	1Page number
size	integer	No	10	Items per page	Min:(max: 1, Max: 50	1050)
sortBy	string	No	Sort fieldrelevance	relevance,relevance, createdAt,createdAt, updatedAt,updatedAt, productName,productName, price,price, stockQuantity,stockQuantity, brand	relevance
sortDir	string	No	Sort direction	asc, desc	asc or desc

Request URL Examples:

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

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

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

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

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

Search Features & Behavior:

and"Apple"

Feature	Description	Example
Multi-word Search	Searches for products containing ALL words	"dell precision" finds products with both "dell" AND "precision"
Partial Matchingmatch	Matches partial words	"iph" matches "iPhone"
Cross-field Search	SearchesMatches acrossagainst multiple product fields	Query matches productName,name, description, shortDescription, brand, tags, specifications
Case Insensitive	Search is case-Case-insensitive	"APPLE" matches "apple"

User Access:

User Type	Searchable Statuses
Public / Authenticated	ACTIVE only
SpecialShop CharactersOwner / Admin	RemovesAll harmful characters	Automatically sanitized for security
Relevance Scoring	Orders by relevance when sortBy=relevance	Products with exact matches ranked higherstatuses

Response JSON Sample:

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

Search Metadata Fields:

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

User Access Levels:

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

Sort Options:

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

Error Responses:

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

---

13. Advanced Product Filter

Purpose: Filters products using multiple criteria with complexcombined combinationsAND/OR and boolean logiclogic.

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

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

Authentication: Optional Bearer Token

RequestPath HeadersParameters:

HeaderParameter	Type	Required	Description
AuthorizationshopId	UUID	Yes	ID of the shop

Query Parameters:

tokenfilters)

Parameter	Type	Required	Default	Description
minPrice	decimal	No	—	Minimum price
maxPrice	decimal	No	—	Maximum price (must be ≥ minPrice)
condition	ProductCondition	No	—	Condition filter
categoryId	UUID	No	—	Category filter
inStock	boolean	No	—	Filter by availability
onSale	boolean	No	—	Filter by sale status
hasGroupBuying	boolean	No	—	Filter by group buying
hasInstallments	boolean	No	—	Filter by installments
hasMultipleColors	boolean	No	—	Filter by color variations
status	ProductStatus[]	No	ACTIVE	Status filter (owners/admins for non-ACTIVE)
page	integer	No	1	Page number
size	integer	No	10	Items per page (max: 50)
sortBy	string	No	BearercreatedAt	createdAt, forupdatedAt, authenticationproductName, (enablesprice, additionalstockQuantity
sortDir	string	No	desc	asc or desc

Filter Logic:

Filter Type	Logic
Price range	AND (minPrice AND maxPrice)
Feature flags	AND (all must match)
Multiple statuses	OR

Error Responses:

• 400: Invalid filter values or price range error
• 404: Shop or category not found

---

14. Get Public Product by Slug

Purpose: Retrieves a single active product by its slug (same response shape as Get Public Product by ID).

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

Access Level: 🌐 Public

Path Parameters:

Parameter	Type	Required	Description
shopId	UUID	Yes	Shop must be active and approved
slug	string	Yes	Product slug

Error Responses:

• 404: Shop not found/not approved, or product not found/not active

---

15. Installment Plan Config

Purpose: CRUD for installment plans attached to a product. Plans are created separately after the product, and linked to it by productId.

Base URL: api/v1/e-commerce/products/{shopId}/{productId}/installment-plans

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

Authentication: Bearer Token

Path Parameters (shared):

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

---

15a. Create Installment Plan

Endpoint: POST api/v1/e-commerce/products/{shopId}/{productId}/installment-plans

Request Body:

shop

Parameter	Type	Required	Description	Validation
shopIdplanName	UUIDstring	Yes	IDDisplay name for the plan	Min: 3, Max: 100 chars
paymentFrequency	PaymentFrequency	Yes	Payment interval	DAILY, WEEKLY, BI_WEEKLY, SEMI_MONTHLY, MONTHLY, QUARTERLY, CUSTOM_DAYS
customFrequencyDays	integer	Conditional	Days between payments	Required when paymentFrequency=CUSTOM_DAYS, min: 1
numberOfPayments	integer	Yes	Total number of thepayments	Min: 2, Max: 120
apr	decimal	Yes	Annual percentage rate	Min: 0.0, Max: 36.0, 2 decimal places
minDownPaymentPercent	integer	Yes	Minimum down payment %	Min: 10, Max: 50
fulfillmentTiming	FulfillmentTiming	Yes	When to filter inship	ValidIMMEDIATE UUID(ship format,after shopdown mustpayment), beAFTER_PAYMENT accessible(layaway — ship after final payment)
displayOrder	integer	No	Sort order in UI	Min: 0, Default: 0
isFeatured	boolean	No	Highlight as recommended plan	Default: false
isActive	boolean	No	Plan is available to buyers	Default: true

QueryRequest JSON Sample:

{
  "planName": "6-Month Interest-Free",
  "paymentFrequency": "MONTHLY",
  "numberOfPayments": 6,
  "apr": 0.00,
  "minDownPaymentPercent": 20,
  "fulfillmentTiming": "IMMEDIATE",
  "displayOrder": 1,
  "isFeatured": true,
  "isActive": true
}

Error Responses:

• 400: Validation errors
• 404: Shop or product not found

---

15b. Get All Installment Plans

Endpoint: GET api/v1/e-commerce/products/{shopId}/{productId}/installment-plans

Returns a list of all installment plans for the product.

Error Responses:

• 404: Shop or product not found

---

15c. Get Installment Plan by ID

Endpoint: GET api/v1/e-commerce/products/{shopId}/{productId}/installment-plans/{planId}

Additional Path Parameter:

Parameter	Type	Description
planId	UUID	ID of the installment plan

---

15d. Update Installment Plan

Endpoint: PUT api/v1/e-commerce/products/{shopId}/{productId}/installment-plans/{planId}

All fields are optional — only provided fields are updated. Same field structure as Create.

---

15e. Delete Installment Plan

Endpoint: DELETE api/v1/e-commerce/products/{shopId}/{productId}/installment-plans/{planId}

---

15f. Activate / Deactivate Plan

Activate: PATCH api/v1/e-commerce/products/{shopId}/{productId}/installment-plans/{planId}/activate

Deactivate: PATCH api/v1/e-commerce/products/{shopId}/{productId}/installment-plans/{planId}/deactivate

Toggles isActive on the plan without changing any other fields.

---

15g. Set Featured Plan

Endpoint: PATCH api/v1/e-commerce/products/{shopId}/{productId}/installment-plans/{planId}/set-featured

Marks the specified plan as the featured (recommended) plan for this product.

---

16. Digital File Management

Purpose: Manages downloadable files for DIGITAL products. Uses a presign → upload → confirm flow to upload files directly to object storage.

Base URL: api/v1/e-commerce/shops/{shopId}/products/{productId}/digital-files

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

Authentication: Bearer Token

Path Parameters (shared):

Parameter	Type	Required	Description
shopId	UUID	Yes	ID of the shop
productId	UUID	Yes	ID of the digital product

---

16a. Presign Upload

Purpose: Generates a presigned PUT URL. The client uploads the file directly to this URL, then calls /confirm.

Endpoint: POST api/v1/e-commerce/shops/{shopId}/products/{productId}/digital-files/presign-upload

Request Body:

(e.g. be order

ValidationParameter	DefaultType	Required	Description
minPricefileName	decimalstring	NoYes	MinimumOriginal pricefile filter	Min: 0, Max: 8 digits	Nonename
maxPricecontentType	decimalstring	NoYes	MaximumMIME pricetype filter	Min: 0, Max: 8 digits, must be >= minPrice	Noneapplication/pdf)
brandfileSize	string[]long	NoYes	BrandFile namessize toin filterbytes (ORmust logic)	Multiple values allowed	Nonepositive)
condition	ProductCondition	No	Product condition filter	NEW, USED_LIKE_NEW, USED_GOOD, USED_FAIR, REFURBISHED, FOR_PARTS	None
categoryId	UUID	No	Category filter	Valid UUID, category must exist	None
tags	string[]	No	Tag filters (OR logic)	Multiple values allowed	None
inStock	boolean	No	Filter by stock availability	true (in stock), false (out of stock)	None
onSale	boolean	No	Filter by sale status	true (on sale), false (not on sale)	None
hasGroupBuying	boolean	No	Filter by group buying availability	true (has group buying), false (no group buying)	None
hasInstallments	boolean	No	Filter by installment availability	true (has installments), false (no installments)	None
hasMultipleColors	boolean	No	Filter by color variations	true (multiple colors), false (single/no colors)	None
isFeatured	boolean	No	Filter by featured status	true (featured), false (not featured)	None
status	ProductStatus[]	No	Product status filter (OR logic)	Multiple statuses allowed	ACTIVE (public users)
pagedisplayOrder	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,for updatedAt,multiple productName, price, stockQuantity, brand	createdAt
sortDir	string	No	Sort direction	asc, desc	descfiles

Request URLJSON ExamplesSample:

#{
  Price"fileName": range"design-kit-v2.fig",
  filter"contentType": GET"application/octet-stream",
  /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/advanced-filter?minPrice=500&maxPrice=1500"fileSize": #52428800,
  Multiple"displayOrder": brand1
filter (Apple OR Samsung)
GET /api/v1/shops/123e4567-e89b-12d3-a456-426614174000/products/advanced-filter?brand=Apple&brand=Samsung&inStock=true

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

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

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

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

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

FilterResponse LogicJSON &Sample:

Combinations

{
  "success": true,
  "message": "Upload URL generated — upload directly to this URL then call /confirm",
  "data": {
    "uploadUrl": "https://s3.example.com/bucket/key?X-Amz-Signature=...",
    "objectKey": "digital-files/product-456/design-kit-v2.fig",
    "expiresAt": "2026-05-19T11:00:00"
  }
}

Upload Flow:

1. Call POST /presign-upload → receive uploadUrl and objectKey
2. PUT {uploadUrl} with binary file body (do not call the API for this step)
3. Call POST /confirm with objectKey to register the file

---

16b. Confirm Upload

Purpose: Registers a file after direct upload to object storage. Must be called after the actual file upload succeeds.

Endpoint: POST api/v1/e-commerce/shops/{shopId}/products/{productId}/digital-files/confirm

Request Body:

betweenfromwithwith

FilterParameter	Type	LogicRequired	ExampleDescription
Price RangeobjectKey	AND (both minPrice AND maxPrice)string	ProductsYes	Returned $500by AND $1500presign-upload
Multiple BrandsfileName	OR (Apple OR Samsung OR Dell)string	ProductsYes	Original anyfile of the specified brandsname
Multiple TagscontentType	OR (premium OR 5g OR wireless)string	ProductsYes	MIME any of the specified tagstype
Multiple StatusesfileSize	OR (ACTIVE OR DRAFT)long	ProductsYes	File anysize ofin the specified statusesbytes
Feature FlagsdisplayOrder	AND (all must be true/false)integer	Products that have group buying AND installments
Combined FiltersNo	ANDSort (between different filter types)	Price range AND brand AND featuresorder

Response JSON Sample:

{
  "success": true,
  "message": "FoundFile 18confirmed productsand matchinglinked yourto filters"product",
  "data": {
    "contents": {
      "shop": {
        "shopId"fileId": "123e4567-aaa1bbbb-e89b-12d3-a456-426614174000"426614174001",
        "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"fileName": "iPhone 15 Pro Max 512GB"design-kit-v2.fig",
    "productSlug"contentType": "iphone-15-pro-max-512gb"application/octet-stream",
    "shortDescription"fileSize": "Premium 6.7-inch iPhone with A17 Pro chip",52428800,
    "primaryImage"fileVersion": "https://example.com/images/iphone15-pro-max.jpg",1,
    "price"displayOrder": 1199.00,1,
    "comparePrice": 1299.00,
          "finalPrice": 1199.00,
          "isOnSale"isActive": true,
    "discountPercentage": 7.69,
          "stockQuantity": 25,
          "isInStock": true,
          "isLowStock": false,
          "brand"uploadedAt": "Apple",
          "sku": "SHP12345678-ELE-APP-512-0001",
          "condition": "NEW",
          "status": "ACTIVE",
          "isFeatured": true,
          "isDigital": false,
          "hasGroupBuying": true,
          "hasInstallments": true,
          "hasMultipleColors": true,
          "groupPrice": 1099.00,
          "startingFromPrice": 1199.00,
          "createdAt": "2025-09-23T10:30:00Z"
        },
        {
          "productId": "567e8901-e89b-12d3-a456-426614174002",
          "productName": "Samsung Galaxy S24 Ultra",
          "productSlug": "samsung-galaxy-s24-ultra",
          "shortDescription": "Premium Android flagship with S Pen",
          "primaryImage": "https://example.com/images/samsung-s24-ultra.jpg",
          "price": 1099.00,
          "comparePrice": 1199.00,
          "finalPrice": 1099.00,
          "isOnSale": true,
          "discountPercentage": 8.34,
          "stockQuantity": 12,
          "isInStock": true,
          "isLowStock": false,
          "brand": "Samsung",
          "sku": "SHP12345678-ELE-SAM-ULT-0007",
          "condition": "NEW",
          "status": "ACTIVE",
          "isFeatured": true,
          "isDigital": false,
          "hasGroupBuying": true,
          "hasInstallments": true,
          "hasMultipleColors": true,
          "groupPrice": 999.00,
          "startingFromPrice": 1099.00,
          "createdAt": "2025-09-22T14:15:00Z"
        }
      ],
      "totalProducts": 18,
      "filterMetadata": {
        "appliedFilters": {
          "minPrice": 800.00,
          "maxPrice": 1500.00,
          "brands": ["Apple", "Samsung"],
          "inStock": true,
          "onSale": true,
          "hasGroupBuying": true,
          "hasInstallments": true,
          "isFeatured": true
        },
        "userType": "PUBLIC",
        "searchedStatuses": ["ACTIVE"],
        "hasActiveFilters": true
      }
    },
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 18,
    "totalPages": 2,
    "hasNext": true,
    "hasPrevious": false2026-05-19T10:45:00"
  }
}

Applied

---

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

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

Filter Validation Rules:

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

Performance Considerations:

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

User Permission Differences:

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

Error Responses:

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

Common Filter Use Cases:

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

14.

16c. Get Public Product by Slug

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

Files

Endpoint: GET /api/v1/e-commerce/shops/{shopId}/products/find-by-slug/{slug}productId}/digital-files

Returns a list of DigitalFileResponse objects for all files linked to the product.

---

16d. Delete File

Endpoint: DELETE api/v1/e-commerce/shops/{shopId}/products/{productId}/digital-files/{fileId}

AccessAdditional LevelPath Parameter:

Parameter	Type	Description
fileId	UUID	ID of the file to delete

---

16e. Toggle File Active Status

Endpoint: 🌐PATCH Public (No authentication required)api/v1/e-commerce/shops/{shopId}/products/{productId}/digital-files/{fileId}/toggle

Authentication: None

PathQuery Parameters:

false

Parameter	Type	Required	Description	Validation
shopIdisActive	UUIDboolean	Yes	IDtrue ofto theactivate, shop	Validto UUID format, shop must be active and approved
slug	String	Yes	Slug of the product	N/Adeactivate

ResponseDeactivated JSONfiles Sample:

are

{
  "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 productshidden from approvedbuyers 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: Shopbut not found, not approved, or product not found/not active

deleted.

---

Quick Reference Guide

Common HTTP Status Codes

requestwithresponse data
• 204
NoContent: Successful DELETE request (hard delete)
orexpiredtoken
(shopowneror system admin required)
orproductnot available
Validationwithdetailedfield-level messages
• 429 Too Many Requests: Rate limit exceeded (search/filter endpoints)
duringprocessing

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

Code	Meaning
200 OK:	Successful GET/PUT/PATCH
201 Created:	Successful POST request, (resource createdcreated)
400 Bad Request:	Invalid request data, validation errors, or business rule violations
401 Unauthorized:	Authentication required,required or invalid token,token
403 Forbidden:	Insufficient permissions
404 Not Found:	Resource not found,found shopor not accessible,accessible
409 Conflict:	Duplicate product name/SKU,name or business constraint violation
422 Unprocessable Entity:	Field-level validation errors
500 Internal Server Error:	Server error

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

DataProduct FormatType StandardsFulfillment Flows

• Dates:
UseISO8601format(2025-09-23T14:30:00Z)
• Prices:
Usedecimal
• UUIDs:
UsestandardUUIDvalidHTTP/HTTPSURLs for product images and color images
• Colors: Hex format (#1D1D1F) for color codes, case insensitive
• Percentages: Decimal format (20.00 for 20%), max 2 decimal places
• Currency: Use shop's base currency, no currency symbols in API

Type	Flow
PHYSICAL	Payment → PENDING_SHIPMENT → Seller ships → Buyer confirms with 26-digit decimalcode places→ (999.00),Escrow storedreleases as→ BigDecimalCOMPLETED
DIGITAL	Payment format→ (123e4567-e89b-12d3-a456-426614174000)COMPLETED Pagination:immediately 1-indexed→ pagesEscrow (pagereleased parameter→ startsDigitalDownloadAccess fromrecords 1) created URLs:→ MustBuyer bedownloads

Product Status Lifecycle

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

OUT_OF_STOCK ←→ ACTIVE (automatic based on inventory)

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

ProductEnums ConditionsReference

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

ReqAction Values & Effects

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

Advanced Features Overview

Group Buying System

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

Requirements:

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

Business Rules:

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

Installment Payment System

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

Payment Intervals:

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

Calculation Formula:

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

Color Variations System

Price Calculation:

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

Price Range Calculation:

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

Validation Rules Summary

Product Creation/Update Validation

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

Business Logic Validation

• Group Size LogicProductType: groupMaxSizePHYSICAL, >=DIGITAL
  groupMinSize

• Price LogicProductCondition: comparePrice > priceNEW AND, groupPriceUSED_LIKE_NEW, <USED_GOOD, priceUSED_FAIR

,
• REFURBISHED, FOR_PARTS

  Order Quantity LogicReqAction: maxOrderQuantitySAVE_DRAFT >=(→ minOrderQuantityDRAFT status), SAVE_PUBLISH

• (→ ACTIVE status)

  Installment LogicUrgencyTag: AtNONE, leastNEW_ARRIVAL, oneLIMITED_EDITION, planLIMITED_OFFER, requiredFEW_REMAINS

  when enabled

• Publishing RequirementsPaymentFrequency: Name,DAILY, description,WEEKLY, price,BI_WEEKLY, stock,SEMI_MONTHLY, category,MONTHLY, imagesQUARTERLY, required

CUSTOM_DAYS

FulfillmentTiming: IMMEDIATE (ship after down payment), AFTER_PAYMENT (layaway — ship after final payment)

SKU Generation SystemFormat

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

Components:Example: SHP12345678-ELE-APP-512-0001

Data Format Standards

• Shop PrefixDates: SHPISO + first 8 characters of shop UUID8601 (uppercase)2026-05-19T14:30:00Z)
• Category CodePrices: FirstDecimal 3with characters2 ofdecimal categoryplaces, namestored (uppercase,as alphanumeric only)BigDecimal
• Brand CodeUUIDs: FirstStandard 3UUID characters of brand name (uppercase, alphanumeric only)format
• Attribute CodePagination: Main1-indexed productpage attribute from specifications or name (3 chars)parameter
• Sequence NumberColors: 4-digitHex sequentialformat number within shop (0001, 0002, etc.)

Examples:

• SHP12345678-ELE-APP-256-0001#RRGGBB (Apple iPhone with 256GB storage)
• Percentages: Decimal format (SHP87654321-LAP-DEL-PRE-000520.00 (Dell= Precision laptop)
• SHP11223344-CLO-NIK-XLA-0012 (Nike XL clothing)

Search & Filter Capabilities

Search Query Processing

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

Filter Combinations Logic

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

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

Performance Optimizations:

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

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:2026-05-19T14:30:00Z"
  }
}

Common Error Scenarios

Creation

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 UsageFlow

Product Management Best Practices

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

Search & Filter Optimization

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

Security Best Practices

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

Performance Optimization

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

Business Logic Guidelines

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

API Integration Examples

Creating a Complete Product (Recommended Flow)

1. POST /shops/{shopId}/productsproducts?action=SAVE_DRAFT
   (action=SAVE_DRAFT)— -create Create basicthe product structure
   - Validate required fieldsshell

2. PUTPOST /products/{shopId}/{productId}/installment-plans
   — add installment plans (if installmentEnabled)

3. POST /shops/{shopId}/products/{productId}/digital-files/presign-upload
   PUT {uploadUrl} (action=SAVE_DRAFT)direct -to Addstorage)
   advancedPOST features/shops/{shopId}/products/{productId}/digital-files/confirm
   — upload digital files (groupDIGITAL buying,products installments)only)

- Upload and set product images
   - Add specifications and color variations
   
3.4. PATCH /shops/{shopId}/products/{productId}/publish
   -— Finalpublish validationwhen check
   - Publish to make publicly availableready

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

---