Products Postman Doc: https://documenter.getpostman.com/view/20499442/[merchant-collection-id] -------------------------------------------------------------------------------- API: Create Product -------------------------------------------------------------------------------- POST /merchant/api/v1/domains/:domain_id/products [Seller Catalog & Inventory, Orchestration] Description: Create a new product with variants, pricing, inventory, and media. Supports simple products and products with multiple variants. Handles SEO optimization, categorization, and multi-store inventory allocation. Request Body: { "title": "Premium Organic Coffee Beans", "description": "100% Arabica coffee beans sourced from sustainable farms", "product_type": "physical", // ENUM: physical, digital, service "status": "active", // ENUM: active, draft, archived "visibility": "visible", // ENUM: visible, hidden "sku": "COFFEE-001", "barcode": "1234567890123", "price": 24.99, "compare_at_price": 29.99, "cost_per_item": 12.00, "track_inventory": true, "inventory_policy": "deny", // ENUM: deny, continue "inventory_quantity": 100, "weight": 1.0, "weight_unit": "kg", "requires_shipping": true, "taxable": true, "tax_code": "FOOD", "vendor": "Premium Coffee Co", "tags": ["organic", "coffee", "arabica", "fair-trade"], "categories": ["670d0ca92aa2235ab2272e80"], // Category IDs "collections": ["670d0ca92aa2235ab2272e81"], // Collection IDs "images": [ { "url": "https://cdn.example.com/coffee-front.jpg", "alt_text": "Premium coffee beans front view", "position": 1 }, { "url": "https://cdn.example.com/coffee-side.jpg", "alt_text": "Premium coffee beans side view", "position": 2 } ], "variants": [ { "title": "250g", "sku": "COFFEE-001-250G", "barcode": "1234567890124", "price": 24.99, "compare_at_price": 29.99, "inventory_quantity": 50, "weight": 0.25, "option1": "250g", "option2": null, "option3": null }, { "title": "500g", "sku": "COFFEE-001-500G", "barcode": "1234567890125", "price": 44.99, "compare_at_price": 54.99, "inventory_quantity": 50, "weight": 0.5, "option1": "500g", "option2": null, "option3": null } ], "options": [ { "name": "Size", "values": ["250g", "500g", "1kg"] } ], "seo": { "title": "Premium Organic Coffee Beans - Buy Online", "description": "Order premium organic Arabica coffee beans. Fair trade, sustainably sourced.", "keywords": ["organic coffee", "arabica beans", "fair trade coffee"] }, "custom_fields": { "roast_level": "medium", "origin": "Colombia", "certifications": ["Organic", "Fair Trade"] }, "store_ids": ["store_id_1", "store_id_2"] // Multi-store assignment } Flow Sequence: # Step 1: Validate Product Data Validation checks: - Required fields present - SKU uniqueness - Price validation - Variant consistency - Image URLs validity - Category/collection existence # Step 2: Generate Product Handle (URL slug) Internal logic: - Slugify title: "premium-organic-coffee-beans" - Ensure uniqueness within domain # Step 3: Upload/Validate Images For each image: POST /api/media/validate [Util Service, Core Microservices] # Validate image URLs, check CDN availability # Step 4: Validate Categories GET /api/categories/validate [Product Service, Core Microservices] # Request: { "category_ids": [...] } # Verify categories exist and belong to domain # Step 5: Create Product Record POST /api/products [Product Service, Core Microservices] # Request: { # "domain_id": "...", # "title": "...", # "description": "...", # "handle": "premium-organic-coffee-beans", # "product_type": "physical", # "status": "active", # "vendor": "...", # "tags": [...], # "seo": {...}, # "custom_fields": {...} # } # Returns: { "product_id": "...", "handle": "..." } # Step 6: Create Variants For each variant: POST /api/products/:product_id/variants [Product Service, Core Microservices] # Request: { # "title": "...", # "sku": "...", # "barcode": "...", # "price": ..., # "compare_at_price": ..., # "weight": ..., # "option1": "...", # "position": ... # } # Step 7: Create Product Options For each option: POST /api/products/:product_id/options [Product Service, Core Microservices] # Request: { "name": "Size", "values": ["250g", "500g", "1kg"] } # Step 8: Associate Images For each image: POST /api/products/:product_id/images [Product Service, Core Microservices] # Request: { "url": "...", "alt_text": "...", "position": ... } # Step 9: Link to Categories POST /api/products/:product_id/categories [Product Service, Core Microservices] # Request: { "category_ids": [...] } # Step 10: Link to Collections POST /api/products/:product_id/collections [Product Service, Core Microservices] # Request: { "collection_ids": [...] } # Step 11: Initialize Inventory For each variant: POST /api/inventory [Inventory Service, Core Microservices] # Request: { # "product_id": "...", # "variant_id": "...", # "sku": "...", # "quantity": ..., # "track_inventory": true, # "store_ids": [...], # "warehouse_allocations": [...] # } # Step 12: Create Product-Store Associations For each store_id: POST /api/products/:product_id/stores [Product Service, Core Microservices] # Links product to specific stores # Step 13: Index for Search POST /api/search/index [Search Engine, Shared Services] # Request: { # "type": "product", # "id": "...", # "data": { "title", "description", "tags", "categories", ... } # } # Step 14: Generate Product Feed POST /api/feeds/generate [Util Service, Core Microservices] # Update product feeds (Google Shopping, Facebook, etc.) # Step 15: Cache Product POST /api/cache/set [Caching Service, Shared Services] # Key: product:{product_id} # TTL: 3600 seconds # Step 16: Log Product Creation POST /api/events/log [Util Service, Core Microservices] # Event: "product_created" Response: { "id": "670d0ca92aa2235ab2272e82", "domain_id": "670d0ca92aa2235ab2272e79", "title": "Premium Organic Coffee Beans", "description": "100% Arabica coffee beans...", "handle": "premium-organic-coffee-beans", "product_type": "physical", "status": "active", "visibility": "visible", "vendor": "Premium Coffee Co", "tags": ["organic", "coffee", "arabica", "fair-trade"], "price_range": { "min": 24.99, "max": 44.99 }, "variants": [ { "id": "var_123", "product_id": "670d0ca92aa2235ab2272e82", "title": "250g", "sku": "COFFEE-001-250G", "price": 24.99, "inventory_quantity": 50, "available": true }, { "id": "var_124", "product_id": "670d0ca92aa2235ab2272e82", "title": "500g", "sku": "COFFEE-001-500G", "price": 44.99, "inventory_quantity": 50, "available": true } ], "images": [ { "id": "img_1", "url": "https://cdn.example.com/coffee-front.jpg", "alt_text": "Premium coffee beans front view", "position": 1 } ], "seo": { "title": "Premium Organic Coffee Beans - Buy Online", "description": "Order premium organic Arabica coffee beans..." }, "created_at": "2024-10-14T12:00:00Z", "updated_at": "2024-10-14T12:00:00Z" } Error Responses: 409 Conflict - SKU already exists { "status": 409, "message": "Product with SKU 'COFFEE-001' already exists", "error_code": "DUPLICATE_SKU" } -------------------------------------------------------------------------------- API: List Products -------------------------------------------------------------------------------- GET /merchant/api/v1/domains/:domain_id/products [Seller Catalog & Inventory, Orchestration] Description: List and search products with filtering, sorting, and pagination. Supports full-text search, faceted filtering, and bulk selection. Query Parameters: ?page=1 &limit=50 &status=active,draft &visibility=visible &category_id=670d0ca92aa2235ab2272e80 &collection_id=670d0ca92aa2235ab2272e81 &vendor=Premium Coffee Co &tags=organic,coffee &search=coffee &sort_by=created_at &sort_order=desc &store_id=store_id_1 &in_stock=true &price_min=10.00 &price_max=100.00 Flow Sequence: # Step 1: Parse and Validate Query Parameters Validate filters, pagination, sort options # Step 2: Build Search Query Internal query builder with filters # Step 3: Check Cache GET /api/cache/product-list [Caching Service, Shared Services] # Cache key based on query params # Step 4: Search Products (if not cached) POST /api/products/search [Product Service, Core Microservices] # Request: { # "domain_id": "...", # "filters": { # "status": ["active", "draft"], # "category_ids": [...], # "tags": [...], # "search_text": "coffee" # }, # "pagination": { "page": 1, "limit": 50 }, # "sort": { "field": "created_at", "order": "desc" } # } # Step 5: Get Inventory Status POST /api/inventory/check-availability [Inventory Service, Core Microservices] # For each product, get current stock status # Step 6: Enrich with Images and Variants Parallel calls to get first image and variant count # Step 7: Apply Store Filter If store_id provided, filter products by store association # Step 8: Calculate Facets POST /api/products/facets [Product Service, Core Microservices] # Calculate available filters (categories, vendors, price ranges, etc.) # Step 9: Cache Results POST /api/cache/set [Caching Service, Shared Services] # TTL: 300 seconds (5 minutes) Response: { "products": [ { "id": "670d0ca92aa2235ab2272e82", "title": "Premium Organic Coffee Beans", "handle": "premium-organic-coffee-beans", "status": "active", "visibility": "visible", "vendor": "Premium Coffee Co", "product_type": "physical", "price_range": { "min": 24.99, "max": 44.99 }, "featured_image": { "url": "https://cdn.example.com/coffee-front.jpg", "alt_text": "Premium coffee beans" }, "variant_count": 2, "total_inventory": 100, "in_stock": true, "tags": ["organic", "coffee"], "created_at": "2024-10-14T12:00:00Z" } ], "pagination": { "page": 1, "limit": 50, "total_pages": 10, "total_count": 487 }, "facets": { "categories": [ { "id": "cat_1", "name": "Coffee", "count": 156 }, { "id": "cat_2", "name": "Tea", "count": 98 } ], "vendors": [ { "name": "Premium Coffee Co", "count": 45 } ], "price_ranges": [ { "min": 0, "max": 25, "count": 234 }, { "min": 25, "max": 50, "count": 189 } ], "tags": [ { "tag": "organic", "count": 178 }, { "tag": "fair-trade", "count": 123 } ] } } -------------------------------------------------------------------------------- API: Get Product -------------------------------------------------------------------------------- GET /merchant/api/v1/domains/:domain_id/products/:id [Seller Catalog & Inventory, Orchestration] Description: Get complete product details including all variants, images, inventory, pricing, SEO, and associations. Flow Sequence: # Step 1: Check Cache GET /api/cache/product/:product_id [Caching Service, Shared Services] # Step 2: Get Product (if not cached) GET /api/products/:product_id [Product Service, Core Microservices] # Step 3: Get Variants GET /api/products/:product_id/variants [Product Service, Core Microservices] # Step 4: Get Images GET /api/products/:product_id/images [Product Service, Core Microservices] # Step 5: Get Options GET /api/products/:product_id/options [Product Service, Core Microservices] # Step 6: Get Categories GET /api/products/:product_id/categories [Product Service, Core Microservices] # Step 7: Get Collections GET /api/products/:product_id/collections [Product Service, Core Microservices] # Step 8: Get Inventory for Each Variant POST /api/inventory/get-by-skus [Inventory Service, Core Microservices] # Request: { "skus": [...] } # Step 9: Get Store Associations GET /api/products/:product_id/stores [Product Service, Core Microservices] # Step 10: Get Pricing History (Optional) GET /api/products/:product_id/price-history [Product Service, Core Microservices] # Step 11: Cache Complete Product POST /api/cache/set [Caching Service, Shared Services] # TTL: 3600 seconds Response: { "id": "670d0ca92aa2235ab2272e82", "domain_id": "670d0ca92aa2235ab2272e79", "title": "Premium Organic Coffee Beans", "description": "100% Arabica coffee beans...", "handle": "premium-organic-coffee-beans", "product_type": "physical", "status": "active", "visibility": "visible", "vendor": "Premium Coffee Co", "tags": ["organic", "coffee", "arabica"], "variants": [ { "id": "var_123", "title": "250g", "sku": "COFFEE-001-250G", "barcode": "1234567890124", "price": 24.99, "compare_at_price": 29.99, "cost_per_item": 12.00, "inventory_quantity": 50, "inventory_policy": "deny", "weight": 0.25, "weight_unit": "kg", "requires_shipping": true, "taxable": true, "option1": "250g", "image_id": "img_1" } ], "options": [ { "id": "opt_1", "name": "Size", "position": 1, "values": ["250g", "500g", "1kg"] } ], "images": [ { "id": "img_1", "url": "https://cdn.example.com/coffee-front.jpg", "alt_text": "Premium coffee beans front view", "position": 1, "variant_ids": ["var_123"] } ], "categories": [ { "id": "cat_1", "name": "Coffee", "handle": "coffee" } ], "collections": [ { "id": "col_1", "name": "Bestsellers", "handle": "bestsellers" } ], "seo": { "title": "Premium Organic Coffee Beans - Buy Online", "description": "Order premium organic Arabica coffee beans...", "keywords": ["organic coffee", "arabica beans"] }, "stores": ["store_id_1", "store_id_2"], "total_inventory": 100, "total_available": 100, "created_at": "2024-10-14T12:00:00Z", "updated_at": "2024-10-14T15:30:00Z" } -------------------------------------------------------------------------------- API: Update Product -------------------------------------------------------------------------------- PATCH /merchant/api/v1/domains/:domain_id/products/:id [Seller Catalog & Inventory, Orchestration] Description: Update product information. Supports partial updates. Request Body: { "title": "Premium Organic Coffee Beans - Updated", "price": 26.99, "status": "active", "tags": ["organic", "coffee", "arabica", "premium"], "images": [ { "url": "https://cdn.example.com/new-image.jpg", "position": 1 } ] } Flow Sequence: # Step 1: Validate Update Data # Step 2: Get Current Product GET /api/products/:product_id [Product Service, Core Microservices] # Step 3: Update Product PATCH /api/products/:product_id [Product Service, Core Microservices] # Step 4: Update Related Resources (if changed) - Update variants if pricing changed - Update images if media changed - Reindex search if searchable fields changed # Step 5: Invalidate Cache DELETE /api/cache/product/:product_id [Caching Service, Shared Services] # Step 6: Reindex Search PUT /api/search/index/:product_id [Search Engine, Shared Services] # Step 7: Update Product Feeds POST /api/feeds/update [Util Service, Core Microservices] # Step 8: Log Update POST /api/events/log [Util Service, Core Microservices] Response: { "id": "670d0ca92aa2235ab2272e82", "title": "Premium Organic Coffee Beans - Updated", "price_range": { "min": 26.99, "max": 46.99 }, "updated_at": "2024-10-14T16:00:00Z" } -------------------------------------------------------------------------------- API: Delete Product -------------------------------------------------------------------------------- DELETE /merchant/api/v1/domains/:domain_id/products/:id [Seller Catalog & Inventory, Orchestration] Description: Soft delete product (marks as archived). Preserves data for orders. Flow Sequence: # Step 1: Check Active Orders GET /api/orders/by-product/:product_id [Order Service, Core Microservices] # Verify no pending orders # Step 2: Archive Product PATCH /api/products/:product_id [Product Service, Core Microservices] # Set status: "archived" # Step 3: Remove from Search Index DELETE /api/search/index/:product_id [Search Engine, Shared Services] # Step 4: Remove from Product Feeds POST /api/feeds/remove [Util Service, Core Microservices] # Step 5: Invalidate Cache DELETE /api/cache/product/:product_id [Caching Service, Shared Services] # Step 6: Log Deletion POST /api/events/log [Util Service, Core Microservices] Response: { "status": 200, "message": "Product archived successfully", "product_id": "670d0ca92aa2235ab2272e82" } -------------------------------------------------------------------------------- API: Bulk Update Products -------------------------------------------------------------------------------- PATCH /merchant/api/v1/domains/:domain_id/products/bulk [Seller Catalog & Inventory, Orchestration] Description: Update multiple products in a single request. Supports updating status, pricing, tags, categories, and inventory for bulk operations. Request Body: { "product_ids": ["id1", "id2", "id3"], "updates": { "status": "active", "tags": { "add": ["new-tag"], "remove": ["old-tag"] }, "categories": { "add": ["cat_id_1"], "remove": ["cat_id_2"] }, "discount": { "type": "percentage", "value": 10 } } } Flow Sequence: # Step 1: Validate Product IDs # Step 2: For each product, apply updates # Step 3: Batch update in database # Step 4: Invalidate caches # Step 5: Reindex search # Step 6: Log bulk operation Response: { "success": true, "updated_count": 3, "failed": [], "updated_products": ["id1", "id2", "id3"] }