{"openapi":"3.0.3","info":{"title":"Maxcom Retail Storefront API","version":"1.0.0","description":"Tenant-aware retail storefront, checkout, admin, audit, uploads, consultation, and platform management APIs."},"servers":[{"url":"/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"StoreDomain":{"name":"X-Store-Domain","in":"header","required":true,"schema":{"type":"string"}},"ProductId":{"name":"productId","in":"path","required":true,"schema":{"type":"string"}},"AddressId":{"name":"addressId","in":"path","required":true,"schema":{"type":"string"}},"OrderId":{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}},"TenantId":{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}},"schemas":{"AuthSession":{"type":"object","properties":{"accessToken":{"type":"string"},"user":{"type":"object","properties":{"id":{"type":"string"},"firstName":{"type":"string"},"role":{"type":"string"}}}}},"Credentials":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8}}},"RegisterInput":{"allOf":[{"$ref":"#/components/schemas/Credentials"},{"type":"object","required":["firstName","lastName"],"properties":{"firstName":{"type":"string"},"lastName":{"type":"string"}}}]},"Product":{"type":"object","required":["title","category","price","stock","sku"],"properties":{"id":{"type":"string"},"dummyJsonId":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"price":{"type":"number"},"discountPercentage":{"type":"number"},"rating":{"type":"number"},"stock":{"type":"integer"},"tags":{"type":"array","items":{"type":"string"}},"brand":{"type":"string"},"sku":{"type":"string"},"weight":{"type":"number"},"dimensions":{"type":"object"},"warrantyInformation":{"type":"string"},"shippingInformation":{"type":"string"},"availabilityStatus":{"type":"string"},"reviews":{"type":"array","items":{"type":"object"}},"returnPolicy":{"type":"string"},"minimumOrderQuantity":{"type":"integer"},"meta":{"type":"object"},"thumbnail":{"type":"string"},"images":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"}}},"AiProductDraftRequest":{"type":"object","required":["input"],"additionalProperties":false,"properties":{"input":{"type":"string","minLength":3,"maxLength":5000},"category":{"type":"string"},"existingValues":{"type":"object","additionalProperties":false,"properties":{"price":{"type":"number"},"discountPercentage":{"type":"number"},"stock":{"type":"integer"},"sku":{"type":"string"},"warrantyInformation":{"type":"string"},"shippingInformation":{"type":"string"}}}}},"AiProductDraft":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"categorySuggestion":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"brand":{"type":"string","nullable":true},"warrantyInformation":{"type":"string","nullable":true},"shippingInformation":{"type":"string","nullable":true},"availabilityStatus":{"type":"string","nullable":true},"attributes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"seo":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}}}},"warnings":{"type":"array","items":{"type":"string"}}}},"AiProductDraftResponse":{"type":"object","properties":{"draft":{"$ref":"#/components/schemas/AiProductDraft"},"preservedValues":{"type":"object","description":"Trusted seller/system values returned unchanged for form mapping."}}},"ProductPage":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"total":{"type":"integer"},"skip":{"type":"integer"},"limit":{"type":"integer"}}},"CartItemInput":{"type":"object","required":["productId","quantity"],"properties":{"productId":{"type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":99}}},"Cart":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CartItemInput"}}}},"Address":{"type":"object","required":["name","mobileNumber","line1","locality","district","state","country","postalCode"],"properties":{"id":{"type":"string","readOnly":true},"label":{"type":"string","enum":["Home","Work","Other"]},"isDefault":{"type":"boolean"},"name":{"type":"string"},"mobileNumber":{"type":"string"},"line1":{"type":"string"},"landmark":{"type":"string"},"locality":{"type":"string"},"block":{"type":"string"},"district":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"postalCode":{"type":"string"}}},"OrderInput":{"type":"object","required":["address","items"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CartItemInput"}}}},"PaymentOptions":{"type":"object","properties":{"currency":{"type":"string"},"defaultMethod":{"type":"string","enum":["COD","RAZORPAY"]},"methods":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["COD","RAZORPAY"]},"label":{"type":"string"},"description":{"type":"string"},"keyId":{"type":"string"}}}}}},"RazorpayOrder":{"type":"object","properties":{"orderId":{"type":"string"},"amount":{"type":"integer"},"currency":{"type":"string"},"keyId":{"type":"string"}}},"RazorpayVerifyInput":{"allOf":[{"$ref":"#/components/schemas/OrderInput"},{"type":"object","required":["razorpayOrderId","razorpayPaymentId","razorpaySignature"],"properties":{"razorpayOrderId":{"type":"string"},"razorpayPaymentId":{"type":"string"},"razorpaySignature":{"type":"string"}}}]},"OrderFulfillment":{"type":"object","properties":{"carrier":{"type":"string"},"trackingNumber":{"type":"string"},"trackingUrl":{"type":"string"},"dispatchNote":{"type":"string"},"dispatchedAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"cancelledAt":{"type":"string","format":"date-time"}}},"OrderStatusUpdate":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["PENDING","CONFIRMED","PROCESSING","SHIPPED","DELIVERED","CANCELLED"]},"carrier":{"type":"string"},"trackingNumber":{"type":"string"},"trackingUrl":{"type":"string","format":"uri"},"dispatchNote":{"type":"string"}}},"OrderInvoice":{"type":"object","properties":{"url":{"type":"string"},"fileName":{"type":"string"},"invoiceNumber":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time"},"uploadedBy":{"type":"string"}}},"OrderInvoiceInput":{"type":"object","required":["url","fileName"],"properties":{"url":{"type":"string"},"fileName":{"type":"string"},"invoiceNumber":{"type":"string"}}},"Order":{"type":"object","properties":{"_id":{"type":"string"},"orderNumber":{"type":"string"},"orderStatus":{"type":"string"},"paymentMethod":{"type":"string"},"paymentStatus":{"type":"string"},"items":{"type":"array","items":{"type":"object"}},"shippingAddress":{"$ref":"#/components/schemas/Address"},"pricing":{"type":"object","properties":{"subtotal":{"type":"number"},"delivery":{"type":"number"},"total":{"type":"number"},"currency":{"type":"string"}}},"fulfillment":{"$ref":"#/components/schemas/OrderFulfillment"},"invoice":{"$ref":"#/components/schemas/OrderInvoice"},"statusHistory":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"note":{"type":"string"},"changedAt":{"type":"string","format":"date-time"}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ConsultationInput":{"type":"object","required":["name","email","phone","topic"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"topic":{"type":"string"},"preferredTime":{"type":"string"},"message":{"type":"string"}}},"UploadInput":{"type":"object","required":["fileName","mimeType","data"],"properties":{"fileName":{"type":"string"},"mimeType":{"type":"string","enum":["image/jpeg","image/png","image/webp","application/pdf"]},"data":{"type":"string","description":"Base64 string or data URL"},"purpose":{"type":"string","enum":["product","brand","content","invoice"]}}},"TenantInput":{"type":"object","required":["name","slug","domains","admin"],"properties":{"name":{"type":"string"},"slug":{"type":"string"},"domains":{"type":"array","items":{"type":"string"}},"admin":{"type":"object","required":["firstName","lastName","email"],"properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email"}}},"settings":{"type":"object"}}},"TenantPaymentUpdate":{"type":"object","required":["mode"],"properties":{"mode":{"type":"string","enum":["COD_ONLY","RAZORPAY_ONLY","COD_AND_RAZORPAY"]},"codEnabled":{"type":"boolean"},"codMaxOrderAmount":{"type":"number"},"razorpayEnabled":{"type":"boolean"},"razorpayKeyId":{"type":"string","description":"Public Razorpay key ID returned to checkout when online payment is enabled."},"razorpayKeySecret":{"type":"string","writeOnly":true,"description":"Backend encrypts this value before storing it. It is never returned by platform or storefront APIs."}}},"TenantEmailUpdate":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"},"host":{"type":"string","example":"smtp.hostinger.com"},"port":{"type":"integer","example":465},"secure":{"type":"boolean","example":true},"user":{"type":"string","format":"email"},"password":{"type":"string","writeOnly":true,"description":"Backend encrypts this value before storing it. It is never returned by platform or storefront APIs."},"from":{"type":"string","example":"Maxcom Retail <support@example.com>"}}},"EmailTestInput":{"type":"object","properties":{"to":{"type":"string","format":"email","description":"Optional recipient. Falls back to EMAIL_TEST_TO."},"subject":{"type":"string","minLength":3,"maxLength":140},"message":{"type":"string","minLength":3,"maxLength":1000}}},"EmailStatus":{"type":"object","properties":{"enabled":{"type":"boolean"},"configured":{"type":"boolean"},"host":{"type":"string"},"port":{"type":"integer"},"secure":{"type":"boolean"},"from":{"type":"string"},"testRecipientConfigured":{"type":"boolean"}}},"AuditEvent":{"type":"object","properties":{"action":{"type":"string"},"entityType":{"type":"string"},"entityId":{"type":"string"},"metadata":{"type":"object"},"createdAt":{"type":"string","format":"date-time"}}}}},"paths":{"/auth/register":{"post":{"tags":["Auth"],"security":[],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Create a storefront customer account","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterInput"}}}},"responses":{"201":{"description":"Registered","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/AuthSession"},"requestId":{"type":"string"}}}}}}}}},"/auth/login":{"post":{"tags":["Auth"],"security":[],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Sign in to a storefront account","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credentials"}}}},"responses":{"200":{"description":"Authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/AuthSession"},"requestId":{"type":"string"}}}}}}}}},"/auth/me":{"get":{"tags":["Auth"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Read current session claims","responses":{"200":{"description":"Session claims","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"requestId":{"type":"string"}}}}}}}}},"/auth/refresh":{"post":{"tags":["Auth"],"security":[],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Rotate refresh session","responses":{"200":{"description":"Session refreshed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/AuthSession"},"requestId":{"type":"string"}}}}}}}}},"/auth/logout":{"post":{"tags":["Auth"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Logout and revoke refresh session","responses":{"204":{"description":"Logged out"}}}},"/auth/password-reset/request":{"post":{"tags":["Auth"],"security":[],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Request a password reset OTP","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Request accepted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"accepted":{"type":"boolean"}}},"requestId":{"type":"string"}}}}}}}}},"/auth/password-reset/verify":{"post":{"tags":["Auth"],"security":[],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Verify password reset OTP","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","otp"],"properties":{"email":{"type":"string","format":"email"},"otp":{"type":"string","pattern":"^\\d{6}$"}}}}}},"responses":{"200":{"description":"OTP verified","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"verified":{"type":"boolean"},"resetToken":{"type":"string"}}},"requestId":{"type":"string"}}}}}}}}},"/auth/password-reset/complete":{"post":{"tags":["Auth"],"security":[],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Complete password reset after OTP verification","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","token","password"],"properties":{"email":{"type":"string","format":"email"},"token":{"type":"string"},"password":{"type":"string","minLength":8}}}}}},"responses":{"200":{"description":"Password updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"updated":{"type":"boolean"}}},"requestId":{"type":"string"}}}}}}}}},"/auth/change-password":{"post":{"tags":["Auth"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Change password for the signed-in account","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["currentPassword","password"],"properties":{"currentPassword":{"type":"string","minLength":8},"password":{"type":"string","minLength":8}}}}}},"responses":{"200":{"description":"Password changed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"updated":{"type":"boolean"}}},"requestId":{"type":"string"}}}}}},"400":{"description":"Current password is incorrect"},"401":{"description":"Authentication required"}}}},"/storefront/config":{"get":{"tags":["Storefront"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Read storefront tenant configuration","responses":{"200":{"description":"Storefront config","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"requestId":{"type":"string"}}}}}}}}},"/products":{"get":{"tags":["Storefront"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"skip","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"sortBy","in":"query","schema":{"type":"string"}},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"]}}],"summary":"List products with DummyJSON-style search, limit, skip, and sorting","responses":{"200":{"description":"Product list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ProductPage"},"requestId":{"type":"string"}}}}}}}}},"/products/search":{"get":{"tags":["Storefront"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"skip","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"summary":"Search products","responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ProductPage"},"requestId":{"type":"string"}}}}}}}}},"/products/categories":{"get":{"tags":["Storefront"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"List storefront categories","responses":{"200":{"description":"Categories","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object"}},"requestId":{"type":"string"}}}}}}}}},"/products/category-list":{"get":{"tags":["Storefront"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"List storefront category slugs","responses":{"200":{"description":"Category slugs","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"string"}},"requestId":{"type":"string"}}}}}}}}},"/products/category/{category}":{"get":{"tags":["Storefront"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"},{"name":"category","in":"path","required":true,"schema":{"type":"string"}},{"name":"skip","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"summary":"List products by category","responses":{"200":{"description":"Category products","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ProductPage"},"requestId":{"type":"string"}}}}}}}}},"/products/{productId}":{"get":{"tags":["Storefront"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"},{"$ref":"#/components/parameters/ProductId"}],"summary":"Get product details","responses":{"200":{"description":"Product","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Product"},"requestId":{"type":"string"}}}}}}}}},"/cart":{"get":{"tags":["Cart"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Get current user cart","responses":{"200":{"description":"Cart","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Cart"},"requestId":{"type":"string"}}}}}}}},"delete":{"tags":["Cart"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Clear cart","responses":{"204":{"description":"Cleared"}}}},"/cart/items":{"post":{"tags":["Cart"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Add or replace a cart item","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartItemInput"}}}},"responses":{"201":{"description":"Cart updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Cart"},"requestId":{"type":"string"}}}}}}}}},"/cart/items/{productId}":{"patch":{"tags":["Cart"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"},{"$ref":"#/components/parameters/ProductId"}],"summary":"Update item quantity","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["quantity"],"properties":{"quantity":{"type":"integer"}}}}}},"responses":{"200":{"description":"Cart updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Cart"},"requestId":{"type":"string"}}}}}}}},"delete":{"tags":["Cart"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"},{"$ref":"#/components/parameters/ProductId"}],"summary":"Remove item from cart","responses":{"204":{"description":"Removed"}}}},"/addresses":{"get":{"tags":["Checkout"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"List saved customer delivery addresses","responses":{"200":{"description":"Saved addresses","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"requestId":{"type":"string"}}}}}}}},"post":{"tags":["Checkout"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Save a customer delivery address","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Address"}}}},"responses":{"201":{"description":"Address saved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Address"},"requestId":{"type":"string"}}}}}}}}},"/addresses/{addressId}":{"patch":{"tags":["Checkout"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"},{"$ref":"#/components/parameters/AddressId"}],"summary":"Update a saved delivery address","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Address"}}}},"responses":{"200":{"description":"Address updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Address"},"requestId":{"type":"string"}}}}}}}},"delete":{"tags":["Checkout"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"},{"$ref":"#/components/parameters/AddressId"}],"summary":"Delete a saved delivery address","responses":{"204":{"description":"Address deleted"}}}},"/addresses/{addressId}/default":{"patch":{"tags":["Checkout"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"},{"$ref":"#/components/parameters/AddressId"}],"summary":"Set default delivery address","responses":{"200":{"description":"Default address updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Address"},"requestId":{"type":"string"}}}}}}}}},"/payment-options":{"get":{"tags":["Checkout"],"security":[],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"List tenant-enabled payment methods","responses":{"200":{"description":"Payment options","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/PaymentOptions"},"requestId":{"type":"string"}}}}}}}}},"/payments/razorpay/orders":{"post":{"tags":["Checkout"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Create a Razorpay order for checkout","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderInput"}}}},"responses":{"201":{"description":"Razorpay order created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/RazorpayOrder"},"requestId":{"type":"string"}}}}}}}}},"/payments/razorpay/verify":{"post":{"tags":["Checkout"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Verify Razorpay signature and create a paid order","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RazorpayVerifyInput"}}}},"responses":{"201":{"description":"Paid order created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Order"},"requestId":{"type":"string"}}}}}}}}},"/orders":{"get":{"tags":["Checkout"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"List the signed-in customer order history","responses":{"200":{"description":"Customer orders","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"requestId":{"type":"string"}}}}}}}},"post":{"tags":["Checkout"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Create an order from checkout delivery details","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderInput"}}}},"responses":{"201":{"description":"Order created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Order"},"requestId":{"type":"string"}}}}}}}}},"/orders/{orderId}":{"get":{"tags":["Checkout"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"},{"$ref":"#/components/parameters/OrderId"}],"summary":"Get a signed-in customer order","responses":{"200":{"description":"Customer order","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Order"},"requestId":{"type":"string"}}}}}}}}},"/orders/{orderId}/invoice":{"get":{"tags":["Checkout"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"},{"$ref":"#/components/parameters/OrderId"}],"summary":"Download metadata for a delivered order invoice","description":"Available only to the order owner after the order is DELIVERED and an admin invoice has been uploaded.","responses":{"200":{"description":"Invoice metadata","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/OrderInvoice"},"requestId":{"type":"string"}}}}}},"403":{"description":"Order has not been delivered yet"},"404":{"description":"Invoice is not available"}}}},"/consultations":{"post":{"tags":["Consultations"],"security":[],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Create consultation request","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsultationInput"}}}},"responses":{"201":{"description":"Consultation created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"requestId":{"type":"string"}}}}}}}}},"/uploads":{"post":{"tags":["Uploads"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Upload an image or invoice PDF using base64 JSON","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadInput"}}}},"responses":{"201":{"description":"Uploaded file metadata","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"requestId":{"type":"string"}}}}}}}}},"/admin/products":{"get":{"tags":["Admin"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"List tenant products","responses":{"200":{"description":"Products","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"requestId":{"type":"string"}}}}}}}},"post":{"tags":["Admin"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Create a tenant product","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"responses":{"201":{"description":"Product created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Product"},"requestId":{"type":"string"}}}}}}}}},"/admin/products/ai-draft":{"post":{"tags":["Admin"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"Generate an AI-assisted product draft without saving a product","description":"Requires TENANT_ADMIN or TENANT_MANAGER. AI output is validated and returned as a draft only; trusted commercial fields remain preserved separately.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiProductDraftRequest"}}}},"responses":{"200":{"description":"AI product draft generated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/AiProductDraftResponse"},"requestId":{"type":"string"}}}}}},"403":{"description":"Forbidden"},"429":{"description":"AI rate limit exceeded"}}}},"/admin/products/{productId}":{"patch":{"tags":["Admin"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"},{"$ref":"#/components/parameters/ProductId"}],"summary":"Update tenant product","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"responses":{"200":{"description":"Product updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Product"},"requestId":{"type":"string"}}}}}}}},"delete":{"tags":["Admin"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"},{"$ref":"#/components/parameters/ProductId"}],"summary":"Archive tenant product","responses":{"204":{"description":"Archived"}}}},"/admin/categories":{"get":{"tags":["Admin"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"List tenant category statistics","responses":{"200":{"description":"Categories","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object"}},"requestId":{"type":"string"}}}}}}}}},"/admin/inventory/{productId}":{"patch":{"tags":["Admin"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"},{"$ref":"#/components/parameters/ProductId"}],"summary":"Update product inventory","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["stock"],"properties":{"stock":{"type":"integer"},"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Inventory updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Product"},"requestId":{"type":"string"}}}}}}}}},"/admin/orders":{"get":{"tags":["Admin"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"List tenant orders","responses":{"200":{"description":"Orders","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"requestId":{"type":"string"}}}}}}}}},"/admin/orders/{orderId}/status":{"patch":{"tags":["Admin"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"},{"$ref":"#/components/parameters/OrderId"}],"summary":"Update order status and optional dispatch tracking","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderStatusUpdate"}}}},"responses":{"200":{"description":"Order updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Order"},"requestId":{"type":"string"}}}}}}}}},"/admin/orders/{orderId}/invoice":{"patch":{"tags":["Admin"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"},{"$ref":"#/components/parameters/OrderId"}],"summary":"Attach an uploaded invoice PDF to an order","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderInvoiceInput"}}}},"responses":{"200":{"description":"Invoice attached","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Order"},"requestId":{"type":"string"}}}}}}}}},"/admin/consultations":{"get":{"tags":["Admin"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"List consultation requests","responses":{"200":{"description":"Consultations","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object"}},"requestId":{"type":"string"}}}}}}}}},"/admin/audit-events":{"get":{"tags":["Admin"],"parameters":[{"$ref":"#/components/parameters/StoreDomain"}],"summary":"List tenant audit events","responses":{"200":{"description":"Audit events","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditEvent"}},"requestId":{"type":"string"}}}}}}}}},"/platform/tenants":{"get":{"tags":["Platform"],"summary":"List tenants","responses":{"200":{"description":"Tenants","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object"}},"requestId":{"type":"string"}}}}}}}},"post":{"tags":["Platform"],"summary":"Onboard a tenant and invite admin","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantInput"}}}},"responses":{"201":{"description":"Tenant created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"requestId":{"type":"string"}}}}}}}}},"/platform/auth/login":{"post":{"tags":["Platform"],"security":[],"summary":"Sign in as a platform super admin","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credentials"}}}},"responses":{"200":{"description":"Platform session","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/AuthSession"},"requestId":{"type":"string"}}}}}}}}},"/platform/invitations/complete":{"post":{"tags":["Platform"],"security":[],"summary":"Complete tenant admin invite and set password","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","token","password"],"properties":{"email":{"type":"string","format":"email"},"token":{"type":"string"},"password":{"type":"string"}}}}}},"responses":{"200":{"description":"Invite completed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"requestId":{"type":"string"}}}}}}}}},"/platform/email/status":{"get":{"tags":["Platform"],"summary":"Read platform SMTP email configuration status","responses":{"200":{"description":"Email status","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/EmailStatus"},"requestId":{"type":"string"}}}}}}}}},"/platform/email/test":{"post":{"tags":["Platform"],"summary":"Send a super-admin SMTP test email","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTestInput"}}}},"responses":{"200":{"description":"Email sent","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"requestId":{"type":"string"}}}}}}}}},"/platform/tenants/{tenantId}":{"patch":{"tags":["Platform"],"parameters":[{"$ref":"#/components/parameters/TenantId"}],"summary":"Update tenant","responses":{"200":{"description":"Tenant updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"requestId":{"type":"string"}}}}}}}}},"/platform/tenants/{tenantId}/payment":{"patch":{"tags":["Platform"],"parameters":[{"$ref":"#/components/parameters/TenantId"}],"summary":"Update tenant payment mode and encrypted Razorpay credentials","description":"Requires SUPER_ADMIN. Razorpay Key Secret is encrypted in MongoDB and omitted from every API response.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantPaymentUpdate"}}}},"responses":{"200":{"description":"Payment configuration updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"requestId":{"type":"string"}}}}}}}}},"/platform/tenants/{tenantId}/email":{"patch":{"tags":["Platform"],"parameters":[{"$ref":"#/components/parameters/TenantId"}],"summary":"Update tenant SMTP email settings","description":"Requires SUPER_ADMIN. SMTP password is encrypted in MongoDB and omitted from every API response.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantEmailUpdate"}}}},"responses":{"200":{"description":"Email configuration updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"requestId":{"type":"string"}}}}}}}}},"/platform/tenants/{tenantId}/email/test":{"post":{"tags":["Platform"],"parameters":[{"$ref":"#/components/parameters/TenantId"}],"summary":"Send a tenant SMTP test email","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTestInput"}}}},"responses":{"200":{"description":"Tenant email sent","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"requestId":{"type":"string"}}}}}}}}},"/platform/tenants/{tenantId}/domains":{"put":{"tags":["Platform"],"parameters":[{"$ref":"#/components/parameters/TenantId"}],"summary":"Replace tenant domains","responses":{"200":{"description":"Domains updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"requestId":{"type":"string"}}}}}}}}},"/platform/tenants/{tenantId}/statistics":{"get":{"tags":["Platform"],"parameters":[{"$ref":"#/components/parameters/TenantId"}],"summary":"Read tenant statistics","responses":{"200":{"description":"Tenant statistics","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"requestId":{"type":"string"}}}}}}}}},"/platform/tenants/{tenantId}/activate":{"post":{"tags":["Platform"],"parameters":[{"$ref":"#/components/parameters/TenantId"}],"summary":"Activate tenant","responses":{"200":{"description":"Tenant activated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"requestId":{"type":"string"}}}}}}}}},"/platform/tenants/{tenantId}/suspend":{"post":{"tags":["Platform"],"parameters":[{"$ref":"#/components/parameters/TenantId"}],"summary":"Suspend tenant","responses":{"200":{"description":"Tenant suspended","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"requestId":{"type":"string"}}}}}}}}},"/platform/tenants/{tenantId}/archive":{"post":{"tags":["Platform"],"parameters":[{"$ref":"#/components/parameters/TenantId"}],"summary":"Archive tenant","responses":{"200":{"description":"Tenant archived","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"requestId":{"type":"string"}}}}}}}}}}}