{ "openapi": "3.0.0", "info": { "title": "ChawkBazar API", "description": "ChawkBazar E-commerce Platform REST API Documentation", "contact": { "name": "API Support", "email": "support@chawkbazar.com" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" }, "version": "1.0.0" }, "servers": [ { "url": "http://localhost:8000/api", "description": "API Server" } ], "paths": { "/abusive_reports": { "get": { "tags": [ "Content Moderation" ], "summary": "List Abuse Reports", "description": "Get paginated list of all abuse reports. Requires SUPER_ADMIN permission.", "operationId": "listAbuseReports", "parameters": [ { "name": "limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Reports retrieved successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" } }, "security": [ { "sanctum": [] } ] } }, "/abusive_reports/{id}": { "get": { "tags": [ "Content Moderation" ], "summary": "Get Abuse Report Details", "description": "Get a single abuse report by ID. Requires SUPER_ADMIN permission.", "operationId": "getAbuseReport", "parameters": [ { "name": "id", "in": "path", "description": "Report ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Report retrieved successfully" }, "401": { "description": "Unauthenticated" }, "404": { "description": "Report not found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Content Moderation" ], "summary": "Delete Abuse Report", "description": "Delete an abuse report. Requires SUPER_ADMIN permission.", "operationId": "deleteAbuseReport", "parameters": [ { "name": "id", "in": "path", "description": "Report ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Report deleted successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "404": { "description": "Report not found" } }, "security": [ { "sanctum": [] } ] } }, "/abusive_reports/accept": { "post": { "tags": [ "Content Moderation" ], "summary": "Accept Abuse Report", "description": "Accept an abuse report and delete the reported content. Requires SUPER_ADMIN permission.", "operationId": "acceptAbuseReport", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "model_id", "model_type" ], "properties": { "model_id": { "type": "integer", "example": 5 }, "model_type": { "type": "string", "example": "Marvel\\\\Database\\\\Models\\\\Review" } }, "type": "object" } } } }, "responses": { "200": { "description": "Report accepted, content deleted" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "404": { "description": "Content not found" } }, "security": [ { "sanctum": [] } ] } }, "/abusive_reports/reject": { "post": { "tags": [ "Content Moderation" ], "summary": "Reject Abuse Report", "description": "Reject an abuse report and keep the content. Deletes all reports for this content. Requires SUPER_ADMIN permission.", "operationId": "rejectAbuseReport", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "model_id", "model_type" ], "properties": { "model_id": { "type": "integer", "example": 5 }, "model_type": { "type": "string", "example": "Marvel\\\\Database\\\\Models\\\\Review" } }, "type": "object" } } } }, "responses": { "200": { "description": "Report rejected, content kept" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "404": { "description": "Content not found" } }, "security": [ { "sanctum": [] } ] } }, "/addresses": { "get": { "tags": [ "Addresses" ], "summary": "List User Addresses", "description": "Retrieve all addresses for the authenticated user.", "operationId": "getAddresses", "responses": { "200": { "description": "Addresses retrieved", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Addresses" ], "summary": "Create Address", "description": "Add a new address to the user's profile.", "operationId": "createAddress", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "type", "address", "customer_id" ], "properties": { "title": { "type": "string", "example": "Work" }, "type": { "type": "string", "enum": [ "billing", "shipping" ], "example": "billing" }, "address": { "type": "object" }, "customer_id": { "type": "integer", "example": 10 }, "default": { "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "201": { "description": "Address created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/addresses/{id}": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Details", "description": "Retrieve details of a specific address.", "operationId": "getAddress", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Address details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" } } } }, "404": { "description": "Address not found" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Addresses" ], "summary": "Update Address", "description": "Update an existing address.", "operationId": "updateAddress", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" } } } }, "responses": { "200": { "description": "Address updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Address not found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Addresses" ], "summary": "Delete Address", "description": "Remove an address from the user profile.", "operationId": "deleteAddress", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Address deleted successfully" }, "401": { "description": "Unauthenticated" }, "404": { "description": "Address not found" } }, "security": [ { "sanctum": [] } ] } }, "/generate-descriptions": { "post": { "tags": [ "AI" ], "summary": "Generate product description with AI", "description": "Generate a creative product description using OpenAI based on product name and keywords. Requires STORE_OWNER or STAFF permission.", "operationId": "generateAiDescription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "product_name" ], "properties": { "product_name": { "type": "string", "example": "Wireless Noise Cancelling Headphones" }, "keywords": { "type": "array", "items": { "type": "string" }, "example": [ "premium", "long battery life", "sleek design" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Generated description", "content": { "application/json": { "schema": { "properties": { "description": { "type": "string", "example": "Experience pure sound with these Premium Wireless Noise Cancelling Headphones..." } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "500": { "description": "AI service error" } }, "security": [ { "sanctum": [] } ] } }, "/analytics": { "get": { "tags": [ "Analytics" ], "summary": "Get shop or platform analytics", "description": "Retrieve comprehensive analytics including revenue, refunds, orders, and sales trends. Accessible by Staff, Store Owners, and Super Admins.", "operationId": "getAnalytics", "responses": { "200": { "description": "Analytics data retrieved successfully", "content": { "application/json": { "schema": { "properties": { "totalRevenue": { "type": "number", "format": "float", "example": 1500.5 }, "totalRefunds": { "type": "number", "format": "float", "example": 100 }, "totalShops": { "type": "integer", "example": 5 }, "totalVendors": { "type": "integer", "example": 3 }, "todaysRevenue": { "type": "number", "format": "float", "example": 250.75 }, "totalOrders": { "type": "integer", "example": 120 }, "newCustomers": { "type": "integer", "example": 10 }, "totalYearSaleByMonth": { "type": "array", "items": { "properties": { "month": { "type": "string", "example": "January" }, "total": { "type": "number", "format": "float", "example": 1200 } }, "type": "object" } }, "todayTotalOrderByStatus": { "properties": { "pending": { "type": "integer", "example": 2 }, "processing": { "type": "integer", "example": 5 }, "complete": { "type": "integer", "example": 10 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "sanctum": [] } ] } }, "/low-stock-products": { "get": { "tags": [ "Analytics" ], "summary": "List products with low stock", "description": "Retrieve products where quantity is less than 10. Supports filtering by shop, type and language.", "operationId": "getLowStockProducts", "parameters": [ { "name": "limit", "in": "query", "description": "Number of products to retrieve", "required": false, "schema": { "type": "integer", "default": 10, "example": 10 } }, { "name": "shop_id", "in": "query", "description": "Filter by shop ID", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "type_id", "in": "query", "description": "Filter by type ID", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "language", "in": "query", "description": "Language code", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "List of low stock products", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } } }, "security": [ { "sanctum": [] } ] } }, "/category-wise-product": { "get": { "tags": [ "Analytics" ], "summary": "Get product count distribution by category", "description": "Retrieve a list of categories with their respective product counts for the current user's scope.", "operationId": "getCategoryWiseProductCount", "parameters": [ { "name": "limit", "in": "query", "description": "Number of categories to retrieve", "schema": { "type": "integer", "default": 15 } }, { "name": "language", "in": "query", "description": "Language code", "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Category distribution data", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "category_id": { "type": "integer", "example": 1 }, "category_name": { "type": "string", "example": "Electronics" }, "shop_name": { "type": "string", "example": "Gadget Store" }, "product_count": { "type": "integer", "example": 42 } }, "type": "object" } } } } } }, "security": [ { "sanctum": [] } ] } }, "/category-wise-product-sale": { "get": { "tags": [ "Analytics" ], "summary": "Get sales distribution by category", "description": "Retrieve top categories based on total product sales volume.", "operationId": "getCategoryWiseProductSales", "parameters": [ { "name": "limit", "in": "query", "description": "Number of categories to retrieve", "schema": { "type": "integer", "default": 15 } }, { "name": "language", "in": "query", "description": "Language code", "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Category sales data", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "category_id": { "type": "integer", "example": 1 }, "category_name": { "type": "string", "example": "Electronics" }, "shop_name": { "type": "string", "example": "Gadget Store" }, "total_sales": { "type": "number", "example": 150 } }, "type": "object" } } } } } }, "security": [ { "sanctum": [] } ] } }, "/top-rate-product": { "get": { "tags": [ "Analytics" ], "summary": "Get highest rated products", "description": "Retrieve products sorted by their average rating. Accessible for shop-scoped analytics.", "operationId": "getTopRatedProducts", "parameters": [ { "name": "limit", "in": "query", "description": "Number of products to retrieve", "schema": { "type": "integer", "default": 10 } }, { "name": "language", "in": "query", "description": "Language code", "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Top rated products data", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Comfortable Shirt" }, "actual_rating": { "type": "number", "format": "float", "example": 4.85 }, "rating_count": { "type": "integer", "example": 25 } }, "type": "object" } } } } } }, "security": [ { "sanctum": [] } ] } }, "/attachments": { "get": { "tags": [ "Attachments" ], "summary": "Get list of attachments", "description": "Returns paginated list of all uploaded attachments", "operationId": "getAttachments", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "original": { "type": "string", "example": "https://example.com/storage/uploads/image.jpg" }, "thumbnail": { "type": "string", "example": "https://example.com/storage/uploads/conversions/image-thumbnail.jpg" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } } } } } }, "post": { "tags": [ "Attachments" ], "summary": "Upload new attachment(s)", "description": "Upload one or multiple files. Rate limited to 10 uploads per minute per user. Supports images, documents, and other file types. Images automatically generate thumbnails.", "operationId": "storeAttachment", "requestBody": { "description": "File(s) to upload", "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "attachment[]" ], "properties": { "attachment[]": { "description": "Array of files to upload (supports multiple files)", "type": "array", "items": { "type": "string", "format": "binary" } } }, "type": "object" } } } }, "responses": { "200": { "description": "File(s) uploaded successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 123 }, "original": { "type": "string", "example": "https://example.com/storage/uploads/file.jpg" }, "thumbnail": { "description": "Only for images", "type": "string", "example": "https://example.com/storage/uploads/thumb_file.jpg" } }, "type": "object" } } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation Error - Invalid file type or size" }, "429": { "description": "Too Many Requests - Rate limit exceeded (10/min)" } }, "security": [ { "sanctum": [] } ] } }, "/attachments/{id}": { "get": { "tags": [ "Attachments" ], "summary": "Get attachment by ID", "description": "Returns a single attachment with its details", "operationId": "getAttachmentById", "parameters": [ { "name": "id", "in": "path", "description": "Attachment ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "original": { "type": "string", "example": "https://example.com/storage/uploads/image.jpg" }, "thumbnail": { "type": "string", "example": "https://example.com/storage/uploads/conversions/image-thumbnail.jpg" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Attachment not found" } } }, "put": { "tags": [ "Attachments" ], "summary": "Update attachment (Not implemented)", "description": "This endpoint is currently not implemented and will return false", "operationId": "updateAttachment", "parameters": [ { "name": "id", "in": "path", "description": "Attachment ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Returns false (not implemented)", "content": { "application/json": { "schema": { "type": "boolean" }, "example": false } } } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Attachments" ], "summary": "Delete attachment", "description": "Permanently delete an attachment and its associated files from storage. Rate limited to 10 requests per minute.", "operationId": "deleteAttachment", "parameters": [ { "name": "id", "in": "path", "description": "Attachment ID to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Attachment deleted successfully", "content": { "application/json": { "schema": { "type": "boolean" }, "example": true } } }, "404": { "description": "Attachment not found" }, "401": { "description": "Unauthenticated" }, "429": { "description": "Too Many Requests - Rate limit exceeded" } }, "security": [ { "sanctum": [] } ] } }, "/attributes": { "get": { "tags": [ "Attributes" ], "summary": "List Attributes", "description": "List attributes. customizable by Shop.", "operationId": "getAttributes", "parameters": [ { "name": "shop_id", "in": "query", "description": "Filter by Shop ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Attributes retrieved", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Attribute" } } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Attributes" ], "summary": "Create Attribute", "description": "Create a new attribute. Requires STORE_OWNER permission for the shop.", "operationId": "createAttribute", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "shop_id" ], "properties": { "name": { "type": "string", "example": "Color" }, "shop_id": { "type": "integer", "example": 10 }, "language": { "type": "string", "example": "en" }, "values": { "type": "array", "items": { "properties": { "value": { "type": "string" }, "meta": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Attribute created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "sanctum": [] } ] } }, "/attributes/{id}": { "get": { "tags": [ "Attributes" ], "summary": "Get Attribute", "description": "Get attribute details by ID or Slug", "operationId": "getAttribute", "parameters": [ { "name": "id", "in": "path", "description": "Attribute ID or Slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Attribute details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" } } } }, "404": { "description": "Attribute not found" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Attributes" ], "summary": "Update Attribute", "description": "Update existing attribute. Requires permission.", "operationId": "updateAttribute", "parameters": [ { "name": "id", "in": "path", "description": "Attribute ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Updated Size" }, "shop_id": { "type": "integer" }, "values": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Attribute updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attribute" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Attributes" ], "summary": "Delete Attribute", "description": "Delete an attribute. Requires permission.", "operationId": "deleteAttribute", "parameters": [ { "name": "id", "in": "path", "description": "Attribute ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Attribute deleted" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "sanctum": [] } ] } }, "/authors": { "get": { "tags": [ "Authors" ], "summary": "List all authors", "description": "Retrieve a paginated list of authors with product counts.", "operationId": "listAuthors", "parameters": [ { "name": "language", "in": "query", "description": "Language code", "required": false, "schema": { "type": "string", "default": "en", "example": "en" } }, { "name": "limit", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "example": 15 } } ], "responses": { "200": { "description": "Authors retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAuthors" } } } } } }, "post": { "tags": [ "Authors" ], "summary": "Create a new author", "description": "Create a new author. Requires active permissions for the associated shop.", "operationId": "createAuthor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "language" ], "properties": { "name": { "type": "string", "example": "George RR Martin" }, "language": { "type": "string", "example": "en" }, "bio": { "type": "string" }, "quote": { "type": "string" }, "born": { "type": "string", "format": "date" }, "death": { "type": "string", "format": "date" }, "languages": { "type": "string" }, "socials": { "type": "array", "items": { "type": "object" } }, "image": { "type": "object" }, "cover_image": { "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Author created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Author" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/authors/{slug}": { "get": { "tags": [ "Authors" ], "summary": "Get a single author", "description": "Retrieve detailed author information by slug or ID.", "operationId": "getAuthor", "parameters": [ { "name": "slug", "in": "path", "description": "Author slug or ID", "required": true, "schema": { "type": "string", "example": "leo-tolstoy" } }, { "name": "language", "in": "query", "description": "Language code", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Author retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Author" } } } }, "404": { "description": "Author not found" } } } }, "/authors/{id}": { "put": { "tags": [ "Authors" ], "summary": "Update an author", "description": "Update author details. Requires permissions for the associated shop.", "operationId": "updateAuthor", "parameters": [ { "name": "id", "in": "path", "description": "Author ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Author" } } } }, "responses": { "200": { "description": "Author updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Author" } } } }, "404": { "description": "Author not found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Authors" ], "summary": "Delete an author", "description": "Delete an author. Requires SUPER_ADMIN permissions.", "operationId": "deleteAuthor", "parameters": [ { "name": "id", "in": "path", "description": "Author ID to delete", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Author deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Author" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Author not found" } }, "security": [ { "sanctum": [] } ] } }, "/top-authors": { "get": { "tags": [ "Authors" ], "summary": "Get top authors", "description": "Retrieve list of authors with the most products.", "operationId": "getTopAuthors", "parameters": [ { "name": "language", "in": "query", "description": "Language code", "required": false, "schema": { "type": "string", "default": "en", "example": "en" } }, { "name": "limit", "in": "query", "description": "Number of results", "required": false, "schema": { "type": "integer", "default": 10, "example": 10 } } ], "responses": { "200": { "description": "Top authors retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Author" } } } } } } } }, "/became-seller": { "get": { "tags": [ "BecameSeller" ], "summary": "Get information for becoming a seller", "description": "Retrieve static content and commission options for the 'Become a Seller' landing page.", "operationId": "getBecameSellerData", "parameters": [ { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BecameSeller" } } } } } } }, "/categories": { "get": { "tags": [ "Categories" ], "summary": "List all categories", "description": "Retrieve a paginated list of categories with optional filtering. Returns categories with their type, parent, children relationships and products count.", "operationId": "listCategories", "parameters": [ { "name": "limit", "in": "query", "description": "Number of categories per page", "required": false, "schema": { "type": "integer", "default": 15, "example": 15 } }, { "name": "language", "in": "query", "description": "Language code for translations", "required": false, "schema": { "type": "string", "default": "en", "example": "en" } }, { "name": "parent", "in": "query", "description": "Filter by parent category. Use 'null' to get only root categories.", "required": false, "schema": { "type": "string", "example": "null" } }, { "name": "self", "in": "query", "description": "Exclude category by ID (useful when editing to exclude self from parent dropdown)", "required": false, "schema": { "type": "integer", "example": 3 } } ], "responses": { "200": { "description": "Categories retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCategories" } } } } } }, "post": { "tags": [ "Categories" ], "summary": "Create a new category", "description": "Create a new product category. Requires admin permissions.", "operationId": "createCategory", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255, "example": "Accessories" }, "slug": { "type": "string", "example": "accessories" }, "icon": { "type": "string", "example": "Accessories" }, "details": { "type": "string", "example": "Browse our wide range of accessories." }, "parent": { "description": "Parent category ID for nested categories", "type": "integer", "example": null, "nullable": true }, "type_id": { "type": "integer", "example": 1 }, "image": { "type": "array", "items": { "type": "object" } }, "banner_image": { "type": "array", "items": { "type": "object" } }, "language": { "type": "string", "example": "en" } }, "type": "object" } } } }, "responses": { "201": { "description": "Category created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/categories/{slug}": { "get": { "tags": [ "Categories" ], "summary": "Get a single category", "description": "Retrieve detailed category information by slug or ID. Includes type, parent category, and children.", "operationId": "getCategory", "parameters": [ { "name": "slug", "in": "path", "description": "Category slug or ID", "required": true, "schema": { "type": "string", "example": "men" } }, { "name": "language", "in": "query", "description": "Language code for translations", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Category retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "404": { "description": "Category not found" } } } }, "/categories/{id}": { "put": { "tags": [ "Categories" ], "summary": "Update a category", "description": "Update an existing category. Requires admin permissions.", "operationId": "updateCategory", "parameters": [ { "name": "id", "in": "path", "description": "Category ID", "required": true, "schema": { "type": "integer", "example": 3 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Men's Fashion" }, "details": { "type": "string", "example": "Updated description for men's fashion category." }, "icon": { "type": "string" }, "parent": { "type": "integer", "nullable": true }, "image": { "type": "array", "items": { "type": "object" } }, "banner_image": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Category updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Category not found" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Categories" ], "summary": "Delete a category", "description": "Delete a category. Requires admin permissions. Note: Deleting a parent category may affect child categories.", "operationId": "deleteCategory", "parameters": [ { "name": "id", "in": "path", "description": "Category ID to delete", "required": true, "schema": { "type": "integer", "example": 3 } } ], "responses": { "200": { "description": "Category deleted successfully", "content": { "application/json": { "schema": { "type": "boolean" }, "example": true } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Category not found" } }, "security": [ { "sanctum": [] } ] } }, "/featured-categories": { "get": { "tags": [ "Categories" ], "summary": "Get featured categories", "description": "Retrieve featured categories with their top products. Returns 3 categories by default. ChawkBazar specific endpoint.", "operationId": "getFeaturedCategories", "responses": { "200": { "description": "Featured categories retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CategorySummary" }, { "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } } }, "type": "object" } ] } } } } } } } }, "/orders/checkout/verify": { "post": { "tags": [ "Checkout" ], "summary": "Verify checkout data", "description": "Validates a cart's contents, applies taxes, and calculates shipping fees. This is typically the first step in the checkout process for both guests and customers.", "operationId": "verifyCheckout", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "amount", "products" ], "properties": { "amount": { "description": "Total cart amount before tax/shipping", "type": "number", "format": "float", "example": 100 }, "products": { "type": "array", "items": { "properties": { "product_id": { "type": "integer", "example": 1 }, "variation_option_id": { "type": "integer", "example": 5, "nullable": true }, "unit_price": { "type": "number", "format": "float", "example": 50 }, "order_quantity": { "type": "integer", "example": 2 } }, "type": "object" } }, "billing_address": { "description": "Billing address details (optional for verification index)", "type": "object" }, "shipping_address": { "description": "Shipping address details (optional for verification index)", "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Checkout validation results", "content": { "application/json": { "schema": { "properties": { "total_tax": { "type": "number", "format": "float", "example": 5 }, "shipping_charge": { "type": "number", "format": "float", "example": 10 }, "available_wallet_points": { "type": "number", "example": 0 }, "unavailable_products": { "type": "array", "items": { "type": "integer" } } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "500": { "description": "Something went wrong" } } } }, "/cms-pages": { "get": { "tags": [ "CMS Pages" ], "summary": "List all CMS pages", "description": "Retrieve a paginated list of CMS pages like Privacy Policy, Terms, etc.", "operationId": "listCmsPages", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "CMS pages retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCmsPages" } } } } } }, "post": { "tags": [ "CMS Pages" ], "summary": "Create a new CMS page", "description": "Create a new CMS page. Requires EDITOR or SUPER_ADMIN permissions.", "operationId": "createCmsPage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "slug" ], "properties": { "title": { "type": "string", "example": "Privacy Policy" }, "slug": { "type": "string", "example": "privacy-policy" }, "content": { "type": "array", "items": { "type": "object" } }, "meta": { "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "CMS page created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CmsPage" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/cms-pages/{slug}": { "get": { "tags": [ "CMS Pages" ], "summary": "Get a CMS page by slug", "description": "Retrieve detailed CMS page information by slug.", "operationId": "getCmsPageBySlug", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "example": "privacy-policy" } } ], "responses": { "200": { "description": "CMS page retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CmsPage" } } } }, "404": { "description": "Page not found" } } } }, "/api/puck/page": { "get": { "tags": [ "Puck Pages" ], "summary": "Get page by path", "description": "Fetches a page by its URL path for Puck frontend rendering", "operationId": "getPageByPath", "parameters": [ { "name": "path", "in": "query", "description": "URL path of the page (e.g., '/', '/about')", "required": false, "schema": { "type": "string", "default": "/", "example": "/" } } ], "responses": { "200": { "description": "Page found successfully", "content": { "application/json": { "schema": { "properties": { "path": { "type": "string", "example": "/" }, "data": { "properties": { "root": { "type": "object" }, "content": { "type": "array", "items": { "type": "object" } }, "zones": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Page not found", "content": { "application/json": { "schema": { "properties": { "data": { "type": "null" } }, "type": "object" } } } } } }, "post": { "tags": [ "Puck Pages" ], "summary": "Create or update page (upsert)", "description": "Creates a new page or updates existing one by path. Requires EDITOR or SUPER_ADMIN permissions.", "operationId": "savePuckPage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "path", "title" ], "properties": { "path": { "description": "URL path for the page", "type": "string", "example": "/" }, "title": { "description": "Page title", "type": "string", "example": "Homepage" }, "slug": { "description": "URL slug (auto-generated if not provided)", "type": "string", "nullable": true }, "data": { "description": "Puck editor data structure", "properties": { "root": { "properties": { "props": { "type": "object" } }, "type": "object" }, "content": { "type": "array", "items": { "properties": { "type": { "type": "string", "example": "HeroSlider" }, "props": { "type": "object" } }, "type": "object" } }, "zones": { "type": "object" } }, "type": "object" }, "meta": { "description": "SEO and other metadata", "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Page saved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "path": { "type": "string", "example": "/" }, "data": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - insufficient permissions" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/cms-pages/{id}": { "put": { "tags": [ "CMS Pages" ], "summary": "Update a CMS page", "description": "Update CMS page details. Requires EDITOR or SUPER_ADMIN permissions.", "operationId": "updateCmsPage", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CmsPage" } } } }, "responses": { "200": { "description": "CMS page updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CmsPage" } } } }, "404": { "description": "Page not found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "CMS Pages" ], "summary": "Delete a CMS page", "description": "Delete a CMS page. Requires EDITOR or SUPER_ADMIN permissions.", "operationId": "deleteCmsPage", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "CMS page deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "Page not found" } }, "security": [ { "sanctum": [] } ] } }, "/api/component-data/flash-sale-products": { "get": { "tags": [ "Component Data" ], "summary": "Get flash sale products", "description": "Returns currently active flash sale with its products. Used by ProductFlashSaleBlock component.", "operationId": "getFlashSaleProducts", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of products to return", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 1 } }, { "name": "language", "in": "query", "description": "Language code for filtering", "required": false, "schema": { "type": "string", "example": "en" } } ], "responses": { "200": { "description": "Flash sale data retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "flash_sale": { "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "slug": { "type": "string" }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time" }, "rate": { "type": "number" } }, "type": "object" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/component-data/categories": { "get": { "tags": [ "Component Data" ], "summary": "Get categories", "description": "Returns categories for CategoryBlock component display.", "operationId": "getCategories", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 10 } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "top_level", "in": "query", "description": "Only return top-level categories (no parent)", "required": false, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Categories retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "icon": { "type": "string", "nullable": true }, "image": { "type": "object", "nullable": true } }, "type": "object" } } }, "type": "object" } } } } } } }, "/api/component-data/collections": { "get": { "tags": [ "Component Data" ], "summary": "Get collections (types)", "description": "Returns collections/types for CollectionBlock component.", "operationId": "getCollections", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 10 } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Collections retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } } } } }, "/api/component-data/popular-products": { "get": { "tags": [ "Component Data" ], "summary": "Get popular products", "description": "Returns products sorted by order count (popularity).", "operationId": "getPopularProducts", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 10 } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Popular products retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } } }, "type": "object" } } } } } } }, "/api/component-data/best-selling-products": { "get": { "tags": [ "Component Data" ], "summary": "Get best selling products", "description": "Returns products sorted by sold quantity.", "operationId": "getBestSellingProducts", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 10 } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Best selling products retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } } }, "type": "object" } } } } } } }, "/conversations": { "get": { "tags": [ "Conversations" ], "summary": "List Conversations", "description": "Get a paginated list of conversations for the current user (as customer or shop owner/staff).", "operationId": "getConversations", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Conversations retrieved", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "total": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/conversations/{id}": { "get": { "tags": [ "Conversations" ], "summary": "Get Conversation Details", "description": "Retrieve details and messages of a single conversation.", "operationId": "getConversation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Conversation retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Conversation not found" } }, "security": [ { "sanctum": [] } ] } }, "/coupons": { "get": { "tags": [ "Coupons" ], "summary": "List all coupons", "description": "Retrieve a paginated list of coupons with optional shop and language filtering.", "operationId": "getCoupons", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 15 } }, { "name": "shop_id", "in": "query", "schema": { "type": "integer" } }, { "name": "language", "in": "query", "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "List of coupons", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Coupon" } }, "current_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } } } } } }, "post": { "tags": [ "Coupons" ], "summary": "Create new coupon", "description": "Create a new coupon for a shop. Accessible by Store Owners and Super Admins.", "operationId": "storeCoupon", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "type", "amount", "shop_id" ], "properties": { "code": { "type": "string", "example": "SUMMER24" }, "type": { "type": "string", "enum": [ "percentage", "fixed", "free_shipping" ] }, "amount": { "type": "number", "example": 20 }, "shop_id": { "type": "integer", "example": 1 }, "minimum_cart_amount": { "type": "number", "example": 100 }, "active_from": { "type": "string", "format": "date-time" }, "expire_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "responses": { "201": { "description": "Coupon created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/coupons/{slug_or_id}": { "get": { "tags": [ "Coupons" ], "summary": "Get single coupon", "description": "Retrieve details of a coupon by its code/slug or incremental ID.", "operationId": "getCouponBySlugOrId", "parameters": [ { "name": "slug_or_id", "in": "path", "description": "Coupon code or ID", "required": true, "schema": { "type": "string" } }, { "name": "language", "in": "query", "description": "Language code", "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Coupon found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } }, "404": { "description": "Coupon not found" } } } }, "/coupons/verify": { "post": { "tags": [ "Coupons" ], "summary": "Verify coupon code", "description": "Check if a coupon code is valid for the current sub_total.", "operationId": "verifyCoupon", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "sub_total" ], "properties": { "code": { "type": "string", "example": "SUMMER24" }, "sub_total": { "type": "number", "example": 100 } }, "type": "object" } } } }, "responses": { "200": { "description": "Coupon verification result" }, "404": { "description": "Coupon not found or invalid" } } } }, "/coupons/{id}": { "put": { "tags": [ "Coupons" ], "summary": "Update coupon", "description": "Update details of an existing coupon. Accessible by Staff, Owners, or Admins.", "operationId": "updateCoupon", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "description": { "type": "string" }, "amount": { "type": "number" }, "expire_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "responses": { "200": { "description": "Coupon updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } }, "404": { "description": "Coupon not found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Coupons" ], "summary": "Delete coupon", "operationId": "deleteCoupon", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Coupon deleted successfully" }, "404": { "description": "Coupon not found" } }, "security": [ { "sanctum": [] } ] } }, "/approve-coupon": { "post": { "tags": [ "Content Moderation" ], "summary": "Approve Vendor Coupon", "description": "Approve a vendor-created coupon for public use. Requires SUPER_ADMIN permission.", "operationId": "approveCoupon", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id" ], "properties": { "id": { "description": "Coupon ID to approve", "type": "integer", "example": 5 } }, "type": "object" } } } }, "responses": { "200": { "description": "Coupon approved successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "404": { "description": "Coupon not found" } }, "security": [ { "sanctum": [] } ] } }, "/disapprove-coupon": { "post": { "tags": [ "Content Moderation" ], "summary": "Disapprove Vendor Coupon", "description": "Reject/disapprove a vendor coupon. Requires SUPER_ADMIN permission.", "operationId": "disapproveCoupon", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id" ], "properties": { "id": { "description": "Coupon ID to disapprove", "type": "integer", "example": 5 } }, "type": "object" } } } }, "responses": { "200": { "description": "Coupon disapproved successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "404": { "description": "Coupon not found" } }, "security": [ { "sanctum": [] } ] } }, "/faqs": { "get": { "tags": [ "FAQs" ], "summary": "List all FAQs", "description": "Retrieve a paginated list of FAQs. Filterable by shop_id and language.", "operationId": "getFaqs", "parameters": [ { "name": "limit", "in": "query", "description": "Number of items per page", "schema": { "type": "integer", "default": 10 } }, { "name": "shop_id", "in": "query", "description": "Filter FAQs by Shop ID", "schema": { "type": "integer" } }, { "name": "language", "in": "query", "description": "Filter by language code", "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "List of FAQs retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Faq" } }, "current_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } } } } } }, "post": { "tags": [ "FAQs" ], "summary": "Create a new FAQ", "description": "Add a new FAQ. Accessible by Staff for their shop, Store Owners, and Super Admins.", "operationId": "storeFaq", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "faq_title", "faq_description" ], "properties": { "faq_title": { "type": "string", "example": "How to return a product?" }, "faq_description": { "type": "string", "example": "You can return any product within 30 days..." }, "shop_id": { "type": "integer", "example": 1 }, "language": { "type": "string", "example": "en" } }, "type": "object" } } } }, "responses": { "201": { "description": "FAQ created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Faq" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/faqs/{id}": { "get": { "tags": [ "FAQs" ], "summary": "Get single FAQ", "description": "Retrieve details of a specific FAQ by ID.", "operationId": "getFaqById", "parameters": [ { "name": "id", "in": "path", "description": "FAQ ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "FAQ found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Faq" } } } }, "404": { "description": "FAQ not found" } } }, "put": { "tags": [ "FAQs" ], "summary": "Update FAQ", "description": "Update details of an existing FAQ. Accessible by staff of the shop, Store Owners, or Super Admins.", "operationId": "updateFaq", "parameters": [ { "name": "id", "in": "path", "description": "FAQ ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "faq_title": { "type": "string" }, "faq_description": { "type": "string" }, "language": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "FAQ updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Faq" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "FAQ not found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "FAQs" ], "summary": "Delete FAQ", "description": "Remove an FAQ from the system. Accessible by authorized Staff, Owners or Admins.", "operationId": "deleteFaq", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "FAQ deleted successfully" }, "404": { "description": "FAQ not found" } }, "security": [ { "sanctum": [] } ] } }, "/flash-sale": { "get": { "tags": [ "Flash Sales" ], "summary": "List Flash Sales", "description": "Retrieve a paginated list of flash sales.", "operationId": "getFlashSales", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 10 } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "default": "en" } }, { "name": "request_from", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "vendor" ] } } ], "responses": { "200": { "description": "Flash sales retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FlashSale" } }, "total": { "type": "integer" } }, "type": "object" } } } } } } }, "/flash-sale/{slug}": { "get": { "tags": [ "Flash Sales" ], "summary": "Get Single Flash Sale", "description": "Retrieve details of a flash sale by its slug.", "operationId": "getFlashSaleBySlug", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Flash sale details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlashSale" } } } }, "404": { "description": "Flash sale not found" } } } }, "/approve-flash-sale-requested-products": { "post": { "tags": [ "Content Moderation" ], "summary": "Approve Flash Sale Request", "description": "Approve a vendor's flash sale product request. Requires SUPER_ADMIN permission.", "operationId": "approveFlashSaleProducts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id" ], "properties": { "id": { "description": "Flash sale request ID to approve", "type": "integer", "example": 5 } }, "type": "object" } } } }, "responses": { "200": { "description": "Flash sale request approved" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" } }, "security": [ { "sanctum": [] } ] } }, "/disapprove-flash-sale-requested-products": { "post": { "tags": [ "Content Moderation" ], "summary": "Disapprove Flash Sale Request", "description": "Reject a vendor's flash sale product request. Requires SUPER_ADMIN permission.", "operationId": "disapproveFlashSaleProducts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id" ], "properties": { "id": { "description": "Flash sale request ID to reject", "type": "integer", "example": 5 } }, "type": "object" } } } }, "responses": { "200": { "description": "Flash sale request rejected" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" } }, "security": [ { "sanctum": [] } ] } }, "/manufacturers": { "get": { "tags": [ "Manufacturers" ], "summary": "List all manufacturers", "description": "Retrieve a paginated list of manufacturers/brands.", "operationId": "listManufacturers", "parameters": [ { "name": "language", "in": "query", "description": "Language code", "required": false, "schema": { "type": "string", "default": "en", "example": "en" } }, { "name": "limit", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "example": 15 } } ], "responses": { "200": { "description": "Manufacturers retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedManufacturers" } } } } } }, "post": { "tags": [ "Manufacturers" ], "summary": "Create a new manufacturer", "description": "Create a new manufacturer. Requires permissions for the associated shop.", "operationId": "createManufacturer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "type_id" ], "properties": { "name": { "type": "string", "example": "Apple" }, "type_id": { "type": "integer", "example": 1 }, "description": { "type": "string" }, "website": { "type": "string", "format": "url" }, "socials": { "type": "array", "items": { "type": "object" } }, "image": { "type": "object" }, "cover_image": { "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Manufacturer created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Manufacturer" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/manufacturers/{slug}": { "get": { "tags": [ "Manufacturers" ], "summary": "Get a single manufacturer", "description": "Retrieve detailed manufacturer information by slug or ID.", "operationId": "getManufacturer", "parameters": [ { "name": "slug", "in": "path", "description": "Manufacturer slug or ID", "required": true, "schema": { "type": "string", "example": "apple" } }, { "name": "language", "in": "query", "description": "Language code", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Manufacturer retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Manufacturer" } } } }, "404": { "description": "Manufacturer not found" } } } }, "/manufacturers/{id}": { "put": { "tags": [ "Manufacturers" ], "summary": "Update a manufacturer", "description": "Update manufacturer details. Requires permissions for the associated shop.", "operationId": "updateManufacturer", "parameters": [ { "name": "id", "in": "path", "description": "Manufacturer ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Manufacturer" } } } }, "responses": { "200": { "description": "Manufacturer updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Manufacturer" } } } }, "404": { "description": "Manufacturer not found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Manufacturers" ], "summary": "Delete a manufacturer", "description": "Delete a manufacturer. Requires shop permissions.", "operationId": "deleteManufacturer", "parameters": [ { "name": "id", "in": "path", "description": "Manufacturer ID to delete", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Manufacturer deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Manufacturer" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Manufacturer not found" } }, "security": [ { "sanctum": [] } ] } }, "/top-manufacturers": { "get": { "tags": [ "Manufacturers" ], "summary": "Get top manufacturers", "description": "Retrieve list of manufacturers with the most products.", "operationId": "getTopManufacturers", "parameters": [ { "name": "language", "in": "query", "description": "Language code", "required": false, "schema": { "type": "string", "default": "en", "example": "en" } }, { "name": "limit", "in": "query", "description": "Number of results", "required": false, "schema": { "type": "integer", "default": 10, "example": 10 } } ], "responses": { "200": { "description": "Top manufacturers retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Manufacturer" } } } } } } } }, "/meem-products": { "get": { "tags": [ "Meem Products" ], "summary": "List all Meem products", "description": "Retrieve a paginated list of Meem products.", "operationId": "getMeemProducts", "parameters": [ { "name": "limit", "in": "query", "description": "Number of products per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1, "example": 15 } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1, "example": 1 } } ], "responses": { "200": { "description": "Meem products retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedMeemProducts" } } } } } }, "post": { "tags": [ "Meem Products" ], "summary": "Create a new Meem product", "description": "Create a new Meem product. Requires SUPER_ADMIN permissions.", "operationId": "createMeemProduct", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255, "example": "Meem Premium Plan" }, "category": { "type": "string", "maxLength": 255, "example": "Insurance", "nullable": true }, "description": { "type": "string", "example": "Comprehensive coverage plan.", "nullable": true }, "image_url": { "type": "string", "format": "url", "example": "https://example.com/images/product.jpg", "nullable": true }, "price": { "type": "number", "format": "float", "example": 199.99, "nullable": true }, "url": { "type": "string", "format": "url", "example": "https://meem.com/products/premium-plan", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Meem product created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeemProduct" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - insufficient permissions" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } }, "security": [ { "sanctum": [] } ] } }, "/meem-products/{id}": { "get": { "tags": [ "Meem Products" ], "summary": "Get a single Meem product", "description": "Retrieve a Meem product by its ID.", "operationId": "getMeemProduct", "parameters": [ { "name": "id", "in": "path", "description": "Meem product ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Meem product retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeemProduct" } } } }, "404": { "description": "Meem product not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "MARVEL_ERROR.NOT_FOUND" } }, "type": "object" } } } } } }, "put": { "tags": [ "Meem Products" ], "summary": "Update a Meem product", "description": "Update an existing Meem product. Requires SUPER_ADMIN permissions.", "operationId": "updateMeemProduct", "parameters": [ { "name": "id", "in": "path", "description": "Meem product ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 255, "example": "Updated Meem Plan" }, "category": { "type": "string", "maxLength": 255, "example": "Health Insurance", "nullable": true }, "description": { "type": "string", "example": "Updated plan description.", "nullable": true }, "image_url": { "type": "string", "format": "url", "example": "https://example.com/images/updated.jpg", "nullable": true }, "price": { "type": "number", "format": "float", "example": 249.99, "nullable": true }, "url": { "type": "string", "format": "url", "example": "https://meem.com/products/updated-plan", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Meem product updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeemProduct" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - insufficient permissions" }, "404": { "description": "Meem product not found" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Meem Products" ], "summary": "Delete a Meem product", "description": "Delete a Meem product. Requires SUPER_ADMIN permissions.", "operationId": "deleteMeemProduct", "parameters": [ { "name": "id", "in": "path", "description": "Meem product ID to delete", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Meem product deleted successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - insufficient permissions" }, "404": { "description": "Meem product not found" } }, "security": [ { "sanctum": [] } ] } }, "/messages/{conversation_id}": { "get": { "tags": [ "Messages" ], "summary": "List Messages", "description": "Get a paginated list of messages for a specific conversation.", "operationId": "getMessages", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Messages retrieved", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "total": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - not a participant" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Messages" ], "summary": "Send Message", "description": "Send a new message in a conversation.", "operationId": "sendMessage", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Hello!" }, "type": { "type": "string", "enum": [ "shop", "user" ], "example": "user" } }, "type": "object" } } } }, "responses": { "201": { "description": "Message sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "sanctum": [] } ] } }, "/messages/seen": { "post": { "tags": [ "Messages" ], "summary": "Mark Messages as Seen", "description": "Mark all messages in a conversation as read for the current user.", "operationId": "seenMessage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "conversation_id" ], "properties": { "conversation_id": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Messages marked as read" }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/orders": { "get": { "tags": [ "Orders" ], "summary": "List all orders", "description": "Retrieve a paginated list of orders. Customers see their own orders. Store Owners/Staff see orders for their shop. Super Admins see all.", "operationId": "getOrders", "parameters": [ { "name": "limit", "in": "query", "description": "Number of orders per page", "required": false, "schema": { "type": "integer", "default": 10, "example": 15 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "example": 1 } }, { "name": "shop_id", "in": "query", "description": "Filter by Shop ID (for Store Owners/Staff)", "required": false, "schema": { "type": "integer", "example": 2 } }, { "name": "tracking_number", "in": "query", "description": "Search by tracking number", "required": false, "schema": { "type": "string", "example": "ORD-123" } } ], "responses": { "200": { "description": "Orders retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOrders" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Orders" ], "summary": "Create a new order", "description": "Create specific order with products. Primarily for customers.", "operationId": "createOrder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "products", "amount", "total", "paid_total", "payment_gateway" ], "properties": { "customer_id": { "type": "integer", "example": 1 }, "products": { "type": "array", "items": { "properties": { "product_id": { "type": "integer", "example": 1 }, "order_quantity": { "type": "integer", "example": 2 }, "unit_price": { "type": "number", "format": "float", "example": 50 }, "subtotal": { "type": "number", "format": "float", "example": 100 } }, "type": "object" } }, "amount": { "type": "number", "format": "float", "example": 100 }, "sales_tax": { "type": "number", "format": "float", "example": 5 }, "delivery_fee": { "type": "number", "format": "float", "example": 10 }, "total": { "type": "number", "format": "float", "example": 115 }, "paid_total": { "type": "number", "format": "float", "example": 115 }, "payment_gateway": { "type": "string", "enum": [ "CASH_ON_DELIVERY", "STRIPE", "PAYPAL" ], "example": "CASH_ON_DELIVERY" }, "billing_address": { "type": "object" }, "shipping_address": { "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Order created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/orders/{id}": { "get": { "tags": [ "Orders" ], "summary": "Get a single order", "description": "Retrieve order details by ID or Tracking Number. Access restricted to the Customer who owns it, or Store Owner/Staff of the shop.", "operationId": "getOrder", "parameters": [ { "name": "id", "in": "path", "description": "Order ID or Tracking Number", "required": true, "schema": { "type": "string", "example": "1" } } ], "responses": { "200": { "description": "Order details retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - not authorized to view this order" }, "404": { "description": "Order not found" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Orders" ], "summary": "Update order status", "description": "Update the status of an order. Requires STORE_OWNER or STAFF permission for the related shop.", "operationId": "updateOrder", "parameters": [ { "name": "id", "in": "path", "description": "Order ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "order-pending", "order-processing", "order-completed", "order-cancelled", "order-failed", "order-at-local-facility", "order-out-for-delivery" ], "example": "order-processing" } }, "type": "object" } } } }, "responses": { "200": { "description": "Order updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Order not found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Orders" ], "summary": "Delete an order", "description": "Delete an order. Requires SUPER_ADMIN permission.", "operationId": "deleteOrder", "parameters": [ { "name": "id", "in": "path", "description": "Order ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Order deleted successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Order not found" } }, "security": [ { "sanctum": [] } ] } }, "/orders/tracking-number/{tracking_number}": { "get": { "tags": [ "Orders" ], "summary": "Track order by tracking number", "description": "Retrieve order details using tracking number. Publicly accessible for valid tracking numbers.", "operationId": "getOrderByTracking", "parameters": [ { "name": "tracking_number", "in": "path", "description": "Order tracking number", "required": true, "schema": { "type": "string", "example": "ORD-123456" } } ], "responses": { "200": { "description": "Order details retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "description": "Order not found" } } } }, "/orders/payment": { "post": { "tags": [ "Orders" ], "summary": "Submit order payment", "description": "Process payment for an existing order", "operationId": "submitOrderPayment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "tracking_number" ], "properties": { "tracking_number": { "type": "string", "example": "ORD-123456" }, "nonce": { "description": "Payment nonce/token from gateway", "type": "string" }, "token": { "description": "Payment token", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment processed successfully" }, "400": { "description": "Payment failed" }, "404": { "description": "Order not found" } }, "security": [ { "sanctum": [] } ] } }, "/products": { "get": { "tags": [ "Products" ], "summary": "List all products", "description": "Retrieve a paginated list of products with optional filtering by category, shop, type, price range, and more.", "operationId": "getProducts", "parameters": [ { "name": "limit", "in": "query", "description": "Number of products per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1, "example": 15 } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1, "example": 1 } }, { "name": "language", "in": "query", "description": "Language code for product translations", "required": false, "schema": { "type": "string", "default": "en", "example": "en" } }, { "name": "search", "in": "query", "description": "Search term to filter products by name or description", "required": false, "schema": { "type": "string", "example": "shirt" } }, { "name": "shop_id", "in": "query", "description": "Filter by shop ID", "required": false, "schema": { "type": "integer", "example": 2 } }, { "name": "type_id", "in": "query", "description": "Filter by type/collection ID", "required": false, "schema": { "type": "integer", "example": 13 } }, { "name": "category", "in": "query", "description": "Filter by category slug", "required": false, "schema": { "type": "string", "example": "men" } }, { "name": "min_price", "in": "query", "description": "Minimum price filter", "required": false, "schema": { "type": "number", "format": "float", "example": 20 } }, { "name": "max_price", "in": "query", "description": "Maximum price filter", "required": false, "schema": { "type": "number", "format": "float", "example": 500 } }, { "name": "status", "in": "query", "description": "Filter by product status", "required": false, "schema": { "type": "string", "enum": [ "publish", "draft", "approved", "rejected", "under_review" ], "example": "publish" } }, { "name": "orderBy", "in": "query", "description": "Field to order by", "required": false, "schema": { "type": "string", "enum": [ "created_at", "name", "price", "min_price", "max_price" ], "example": "created_at" } }, { "name": "sortedBy", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ], "example": "desc" } } ], "responses": { "200": { "description": "Products retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedProducts" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } }, "post": { "tags": [ "Products" ], "summary": "Create a new product", "description": "Create a new product. Requires STAFF or STORE_OWNER permissions.", "operationId": "createProduct", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "type_id", "shop_id", "product_type", "unit" ], "properties": { "name": { "type": "string", "maxLength": 255, "example": "Dido Pilot Glass" }, "slug": { "type": "string", "example": "dido-pilot-glass", "nullable": true }, "description": { "type": "string", "maxLength": 10000, "example": "Polarized sunglasses reduce glare reflected off of roads, bodies of water, snow and other horizontal surfaces." }, "type_id": { "type": "integer", "example": 15 }, "shop_id": { "type": "integer", "example": 2 }, "price": { "type": "number", "format": "float", "example": 350, "nullable": true }, "sale_price": { "description": "Must be less than or equal to price", "type": "number", "format": "float", "example": 300, "nullable": true }, "quantity": { "type": "integer", "example": 500, "nullable": true }, "sku": { "type": "string", "example": "SKU-GLASS-001" }, "unit": { "type": "string", "example": "1 pc" }, "product_type": { "type": "string", "enum": [ "simple", "variable" ], "example": "simple" }, "status": { "type": "string", "enum": [ "draft", "publish", "approved", "rejected", "under_review", "unpublish" ], "example": "publish" }, "in_stock": { "type": "boolean", "example": true }, "is_taxable": { "type": "boolean", "example": false }, "is_digital": { "type": "boolean", "example": false }, "is_external": { "type": "boolean", "example": false }, "is_rental": { "type": "boolean", "example": false }, "height": { "type": "string", "nullable": true }, "width": { "type": "string", "nullable": true }, "length": { "type": "string", "nullable": true }, "external_product_url": { "type": "string", "nullable": true }, "external_product_button_text": { "type": "string", "nullable": true }, "categories": { "type": "array", "items": { "type": "integer" }, "example": [ 3, 6 ] }, "tags": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 2 ] }, "image": { "properties": { "id": { "type": "integer" }, "original": { "type": "string" }, "thumbnail": { "type": "string" } }, "type": "object" }, "gallery": { "type": "array", "items": { "type": "object" } }, "language": { "type": "string", "example": "en" } }, "type": "object" } } } }, "responses": { "201": { "description": "Product created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - insufficient permissions" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } }, "security": [ { "sanctum": [] } ] } }, "/products/{slug}": { "get": { "tags": [ "Products" ], "summary": "Get a single product", "description": "Retrieve detailed product information by slug or ID. Includes related products.", "operationId": "getProduct", "parameters": [ { "name": "slug", "in": "path", "description": "Product slug or ID", "required": true, "schema": { "type": "string", "example": "hoppister-tops" } }, { "name": "language", "in": "query", "description": "Language code for translations", "required": false, "schema": { "type": "string", "default": "en", "example": "en" } }, { "name": "with", "in": "query", "description": "Relationships to include (separated by semicolon)", "required": false, "schema": { "type": "string", "example": "categories;tags;shop;type" } } ], "responses": { "200": { "description": "Product retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "MARVEL_ERROR.NOT_FOUND" } }, "type": "object" } } } } } } }, "/products/{id}": { "put": { "tags": [ "Products" ], "summary": "Update a product", "description": "Update an existing product. Requires STAFF or STORE_OWNER permissions for the shop.", "operationId": "updateProduct", "parameters": [ { "name": "id", "in": "path", "description": "Product ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 255, "example": "Updated Hoppister Tops" }, "description": { "type": "string", "example": "Updated description for this product." }, "price": { "type": "number", "format": "float", "example": 399 }, "sale_price": { "type": "number", "format": "float", "example": 350 }, "quantity": { "type": "integer", "example": 1500 }, "status": { "type": "string", "enum": [ "draft", "publish" ], "example": "publish" }, "categories": { "type": "array", "items": { "type": "integer" }, "example": [ 3, 6 ] }, "tags": { "type": "array", "items": { "type": "integer" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Product updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - you don't have permission to update this product" }, "404": { "description": "Product not found" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Products" ], "summary": "Delete a product", "description": "Soft delete a product. Requires STAFF or STORE_OWNER permissions for the shop.", "operationId": "deleteProduct", "parameters": [ { "name": "id", "in": "path", "description": "Product ID to delete", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Product deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - you don't have permission to delete this product" }, "404": { "description": "Product not found" } }, "security": [ { "sanctum": [] } ] } }, "/best-selling-products": { "get": { "tags": [ "Products" ], "summary": "Get best selling products", "description": "Retrieve products sorted by total sold quantity. Useful for showcasing top performers.", "operationId": "fetchBestSellingProducts", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of products to return", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 1, "example": 10 } }, { "name": "language", "in": "query", "description": "Language code for product translations", "required": false, "schema": { "type": "string", "default": "en", "example": "en" } }, { "name": "type_slug", "in": "query", "description": "Filter by type/collection slug", "required": false, "schema": { "type": "string", "example": "clothing" } } ], "responses": { "200": { "description": "Best selling products retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } } } } } } } }, "/popular-products": { "get": { "tags": [ "Products" ], "summary": "Get popular products", "description": "Retrieve products sorted by order count (popularity). Supports filtering by shop, type, and date range.", "operationId": "fetchPopularProducts", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of products to return", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 1, "example": 10 } }, { "name": "language", "in": "query", "description": "Language code for product translations", "required": false, "schema": { "type": "string", "default": "en", "example": "en" } }, { "name": "shop_id", "in": "query", "description": "Filter by shop ID", "required": false, "schema": { "type": "integer", "example": 2 } }, { "name": "type_id", "in": "query", "description": "Filter by type/collection ID", "required": false, "schema": { "type": "integer", "example": 13 } }, { "name": "type_slug", "in": "query", "description": "Filter by type/collection slug (alternative to type_id)", "required": false, "schema": { "type": "string", "example": "clothing" } }, { "name": "range", "in": "query", "description": "Number of days to look back for popularity calculation", "required": false, "schema": { "type": "integer", "example": 30 } } ], "responses": { "200": { "description": "Popular products retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } } } } }, "404": { "description": "Type not found (if type_slug is provided but not found)" } } } }, "/products/calculate-rental-price": { "get": { "tags": [ "Products" ], "summary": "Calculate rental price for a product", "description": "Calculates the total rental price based on duration, quantity, and selected features. Also checks availability for the given date range.", "operationId": "calculateRentalPrice", "parameters": [ { "name": "product_id", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "variation_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "example": "2023-12-01" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "example": "2023-12-05" } }, { "name": "quantity", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "persons", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "dropoff_location_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "pickup_location_id", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Calculated rental price", "content": { "application/json": { "schema": { "properties": { "price": { "type": "number", "format": "float", "example": 150 }, "total": { "type": "number", "format": "float", "example": 150 } }, "type": "object" } } } }, "400": { "description": "Invalid product or date range" }, "404": { "description": "Product not found" } } } }, "/draft-products": { "get": { "tags": [ "Products" ], "summary": "List products in draft status", "description": "Returns a paginated list of drafted products belonging to the user's shop(s).", "operationId": "getDraftedProducts", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "shop_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Paginated list of drafted products", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "total": { "type": "integer" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/product-stock": { "get": { "tags": [ "Products" ], "summary": "List products with low stock", "description": "Returns a paginated list of products with inventory less than 10 belonging to the user's shop(s).", "operationId": "getProductStock", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "shop_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Paginated list of products with low stock", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "total": { "type": "integer" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/questions": { "get": { "tags": [ "Questions" ], "summary": "List Questions", "description": "List questions. Filter by product_id to see questions for a product.", "operationId": "getQuestions", "parameters": [ { "name": "product_id", "in": "query", "description": "Filter by Product ID", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "default": 15 } }, { "name": "page", "in": "query", "description": "Page number", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Questions retrieved", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Question" } }, "total": { "type": "integer" } }, "type": "object" } } } } } }, "post": { "tags": [ "Questions" ], "summary": "Ask a Question", "description": "Submit a question for a product. Requires CUSTOMER permission.", "operationId": "createQuestion", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "question", "product_id", "shop_id" ], "properties": { "question": { "type": "string", "example": "Is this waterproof?" }, "product_id": { "type": "integer", "example": 10 }, "shop_id": { "type": "integer", "example": 2 } }, "type": "object" } } } }, "responses": { "200": { "description": "Question submitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Question" } } } }, "401": { "description": "Unauthenticated" }, "400": { "description": "Limit exceeded" } }, "security": [ { "sanctum": [] } ] } }, "/questions/{id}": { "get": { "tags": [ "Questions" ], "summary": "Get Question Details", "description": "Get a single question details", "operationId": "getQuestion", "parameters": [ { "name": "id", "in": "path", "description": "Question ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Question details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Question" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Questions" ], "summary": "Answer a Question", "description": "Update question (usually to add an answer). Requires STORE_OWNER permission for the shop.", "operationId": "updateQuestion", "parameters": [ { "name": "id", "in": "path", "description": "Question ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "answer", "shop_id" ], "properties": { "answer": { "type": "string", "example": "Yes, it is waterproof." }, "shop_id": { "type": "integer", "example": 2 } }, "type": "object" } } } }, "responses": { "200": { "description": "Question updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Question" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Questions" ], "summary": "Delete a Question", "description": "Delete a question. Requires permission.", "operationId": "deleteQuestion", "parameters": [ { "name": "id", "in": "path", "description": "Question ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Question deleted" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "sanctum": [] } ] } }, "/my-questions": { "get": { "tags": [ "Questions" ], "summary": "My Questions", "description": "List questions asked by the authenticated user.", "operationId": "getMyQuestions", "parameters": [ { "name": "limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "default": 15 } }, { "name": "page", "in": "query", "description": "Page number", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "My questions retrieved", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Question" } }, "total": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/refunds": { "get": { "tags": [ "Refunds" ], "summary": "List Refund Requests", "description": "Retrieve a paginated list of refund requests. Customers see their own; Admin/Owners see relevant ones.", "operationId": "getRefunds", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "shop_id", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Refund requests retrieved", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Refund" } }, "total": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Refunds" ], "summary": "Create Refund Request", "description": "Submit a new refund request for an order. Requires CUSTOMER permission.", "operationId": "createRefund", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "description", "order_id", "amount" ], "properties": { "title": { "type": "string", "example": "Wrong item" }, "description": { "type": "string", "example": "I received a different item than ordered." }, "order_id": { "type": "integer", "example": 1 }, "amount": { "type": "number", "format": "float", "example": 25 }, "images": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Refund request submitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/refunds/{id}": { "get": { "tags": [ "Refunds" ], "summary": "Get Refund details", "description": "Retrieve details of a single refund request.", "operationId": "getRefund", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Refund details retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "404": { "description": "Refund not found" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Content Moderation" ], "summary": "Update Refund Status", "description": "Update a refund request status (approve, reject, processing). When approved, credits customer wallet and deducts from shop balance. Requires SUPER_ADMIN permission.", "operationId": "updateRefund", "parameters": [ { "name": "id", "in": "path", "description": "Refund ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "approved", "rejected", "processing", "pending" ], "example": "approved" } }, "type": "object" } } } }, "responses": { "200": { "description": "Refund updated successfully" }, "400": { "description": "Already refunded" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "404": { "description": "Refund not found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Content Moderation" ], "summary": "Delete Refund Request", "description": "Delete a refund request. Requires SUPER_ADMIN permission.", "operationId": "deleteRefund", "parameters": [ { "name": "id", "in": "path", "description": "Refund ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Refund deleted successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "404": { "description": "Refund not found" } }, "security": [ { "sanctum": [] } ] } }, "/refund-policies": { "get": { "tags": [ "Refund Policies" ], "summary": "List Refund Policies", "description": "Retrieve a paginated list of refund policies.", "operationId": "getRefundPolicies", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Refund policies retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RefundPolicy" } }, "total": { "type": "integer" } }, "type": "object" } } } } } } }, "/refund-policies/{slug}": { "get": { "tags": [ "Refund Policies" ], "summary": "Get Single Refund Policy", "description": "Retrieve details of a refund policy by its slug.", "operationId": "getRefundPolicyBySlug", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Refund policy details retrieved successfuly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundPolicy" } } } }, "404": { "description": "Refund policy not found" } } } }, "/refund-reasons": { "get": { "tags": [ "Refund Reasons" ], "summary": "List Refund Reasons", "description": "Retrieve a paginated list of refund reasons.", "operationId": "getRefundReasons", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Refund reasons retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RefundReason" } }, "total": { "type": "integer" } }, "type": "object" } } } } } } }, "/refund-reasons/{id_or_slug}": { "get": { "tags": [ "Refund Reasons" ], "summary": "Get Single Refund Reason", "description": "Retrieve details of a refund reason by its ID or slug.", "operationId": "getRefundReason", "parameters": [ { "name": "id_or_slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Refund reason details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundReason" } } } }, "404": { "description": "Refund reason not found" } } } }, "/reviews": { "get": { "tags": [ "Reviews" ], "summary": "List Reviews", "description": "List reviews for a product.", "operationId": "getReviews", "parameters": [ { "name": "product_id", "in": "query", "description": "Filter by Product ID", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "default": 15 } }, { "name": "page", "in": "query", "description": "Page number", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Reviews retrieved", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } }, "total": { "type": "integer" } }, "type": "object" } } } } } }, "post": { "tags": [ "Reviews" ], "summary": "Create Review", "description": "Submit a review for a product. Requires CUSTOMER permission.", "operationId": "createReview", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "rating", "product_id", "shop_id", "order_id" ], "properties": { "rating": { "type": "integer", "example": 5 }, "comment": { "type": "string", "example": "Great!" }, "product_id": { "type": "integer", "example": 10 }, "shop_id": { "type": "integer", "example": 2 }, "order_id": { "type": "integer", "example": 100 }, "photos": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Review created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Review" } } } }, "401": { "description": "Unauthenticated" }, "400": { "description": "Bad Request or Already Reviewed" } }, "security": [ { "sanctum": [] } ] } }, "/reviews/{id}": { "get": { "tags": [ "Reviews" ], "summary": "Get Review Details", "description": "Get a singel review details", "operationId": "getReview", "parameters": [ { "name": "id", "in": "path", "description": "Review ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Review details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Review" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Reviews" ], "summary": "Update Review", "description": "Update a review. Requires permission.", "operationId": "updateReview", "parameters": [ { "name": "id", "in": "path", "description": "Review ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "rating": { "type": "integer" }, "comment": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Review updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Review" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Reviews" ], "summary": "Delete Review", "description": "Delete a review. Requires permission.", "operationId": "deleteReview", "parameters": [ { "name": "id", "in": "path", "description": "Review ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Review deleted" }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/settings": { "post": { "tags": [ "Platform Configuration" ], "summary": "Update Platform Settings", "description": "Create or update platform-wide settings (currency, language, SEO, etc.). Requires SUPER_ADMIN permission.", "operationId": "updateSettings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "options" ], "properties": { "language": { "type": "string", "example": "en" }, "options": { "description": "Platform settings object", "properties": { "siteTitle": { "type": "string", "example": "ChawkBazar" }, "siteSubtitle": { "type": "string" }, "currency": { "type": "string", "example": "USD" }, "logo": { "type": "object" }, "seo": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Settings updated successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" } }, "security": [ { "sanctum": [] } ] } }, "/shippings": { "get": { "tags": [ "Platform Configuration" ], "summary": "List All Shipping Classes", "description": "Get list of all shipping classes/zones. Requires SUPER_ADMIN permission.", "operationId": "listShippings", "responses": { "200": { "description": "Shippings retrieved successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Platform Configuration" ], "summary": "Create Shipping Class", "description": "Create a new shipping class/zone. Requires SUPER_ADMIN permission.", "operationId": "createShipping", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "amount", "type" ], "properties": { "name": { "type": "string", "example": "Express Shipping" }, "amount": { "type": "number", "example": 10.99 }, "type": { "type": "string", "enum": [ "fixed", "percentage", "free" ], "example": "fixed" }, "is_global": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Shipping created successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/shippings/{id}": { "get": { "tags": [ "Platform Configuration" ], "summary": "Get Shipping Details", "description": "Get a single shipping class by ID. Requires SUPER_ADMIN permission.", "operationId": "getShipping", "parameters": [ { "name": "id", "in": "path", "description": "Shipping ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Shipping retrieved successfully" }, "401": { "description": "Unauthenticated" }, "404": { "description": "Shipping not found" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Platform Configuration" ], "summary": "Update Shipping Class", "description": "Update an existing shipping class. Requires SUPER_ADMIN permission.", "operationId": "updateShipping", "parameters": [ { "name": "id", "in": "path", "description": "Shipping ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "amount": { "type": "number" }, "type": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Shipping updated successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "404": { "description": "Shipping not found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Platform Configuration" ], "summary": "Delete Shipping Class", "description": "Delete a shipping class. Requires SUPER_ADMIN permission.", "operationId": "deleteShipping", "parameters": [ { "name": "id", "in": "path", "description": "Shipping ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Shipping deleted successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "404": { "description": "Shipping not found" } }, "security": [ { "sanctum": [] } ] } }, "/shops": { "get": { "tags": [ "Shops" ], "summary": "List all shops", "description": "Retrieve a paginated list of active shops with order and product counts.", "operationId": "listShops", "parameters": [ { "name": "limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "default": 15 } }, { "name": "page", "in": "query", "description": "Page number", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Shops retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedShops" } } } } } }, "post": { "tags": [ "Shops" ], "summary": "Create a new shop", "description": "Create a new shop. Requires STORE_OWNER permission.", "operationId": "createShop", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "My New Shop" }, "description": { "type": "string", "example": "A great shop for fashion lovers" }, "logo": { "type": "object" }, "cover_image": { "type": "object" }, "address": { "type": "object" }, "settings": { "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Shop created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shop" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - needs STORE_OWNER permission" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/shops/{slug}": { "get": { "tags": [ "Shops" ], "summary": "Get a single shop", "description": "Retrieve detailed shop information by slug or ID. Includes categories, owner, and balance (for shop owner/admin only).", "operationId": "getShop", "parameters": [ { "name": "slug", "in": "path", "description": "Shop slug or ID", "required": true, "schema": { "type": "string", "example": "urban-threads-emporium" } } ], "responses": { "200": { "description": "Shop retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shop" } } } }, "404": { "description": "Shop not found" } } } }, "/shops/{id}": { "put": { "tags": [ "Shops" ], "summary": "Update a shop", "description": "Update shop details. Requires ownership or SUPER_ADMIN permission.", "operationId": "updateShop", "parameters": [ { "name": "id", "in": "path", "description": "Shop ID", "required": true, "schema": { "type": "integer", "example": 2 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "logo": { "type": "object" }, "cover_image": { "type": "object" }, "address": { "type": "object" }, "settings": { "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Shop updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shop" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Shop not found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Shops" ], "summary": "Delete a shop", "description": "Delete a shop. Requires ownership or SUPER_ADMIN permission.", "operationId": "deleteShop", "parameters": [ { "name": "id", "in": "path", "description": "Shop ID to delete", "required": true, "schema": { "type": "integer", "example": 2 } } ], "responses": { "200": { "description": "Shop deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shop" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Shop not found" } }, "security": [ { "sanctum": [] } ] } }, "/approve-shop": { "post": { "tags": [ "Shop Administration" ], "summary": "Approve Shop", "description": "Approve a pending shop and set commission rate. Activates shop and publishes all products. Requires SUPER_ADMIN permission.", "operationId": "approveShop", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id" ], "properties": { "id": { "description": "Shop ID to approve", "type": "integer", "example": 5 }, "admin_commission_rate": { "description": "Custom commission rate (optional)", "type": "number", "example": 10.5 }, "isCustomCommission": { "description": "Use custom commission rate", "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "200": { "description": "Shop approved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shop" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "404": { "description": "Shop not found" } }, "security": [ { "sanctum": [] } ] } }, "/disapprove-shop": { "post": { "tags": [ "Shop Administration" ], "summary": "Disapprove/Disable Shop", "description": "Disable a shop and set all its products to draft. Requires SUPER_ADMIN permission.", "operationId": "disapproveShop", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id" ], "properties": { "id": { "description": "Shop ID to disapprove", "type": "integer", "example": 5 } }, "type": "object" } } } }, "responses": { "200": { "description": "Shop disapproved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shop" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "404": { "description": "Shop not found" } }, "security": [ { "sanctum": [] } ] } }, "/staffs": { "get": { "tags": [ "Staff Management" ], "summary": "List Shop Staff", "description": "Get list of staff members for a shop. Requires STORE_OWNER permission.", "operationId": "getStaffs", "parameters": [ { "name": "shop_id", "in": "query", "description": "Shop ID", "required": true, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Staff list retrieved", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "total": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Staff Management" ], "summary": "Add Staff to Shop", "description": "Create a new staff member for a shop. Only the shop owner can add staff.", "operationId": "addStaff", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password", "shop_id" ], "properties": { "name": { "type": "string", "example": "John Staff" }, "email": { "type": "string", "format": "email", "example": "staff@myshop.com" }, "password": { "type": "string", "format": "password", "example": "staffPassword123" }, "shop_id": { "description": "ID of the shop to assign staff to", "type": "integer", "example": 5 } }, "type": "object" } } } }, "responses": { "200": { "description": "Staff created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - not shop owner" } }, "security": [ { "sanctum": [] } ] } }, "/staffs/{id}": { "delete": { "tags": [ "Staff Management" ], "summary": "Delete Staff Member", "description": "Remove a staff member from the shop. Only the shop owner can delete staff.", "operationId": "deleteStaff", "parameters": [ { "name": "id", "in": "path", "description": "Staff user ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Staff deleted successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - not shop owner" }, "404": { "description": "Staff not found" } }, "security": [ { "sanctum": [] } ] } }, "/my-shops": { "get": { "tags": [ "Shops" ], "summary": "Get current user's shops", "description": "Retrieve all shops owned by the authenticated user.", "operationId": "getMyShops", "responses": { "200": { "description": "User's shops retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ShopSummary" } } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/followed-shops-popular-products": { "get": { "tags": [ "Shops" ], "summary": "Get popular products from followed shops", "description": "Retrieve popular products from shops the user follows, sorted by order count.", "operationId": "getFollowedShopsPopularProducts", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "Popular products retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/followed-shops": { "get": { "tags": [ "Shops" ], "summary": "Get shops followed by current user", "description": "Retrieve paginated list of shops that the authenticated user is following.", "operationId": "getFollowedShops", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Followed shops retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedShops" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/follow-shop": { "get": { "tags": [ "Shops" ], "summary": "Check if user follows a shop", "description": "Returns boolean indicating if authenticated user follows the specified shop.", "operationId": "checkFollowShop", "parameters": [ { "name": "shop_id", "in": "query", "required": true, "schema": { "type": "integer", "example": 2 } } ], "responses": { "200": { "description": "Follow status retrieved", "content": { "application/json": { "schema": { "type": "boolean" }, "example": true } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Shops" ], "summary": "Follow or unfollow a shop", "description": "Toggle follow status for a shop. Returns true if now following, false if unfollowed.", "operationId": "toggleFollowShop", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "shop_id" ], "properties": { "shop_id": { "type": "integer", "example": 2 } }, "type": "object" } } } }, "responses": { "200": { "description": "Follow status toggled", "content": { "application/json": { "schema": { "type": "boolean" }, "example": true } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/near-by-shop/{lat}/{lng}": { "get": { "tags": [ "Shops" ], "summary": "Find shops near a location", "description": "Returns shops within the configured maximum distance from the given coordinates, sorted by distance.", "operationId": "getNearByShops", "parameters": [ { "name": "lat", "in": "path", "description": "Latitude", "required": true, "schema": { "type": "number", "format": "float", "example": 40.7128 } }, { "name": "lng", "in": "path", "description": "Longitude", "required": true, "schema": { "type": "number", "format": "float", "example": -74.006 } } ], "responses": { "200": { "description": "Nearby shops retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ShopSummary" }, { "properties": { "distance": { "description": "Distance in km", "type": "number", "format": "float" } }, "type": "object" } ] } } } } }, "400": { "description": "Invalid coordinates" } } } }, "/new-shops": { "get": { "tags": [ "Shop Administration" ], "summary": "List Pending/Inactive Shops", "description": "Get paginated list of shops filtered by active status. Use is_active=false for pending shops. Requires SUPER_ADMIN permission.", "operationId": "getNewOrInactiveShops", "parameters": [ { "name": "is_active", "in": "query", "description": "Filter by active status (false=pending)", "required": true, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Shops retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedShops" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" } }, "security": [ { "sanctum": [] } ] } }, "/transfer-shop-ownership": { "post": { "tags": [ "Shops" ], "summary": "Transfer Shop Ownership", "description": "Transfer ownership of a shop to another user. Requires STORE_OWNER permission.", "operationId": "transferShopOwnership", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "shop_id", "admin_id" ], "properties": { "shop_id": { "description": "Shop ID", "type": "integer", "example": 5 }, "admin_id": { "description": "User ID to transfer ownership to", "type": "integer", "example": 10 } }, "type": "object" } } } }, "responses": { "200": { "description": "Ownership transferred successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Shop or User not found" } }, "security": [ { "sanctum": [] } ] } }, "/store-notices": { "get": { "tags": [ "Store Notices" ], "summary": "List store notices", "description": "Retrieve a paginated list of store notices for the authenticated user.", "operationId": "getStoreNotices", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "List of notices retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StoreNotice" } }, "current_page": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Store Notices" ], "summary": "Create a new store notice", "description": "Post a notice for shops or users. Restricted to Super Admin or Shop Owner.", "operationId": "storeStoreNotice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "notice", "description", "priority", "type" ], "properties": { "notice": { "type": "string", "example": "Holiday Closure" }, "description": { "type": "string", "example": "Shop will be closed..." }, "priority": { "type": "string", "enum": [ "high", "medium", "low" ] }, "type": { "type": "string" }, "received_by": { "description": "Array of shop or user IDs", "type": "array", "items": { "type": "integer" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Notice created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreNotice" } } } }, "403": { "description": "Forbidden" } }, "security": [ { "sanctum": [] } ] } }, "/store-notices/getStoreNoticeType": { "get": { "tags": [ "Store Notices" ], "summary": "Get available notice types", "description": "Retrieve list of valid notice types (e.g., all_shop, all_vendor).", "operationId": "getStoreNoticeTypes", "responses": { "200": { "description": "List of types retrieved successfully" } }, "security": [ { "sanctum": [] } ] } }, "/store-notices/getUsersToNotify": { "get": { "tags": [ "Store Notices" ], "summary": "Get candidates for notice recipients", "description": "Retrieve users or shops that can receive notices based on current user scope.", "operationId": "getUsersToNotify", "parameters": [ { "name": "type", "in": "query", "required": true } ], "responses": { "200": { "description": "List retrieved successfully" } }, "security": [ { "sanctum": [] } ] } }, "/store-notices/{id}": { "get": { "tags": [ "Store Notices" ], "summary": "Get single store notice", "operationId": "getStoreNoticeById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Notice found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreNotice" } } } }, "404": { "description": "Notice not found" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Store Notices" ], "summary": "Update store notice", "operationId": "updateStoreNotice", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "notice": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Notice updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreNotice" } } } } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Store Notices" ], "summary": "Delete store notice", "operationId": "deleteStoreNotice", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Notice deleted successfully" } }, "security": [ { "sanctum": [] } ] } }, "/store-notices/read": { "post": { "tags": [ "Store Notices" ], "summary": "Mark a single notice as read", "operationId": "markNoticeAsRead", "requestBody": { "content": { "application/json": { "schema": { "required": [ "id" ], "properties": { "id": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Marked as read successfully" } }, "security": [ { "sanctum": [] } ] } }, "/store-notices/read-all": { "post": { "tags": [ "Store Notices" ], "summary": "Mark multiple notices as read", "operationId": "markAllNoticesAsRead", "requestBody": { "content": { "application/json": { "schema": { "required": [ "notices" ], "properties": { "notices": { "type": "array", "items": { "type": "integer", "example": 1 } } }, "type": "object" } } } }, "responses": { "200": { "description": "Notices marked as read" } }, "security": [ { "sanctum": [] } ] } }, "/tags": { "get": { "tags": [ "Tags" ], "summary": "List all product tags", "description": "Retrieve a paginated list of product tags.", "operationId": "listTags", "parameters": [ { "name": "language", "in": "query", "description": "Language code", "required": false, "schema": { "type": "string", "default": "en", "example": "en" } }, { "name": "limit", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 15, "example": 15 } } ], "responses": { "200": { "description": "Tags retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTags" } } } } } }, "post": { "tags": [ "Tags" ], "summary": "Create a new tag", "description": "Create a new tag. Requires admin permissions.", "operationId": "createTag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "type_id" ], "properties": { "name": { "type": "string", "example": "Organic" }, "type_id": { "type": "integer", "example": 1 }, "details": { "type": "string", "example": "Organic products" }, "icon": { "type": "string", "example": "OrganicIcon" } }, "type": "object" } } } }, "responses": { "201": { "description": "Tag created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/tags/{slug}": { "get": { "tags": [ "Tags" ], "summary": "Get a single product tag", "description": "Retrieve detailed information about a tag by slug or ID.", "operationId": "getTag", "parameters": [ { "name": "slug", "in": "path", "description": "Tag slug or ID", "required": true, "schema": { "type": "string", "example": "organic" } }, { "name": "language", "in": "query", "description": "Language code", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Tag retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "404": { "description": "Tag not found" } } } }, "/tags/{id}": { "put": { "tags": [ "Tags" ], "summary": "Update a tag", "description": "Update tag details. Requires admin permissions.", "operationId": "updateTag", "parameters": [ { "name": "id", "in": "path", "description": "Tag ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "responses": { "200": { "description": "Tag updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "404": { "description": "Tag not found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Tags" ], "summary": "Delete a tag", "description": "Delete a product tag. Requires admin permissions.", "operationId": "deleteTag", "parameters": [ { "name": "id", "in": "path", "description": "Tag ID to delete", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Tag deleted successfully", "content": { "application/json": { "schema": { "type": "boolean" }, "example": true } } }, "404": { "description": "Tag not found" } }, "security": [ { "sanctum": [] } ] } }, "/taxes": { "get": { "tags": [ "Platform Configuration" ], "summary": "List All Taxes", "description": "Get list of all tax rates. Requires SUPER_ADMIN permission.", "operationId": "listTaxes", "responses": { "200": { "description": "Taxes retrieved successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Platform Configuration" ], "summary": "Create Tax Rate", "description": "Create a new tax rate. Requires SUPER_ADMIN permission.", "operationId": "createTax", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "rate", "country" ], "properties": { "name": { "type": "string", "example": "VAT" }, "rate": { "type": "number", "example": 15 }, "country": { "type": "string", "example": "US" }, "state": { "type": "string", "example": "CA" }, "city": { "type": "string" }, "zip": { "type": "string" }, "is_global": { "type": "boolean", "example": false }, "priority": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Tax created successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/taxes/{id}": { "get": { "tags": [ "Platform Configuration" ], "summary": "Get Tax Details", "description": "Get a single tax rate by ID. Requires SUPER_ADMIN permission.", "operationId": "getTax", "parameters": [ { "name": "id", "in": "path", "description": "Tax ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Tax retrieved successfully" }, "401": { "description": "Unauthenticated" }, "404": { "description": "Tax not found" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Platform Configuration" ], "summary": "Update Tax Rate", "description": "Update an existing tax rate. Requires SUPER_ADMIN permission.", "operationId": "updateTax", "parameters": [ { "name": "id", "in": "path", "description": "Tax ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "rate": { "type": "number" }, "country": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Tax updated successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "404": { "description": "Tax not found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Platform Configuration" ], "summary": "Delete Tax Rate", "description": "Delete a tax rate. Requires SUPER_ADMIN permission.", "operationId": "deleteTax", "parameters": [ { "name": "id", "in": "path", "description": "Tax ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Tax deleted successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "404": { "description": "Tax not found" } }, "security": [ { "sanctum": [] } ] } }, "/terms-and-conditions": { "get": { "tags": [ "Terms & Conditions" ], "summary": "List Terms & Conditions", "description": "Retrieve a paginated list of terms and conditions. Public users see only approved ones.", "operationId": "getTermsAndConditions", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 10 } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "default": "en" } }, { "name": "shop_id", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Terms & conditions retrieved successfully", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TermsAndConditions" } }, "total": { "type": "integer" } }, "type": "object" } } } } } } }, "/terms-and-conditions/{slug}": { "get": { "tags": [ "Terms & Conditions" ], "summary": "Get Single Terms & Conditions", "description": "Retrieve details of a terms and conditions by its slug.", "operationId": "getTermsAndConditionsBySlug", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Terms & conditions details retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsAndConditions" } } } }, "404": { "description": "Terms & conditions not found" } } } }, "/types": { "get": { "tags": [ "Types" ], "summary": "List all product types", "description": "Retrieve all product types/collections like Grocery, Bakery, Clothing, etc.", "operationId": "listTypes", "parameters": [ { "name": "language", "in": "query", "description": "Language code", "required": false, "schema": { "type": "string", "default": "en", "example": "en" } }, { "name": "limit", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 1000, "example": 15 } } ], "responses": { "200": { "description": "Types retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Type" } } } } } } }, "post": { "tags": [ "Types" ], "summary": "Create a new product type", "description": "Create a new type. Requires admin permissions.", "operationId": "createType", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "settings" ], "properties": { "name": { "type": "string", "example": "Bakery" }, "icon": { "type": "string", "example": "BakeryIcon" }, "settings": { "properties": { "isFullWidth": { "type": "boolean", "example": true }, "layoutType": { "type": "string", "example": "classic" } }, "type": "object" }, "banners": { "type": "array", "items": { "type": "object" } }, "promotional_sliders": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Type created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Type" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/types/{slug}": { "get": { "tags": [ "Types" ], "summary": "Get a single product type", "description": "Retrieve detailed information about a type by slug or ID.", "operationId": "getType", "parameters": [ { "name": "slug", "in": "path", "description": "Type slug or ID", "required": true, "schema": { "type": "string", "example": "grocery" } }, { "name": "language", "in": "query", "description": "Language code", "required": false, "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Type retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Type" } } } }, "404": { "description": "Type not found" } } } }, "/types/{id}": { "put": { "tags": [ "Types" ], "summary": "Update a product type", "description": "Update type details. Requires admin permissions.", "operationId": "updateType", "parameters": [ { "name": "id", "in": "path", "description": "Type ID", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Type" } } } }, "responses": { "200": { "description": "Type updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Type" } } } }, "404": { "description": "Type not found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Types" ], "summary": "Delete a product type", "description": "Delete a product type. Requires admin permissions.", "operationId": "deleteType", "parameters": [ { "name": "id", "in": "path", "description": "Type ID to delete", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Type deleted successfully", "content": { "application/json": { "schema": { "type": "boolean" }, "example": true } } }, "404": { "description": "Type not found" } }, "security": [ { "sanctum": [] } ] } }, "/admins": { "get": { "tags": [ "User Management" ], "summary": "List Admin Users", "description": "Get list of all admin users. Requires SUPER_ADMIN permission.", "operationId": "getAdmins", "parameters": [ { "name": "limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Admins retrieved successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "sanctum": [] } ] } }, "/vendors": { "get": { "tags": [ "User Management" ], "summary": "List Vendor Users", "description": "Get list of all store owner/vendor users.", "operationId": "getVendors", "parameters": [ { "name": "limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "default": 15 } }, { "name": "is_active", "in": "query", "description": "Filter by active status", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Vendors retrieved successfully" }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/customers": { "get": { "tags": [ "User Management" ], "summary": "List Customer Users", "description": "Get list of all customer users (excluding admins, vendors, and staff).", "operationId": "getCustomers", "parameters": [ { "name": "limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Customers retrieved successfully" }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/users": { "get": { "tags": [ "User Management" ], "summary": "List All Users", "description": "Get paginated list of all users. Requires SUPER_ADMIN permission.", "operationId": "listUsers", "parameters": [ { "name": "limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Users retrieved successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "User Management" ], "summary": "Create User (Admin)", "description": "Create a new user with any role. Requires SUPER_ADMIN permission.", "operationId": "createUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password" ], "properties": { "name": { "type": "string", "example": "New User" }, "email": { "type": "string", "format": "email", "example": "newuser@example.com" }, "password": { "type": "string", "format": "password", "example": "password123" }, "permission": { "type": "string", "enum": [ "customer", "store_owner", "staff", "editor", "super_admin" ], "example": "customer" } }, "type": "object" } } } }, "responses": { "201": { "description": "User created successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/users/{id}": { "get": { "tags": [ "User Management" ], "summary": "Get User Details", "description": "Get a single user's full details. Requires SUPER_ADMIN permission.", "operationId": "getUser", "parameters": [ { "name": "id", "in": "path", "description": "User ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "User retrieved successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "User not found" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "User Management" ], "summary": "Update User", "description": "Update user profile. SUPER_ADMIN can update any user; others can only update themselves.", "operationId": "updateUser", "parameters": [ { "name": "id", "in": "path", "description": "User ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Updated Name" }, "email": { "type": "string", "format": "email", "example": "updated@example.com" }, "profile": { "type": "object" }, "address": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "User updated successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "User Management" ], "summary": "Delete User", "description": "Permanently delete a user. Requires SUPER_ADMIN permission.", "operationId": "deleteUser", "parameters": [ { "name": "id", "in": "path", "description": "User ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "User deleted successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "404": { "description": "User not found" } }, "security": [ { "sanctum": [] } ] } }, "/me": { "get": { "tags": [ "Authentication" ], "summary": "Get Current User", "description": "Get the currently authenticated user's profile with wallet, addresses, and shop information", "operationId": "getCurrentUser", "responses": { "200": { "description": "User profile retrieved successfully", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "role": { "type": "string", "example": "customer" }, "profile": { "type": "object" }, "wallet": { "type": "object" }, "address": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/token": { "post": { "tags": [ "Authentication" ], "summary": "User Login", "description": "Authenticate user and get access token", "operationId": "login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "password": { "type": "string", "format": "password", "example": "password123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Successful login", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/logout": { "post": { "tags": [ "Authentication" ], "summary": "User Logout", "description": "Revoke the current access token", "operationId": "logout", "responses": { "200": { "description": "Successfully logged out", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/register": { "post": { "tags": [ "Authentication" ], "summary": "Register New User", "description": "Create a new user account and get access token", "operationId": "register", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password" ], "properties": { "name": { "type": "string", "maxLength": 255, "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "password": { "type": "string", "format": "password", "example": "securePassword123" }, "permission": { "description": "User permission level", "type": "string", "enum": [ "customer", "store_owner" ], "example": "customer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Successfully registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "403": { "description": "Not authorized (attempted to register as super_admin, editor, or staff - these roles are admin-assigned only)" } } } }, "/ban-user": { "post": { "tags": [ "User Management" ], "summary": "Ban User", "description": "Deactivate a user account and all their shops. Requires SUPER_ADMIN permission.", "operationId": "banUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id" ], "properties": { "id": { "description": "User ID to ban", "type": "integer", "example": 5 } }, "type": "object" } } } }, "responses": { "200": { "description": "User banned successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" } }, "security": [ { "sanctum": [] } ] } }, "/active-user": { "post": { "tags": [ "User Management" ], "summary": "Activate User", "description": "Reactivate a banned user account. Requires SUPER_ADMIN permission.", "operationId": "activateUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id" ], "properties": { "id": { "description": "User ID to activate", "type": "integer", "example": 5 } }, "type": "object" } } } }, "responses": { "200": { "description": "User activated successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" } }, "security": [ { "sanctum": [] } ] } }, "/forget-password": { "post": { "tags": [ "Password Management" ], "summary": "Request Password Reset", "description": "Send password reset email to user", "operationId": "forgetPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password reset email sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/verify-forget-password-token": { "post": { "tags": [ "Password Management" ], "summary": "Verify Password Reset Token", "description": "Verify that a password reset token is valid", "operationId": "verifyForgetPasswordToken", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "token" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "token": { "type": "string", "example": "abc123xyz" } }, "type": "object" } } } }, "responses": { "200": { "description": "Token verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/reset-password": { "post": { "tags": [ "Password Management" ], "summary": "Reset Password", "description": "Reset user password using token from email", "operationId": "resetPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "token", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "token": { "type": "string", "example": "abc123xyz" }, "password": { "type": "string", "format": "password", "example": "newSecurePassword123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password reset successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "422": { "description": "Validation error" } } } }, "/change-password": { "post": { "tags": [ "Password Management" ], "summary": "Change Password", "description": "Change the current user's password (requires old password)", "operationId": "changePassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "oldPassword", "newPassword" ], "properties": { "oldPassword": { "type": "string", "format": "password", "example": "currentPassword123" }, "newPassword": { "type": "string", "format": "password", "example": "newSecurePassword456" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password changed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error or old password incorrect" } }, "security": [ { "sanctum": [] } ] } }, "/social-login-token": { "post": { "tags": [ "Authentication" ], "summary": "Social Login", "description": "Login or register using Facebook or Google OAuth token", "operationId": "socialLogin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "provider", "access_token" ], "properties": { "provider": { "type": "string", "enum": [ "facebook", "google" ], "example": "google" }, "access_token": { "type": "string", "example": "ya29.a0AfH6SMC..." } }, "type": "object" } } } }, "responses": { "200": { "description": "Successfully authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "422": { "description": "Invalid provider or token" } } } }, "/add-points": { "post": { "tags": [ "User Management" ], "summary": "Add Loyalty Points", "description": "Add loyalty/reward points to a customer's wallet. Requires SUPER_ADMIN permission.", "operationId": "addPoints", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "customer_id", "points" ], "properties": { "customer_id": { "description": "User ID to add points to", "type": "integer", "example": 5 }, "points": { "description": "Number of points to add", "type": "number", "example": 100 } }, "type": "object" } } } }, "responses": { "200": { "description": "Points added successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/users/make-admin": { "post": { "tags": [ "User Management" ], "summary": "Toggle Admin Status", "description": "Grant or revoke SUPER_ADMIN permission from a user. If user is admin, revokes; if not, grants. Requires SUPER_ADMIN permission.", "operationId": "makeOrRevokeAdmin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "user_id" ], "properties": { "user_id": { "description": "User ID to toggle admin status", "type": "integer", "example": 5 } }, "type": "object" } } } }, "responses": { "200": { "description": "Admin status toggled successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "404": { "description": "User not found" } }, "security": [ { "sanctum": [] } ] } }, "/subscribe-to-newsletter": { "post": { "tags": [ "Users" ], "summary": "Subscribe to newsletter", "description": "Add an email address to the platform's newsletter subscription list.", "operationId": "subscribeNewsletter", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "buyer@example.com" } }, "type": "object" } } } }, "responses": { "200": { "description": "Successfully subscribed", "content": { "application/json": { "schema": { "type": "boolean" }, "example": true } } }, "422": { "description": "Validation error" }, "500": { "description": "Something went wrong" } } } }, "/update-email": { "post": { "tags": [ "Authentication" ], "summary": "Update User Email", "description": "Update the current user's email address. Requires authentication.", "operationId": "updateEmail", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "newemail@example.com" } }, "type": "object" } } } }, "responses": { "200": { "description": "Email updated successfully" }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/wishlists": { "get": { "tags": [ "Wishlist" ], "summary": "List Wishlist Products", "description": "Get a paginated list of products in the current user's wishlist.", "operationId": "getWishlists", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Wishlist products retrieved", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "total": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Wishlist" ], "summary": "Add Product to Wishlist", "description": "Add a single product to the current user's wishlist.", "operationId": "addToWishlist", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "product_id" ], "properties": { "product_id": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Product added successfully" }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/wishlists/toggle": { "post": { "tags": [ "Wishlist" ], "summary": "Toggle Wishlist Item", "description": "Add or remove a product from the current user's wishlist.", "operationId": "toggleWishlist", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "product_id" ], "properties": { "product_id": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Wishlist toggled successfully" }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/wishlists/{id}": { "delete": { "tags": [ "Wishlist" ], "summary": "Remove Product from Wishlist", "description": "Remove a specific product from the current user's wishlist.", "operationId": "removeFromWishlist", "parameters": [ { "name": "id", "in": "path", "description": "Product ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Product removed successfully" }, "401": { "description": "Unauthenticated" }, "404": { "description": "Product not found" } }, "security": [ { "sanctum": [] } ] } }, "/withdraws": { "get": { "tags": [ "Withdrawal Management" ], "summary": "List withdrawals", "description": "List withdrawal requests. Store Owners see their own. Super Admins see all.", "operationId": "getWithdraws", "parameters": [ { "name": "shop_id", "in": "query", "description": "Filter by Shop ID", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "default": 15 } }, { "name": "page", "in": "query", "description": "Page number", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Withdrawals retrieved", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Withdraw" } }, "total": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Withdrawal Management" ], "summary": "Request a withdrawal", "description": "Create a new withdrawal request for a shop. Requires STORE_OWNER permission.", "operationId": "createWithdraw", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "amount", "shop_id", "payment_method" ], "properties": { "amount": { "type": "number", "format": "float", "example": 500 }, "shop_id": { "type": "integer", "example": 10 }, "payment_method": { "type": "string", "example": "Bank Transfer" }, "details": { "type": "string", "example": "Account info..." }, "note": { "type": "string", "example": "Monthly payout" } }, "type": "object" } } } }, "responses": { "200": { "description": "Withdrawal requested successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdraw" } } } }, "400": { "description": "Bad Request (Insufficient balance or invalid shop)" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "sanctum": [] } ] } }, "/withdraws/{id}": { "get": { "tags": [ "Withdrawal Management" ], "summary": "Get withdrawal details", "description": "Get details of a specific withdrawal. Requires STORE_OWNER or SUPER_ADMIN permission.", "operationId": "getWithdraw", "parameters": [ { "name": "id", "in": "path", "description": "Withdraw ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Withdraw details retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdraw" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Withdraw not found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Withdrawal Management" ], "summary": "Delete Withdrawal Request", "description": "Delete a withdrawal request. Requires SUPER_ADMIN permission.", "operationId": "deleteWithdraw", "parameters": [ { "name": "id", "in": "path", "description": "Withdraw ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Withdraw deleted successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "404": { "description": "Withdraw not found" } }, "security": [ { "sanctum": [] } ] } }, "/approve-withdraw": { "post": { "tags": [ "Withdrawal Management" ], "summary": "Approve/Reject Withdrawal", "description": "Change withdrawal request status (approved, rejected, on_hold, processing). Requires SUPER_ADMIN permission.", "operationId": "approveWithdraw", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id", "status" ], "properties": { "id": { "description": "Withdraw ID", "type": "integer", "example": 5 }, "status": { "type": "string", "enum": [ "approved", "rejected", "on_hold", "processing", "pending" ], "example": "approved" } }, "type": "object" } } } }, "responses": { "200": { "description": "Withdrawal status updated" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - requires SUPER_ADMIN" }, "404": { "description": "Withdraw not found" } }, "security": [ { "sanctum": [] } ] } } }, "components": { "schemas": { "Address": { "properties": { "id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Home" }, "type": { "type": "string", "enum": [ "billing", "shipping" ], "example": "shipping" }, "default": { "type": "boolean", "example": true }, "address": { "description": "JSON object containing street, city, state, zip, country", "type": "object" }, "customer_id": { "type": "integer", "example": 10 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Attribute": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Size" }, "slug": { "type": "string", "example": "size" }, "shop_id": { "type": "integer", "example": 10 }, "language": { "type": "string", "example": "en" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/AttributeValue" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "AttributeValue": { "properties": { "id": { "type": "integer", "example": 5 }, "attribute_id": { "type": "integer", "example": 1 }, "value": { "type": "string", "example": "XL" }, "meta": { "type": "string", "nullable": true } }, "type": "object" }, "Author": { "description": "Author details", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Leo Tolstoy" }, "slug": { "type": "string", "example": "leo-tolstoy" }, "bio": { "type": "string", "example": "Count Lev Nikolayevich Tolstoy, usually referred to in English as Leo Tolstoy, was a Russian writer." }, "quote": { "type": "string", "example": "All, everything that I understand, I understand only because I love." }, "born": { "type": "string", "example": "1828-09-09" }, "death": { "type": "string", "example": "1910-11-20" }, "languages": { "type": "string", "example": "Russian, French" }, "is_approved": { "type": "boolean", "example": true }, "products_count": { "type": "integer", "example": 15 }, "language": { "type": "string", "example": "en" }, "translated_languages": { "type": "array", "items": { "type": "string" }, "example": [ "en" ] }, "socials": { "type": "array", "items": { "type": "object" } }, "image": { "type": "object", "nullable": true }, "cover_image": { "type": "object", "nullable": true } }, "type": "object" }, "PaginatedAuthors": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Author" } }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 15 }, "total": { "type": "integer", "example": 100 }, "last_page": { "type": "integer", "example": 7 } }, "type": "object" }, "BecameSeller": { "properties": { "page_options": { "description": "Configuration for the 'Become a Seller' page", "type": "object" }, "commissions": { "description": "Platform commission structures", "type": "array", "items": { "type": "object" } } }, "type": "object" }, "CategorySummary": { "description": "Category summary for listings", "properties": { "id": { "type": "integer", "example": 3 }, "name": { "type": "string", "example": "Men" }, "slug": { "type": "string", "example": "men" }, "icon": { "type": "string", "example": "Wallet" }, "details": { "type": "string", "example": "A wonderful serenity has taken possession of my entire soul." }, "parent": { "type": "integer", "example": null, "nullable": true }, "products_count": { "type": "integer", "example": 25 }, "language": { "type": "string", "example": "en" }, "image": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 28 }, "original": { "type": "string", "example": "https://chawkbazarlaravel.s3.ap-southeast-1.amazonaws.com/28/men.png" }, "thumbnail": { "type": "string", "example": "https://chawkbazarlaravel.s3.ap-southeast-1.amazonaws.com/28/conversions/men-thumbnail.jpg" } }, "type": "object" } }, "banner_image": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "original": { "type": "string" }, "thumbnail": { "type": "string" } }, "type": "object" } } }, "type": "object" }, "Category": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CategorySummary" }, { "properties": { "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "type": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Clothing" }, "slug": { "type": "string", "example": "clothing" } }, "type": "object", "nullable": true }, "parentCategory": { "oneOf": [ { "$ref": "#/components/schemas/CategorySummary" } ], "nullable": true, "type": "object" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/CategorySummary" } } }, "type": "object" } ] }, "PaginatedCategories": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CategorySummary" } }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 15 }, "total": { "type": "integer", "example": 8 } }, "type": "object" }, "AuthResponse": { "properties": { "token": { "description": "Bearer token for API authentication", "type": "string", "example": "1|abc123xyz..." }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "customer" ] }, "role": { "type": "string", "example": "customer" } }, "type": "object" }, "LoginResponse": { "properties": { "token": { "description": "Bearer token or null if login failed", "type": "string", "example": "1|abc123xyz...", "nullable": true }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "customer" ] }, "email_verified": { "type": "boolean", "example": true }, "role": { "type": "string", "example": "customer" } }, "type": "object" }, "MessageResponse": { "properties": { "message": { "type": "string", "example": "Operation completed successfully" }, "success": { "type": "boolean", "example": true } }, "type": "object" }, "ValidationError": { "properties": { "errors": { "type": "object", "example": { "email": [ "The email field is required." ], "password": [ "The password field is required." ] } } }, "type": "object" }, "CmsPage": { "description": "CMS Page details", "properties": { "id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Privacy Policy" }, "slug": { "type": "string", "example": "privacy-policy" }, "content": { "description": "List of content blocks", "type": "array", "items": { "type": "object" } }, "meta": { "description": "SEO metadata", "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "PaginatedCmsPages": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CmsPage" } }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 10 }, "total": { "type": "integer", "example": 5 }, "last_page": { "type": "integer", "example": 1 } }, "type": "object" }, "ProductSummary": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "price": { "type": "number" }, "sale_price": { "type": "number", "nullable": true }, "min_price": { "type": "number", "nullable": true }, "max_price": { "type": "number", "nullable": true }, "product_type": { "type": "string" }, "quantity": { "type": "integer" }, "image": { "type": "object", "nullable": true }, "shop": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "type": "object", "nullable": true }, "type": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "type": "object", "nullable": true } }, "type": "object" }, "Conversation": { "properties": { "id": { "type": "integer", "example": 1 }, "shop_id": { "type": "integer", "example": 2 }, "user_id": { "type": "integer", "example": 10 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "shop": { "$ref": "#/components/schemas/Shop" }, "user": { "$ref": "#/components/schemas/User" }, "latest_message": { "type": "object", "nullable": true } }, "type": "object" }, "Coupon": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "SAVE50" }, "description": { "type": "string", "example": "Get 50% off your first order" }, "image": { "type": "object" }, "type": { "type": "string", "example": "percentage" }, "amount": { "type": "number", "format": "float", "example": 50 }, "minimum_cart_amount": { "type": "number", "format": "float", "example": 100 }, "active_from": { "type": "string", "format": "date-time" }, "expire_at": { "type": "string", "format": "date-time" }, "is_approve": { "type": "boolean", "example": true }, "language": { "type": "string", "example": "en" }, "shop_id": { "type": "integer" } }, "type": "object" }, "Faq": { "properties": { "id": { "type": "integer", "example": 1 }, "faq_title": { "type": "string", "example": "How to return?" }, "slug": { "type": "string", "example": "how-to-return" }, "faq_description": { "type": "string", "example": "You can return within 30 days." }, "faq_type": { "type": "string", "example": "global" }, "issued_by": { "type": "string", "example": "Admin" }, "language": { "type": "string", "example": "en" }, "translated_languages": { "type": "array", "items": { "type": "string", "example": "en" } } }, "type": "object" }, "FlashSale": { "properties": { "id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Summer Sale" }, "slug": { "type": "string", "example": "summer-sale" }, "description": { "type": "string", "example": "Up to 50% off on summer collection" }, "image": { "type": "object" }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time" }, "type": { "type": "string", "enum": [ "fixed", "percentage" ], "example": "percentage" }, "rate": { "type": "number", "example": 50 }, "language": { "type": "string", "example": "en" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Manufacturer": { "description": "Manufacturer details", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Apple" }, "slug": { "type": "string", "example": "apple" }, "description": { "type": "string", "example": "Apple Inc. is an American multinational technology company." }, "website": { "type": "string", "example": "https://www.apple.com" }, "is_approved": { "type": "boolean", "example": true }, "products_count": { "type": "integer", "example": 50 }, "language": { "type": "string", "example": "en" }, "translated_languages": { "type": "array", "items": { "type": "string" }, "example": [ "en" ] }, "socials": { "type": "array", "items": { "type": "object" } }, "image": { "type": "object", "nullable": true }, "cover_image": { "type": "object", "nullable": true }, "type": { "$ref": "#/components/schemas/Type" } }, "type": "object" }, "PaginatedManufacturers": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Manufacturer" } }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 15 }, "total": { "type": "integer", "example": 100 }, "last_page": { "type": "integer", "example": 7 } }, "type": "object" }, "MeemProduct": { "description": "Meem product resource", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Meem Premium Plan" }, "category": { "type": "string", "example": "Insurance", "nullable": true }, "description": { "type": "string", "example": "Comprehensive coverage plan for individuals.", "nullable": true }, "image_url": { "type": "string", "format": "url", "example": "https://example.com/images/product.jpg", "nullable": true }, "price": { "type": "number", "format": "float", "example": 199.99, "nullable": true }, "url": { "type": "string", "format": "url", "example": "https://meem.com/products/premium-plan", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "PaginatedMeemProducts": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MeemProduct" } }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 15 }, "total": { "type": "integer", "example": 30 }, "last_page": { "type": "integer", "example": 2 } }, "type": "object" }, "Message": { "properties": { "id": { "type": "integer", "example": 1 }, "conversation_id": { "type": "integer", "example": 1 }, "sender_id": { "type": "integer", "example": 10 }, "message": { "type": "string", "example": "Hello, I have a question about my order." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Order": { "properties": { "id": { "type": "integer", "example": 1 }, "tracking_number": { "type": "string", "example": "ORD-123456" }, "customer_id": { "type": "integer", "example": 10 }, "customer_contact": { "type": "string", "example": "+123456789" }, "status": { "type": "string", "example": "order-pending" }, "amount": { "type": "number", "format": "float", "example": 100 }, "sales_tax": { "type": "number", "format": "float", "example": 5 }, "paid_total": { "type": "number", "format": "float", "example": 105 }, "total": { "type": "number", "format": "float", "example": 105 }, "coupon_id": { "type": "integer", "nullable": true }, "shop_id": { "description": "If generic order, this is null. If sub-order, contains shop ID.", "type": "integer", "nullable": true }, "discount": { "type": "number", "format": "float", "example": 0 }, "payment_gateway": { "type": "string", "example": "CASH_ON_DELIVERY" }, "shipping_address": { "type": "object" }, "billing_address": { "type": "object" }, "logistics_provider": { "type": "integer", "nullable": true }, "delivery_fee": { "type": "number", "format": "float", "example": 10 }, "delivery_time": { "type": "string", "example": "Express" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "products": { "type": "array", "items": { "type": "object" } }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } }, "type": "object" }, "PaginatedOrders": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "current_page": { "type": "integer", "example": 1 }, "first_page_url": { "type": "string" }, "last_page": { "type": "integer", "example": 10 }, "per_page": { "type": "integer", "example": 15 }, "total": { "type": "integer", "example": 150 } }, "type": "object" }, "Product": { "description": "Full product details for single product view", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Hoppister Tops" }, "slug": { "type": "string", "example": "hoppister-tops" }, "description": { "type": "string", "example": "Fendi began life in 1925 as a fur and leather speciality store in Rome." }, "type_id": { "type": "integer", "example": 13 }, "price": { "type": "number", "format": "float", "example": 350, "nullable": true }, "sale_price": { "type": "number", "format": "float", "example": 300, "nullable": true }, "min_price": { "type": "number", "format": "float", "example": 20 }, "max_price": { "type": "number", "format": "float", "example": 25 }, "quantity": { "type": "integer", "example": 1000 }, "in_stock": { "type": "boolean", "example": true }, "is_taxable": { "type": "boolean", "example": false }, "status": { "type": "string", "enum": [ "draft", "publish", "approved", "rejected", "under_review" ], "example": "publish" }, "product_type": { "type": "string", "enum": [ "simple", "variable" ], "example": "variable" }, "unit": { "type": "string", "example": "1 pc" }, "sku": { "type": "string", "example": "SKU-12345", "nullable": true }, "shop_id": { "type": "integer", "example": 2 }, "height": { "type": "string", "nullable": true }, "width": { "type": "string", "nullable": true }, "length": { "type": "string", "nullable": true }, "is_digital": { "type": "boolean", "example": false }, "is_external": { "type": "boolean", "example": false }, "is_rental": { "type": "boolean", "example": false }, "ratings": { "type": "number", "format": "float", "example": 4.5 }, "total_reviews": { "type": "integer", "example": 25 }, "in_wishlist": { "type": "boolean", "example": false }, "language": { "type": "string", "example": "en" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "image": { "properties": { "id": { "type": "integer" }, "original": { "type": "string" }, "thumbnail": { "type": "string" } }, "type": "object" }, "gallery": { "type": "array", "items": { "type": "object" } }, "categories": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "type": "object" } }, "tags": { "type": "array", "items": { "type": "object" } }, "shop": { "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Urban Threads Emporium" }, "slug": { "type": "string" } }, "type": "object" }, "type": { "properties": { "id": { "type": "integer", "example": 13 }, "name": { "type": "string", "example": "Clothing" }, "slug": { "type": "string" } }, "type": "object" }, "related_products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } } }, "type": "object" }, "PaginatedProducts": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 15 }, "total": { "type": "integer", "example": 50 }, "last_page": { "type": "integer", "example": 5 } }, "type": "object" }, "Question": { "properties": { "id": { "type": "integer", "example": 1 }, "question": { "type": "string", "example": "Does this come in blue?" }, "answer": { "type": "string", "example": "Yes, it does.", "nullable": true }, "user_id": { "type": "integer", "example": 1 }, "product_id": { "type": "integer", "example": 10 }, "shop_id": { "type": "integer", "example": 2 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "product": { "$ref": "#/components/schemas/Product" }, "user": { "$ref": "#/components/schemas/User" } }, "type": "object" }, "Refund": { "properties": { "id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Damaged product" }, "description": { "type": "string", "example": "The product arrived with a broken screen." }, "images": { "type": "array", "items": { "type": "object" } }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "processing" ], "example": "pending" }, "amount": { "type": "number", "format": "float", "example": 50 }, "order_id": { "type": "integer", "example": 1 }, "customer_id": { "type": "integer", "example": 10 }, "shop_id": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "RefundPolicy": { "properties": { "id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "30-Day Return Policy" }, "slug": { "type": "string", "example": "30-day-return-policy" }, "description": { "type": "string", "example": "Detailed policy text..." }, "amount": { "type": "number", "example": 0 }, "status": { "type": "string", "example": "approved" }, "language": { "type": "string", "example": "en" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "RefundReason": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Damaged Item" }, "slug": { "type": "string", "example": "damaged-item" }, "language": { "type": "string", "example": "en" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Review": { "properties": { "id": { "type": "integer", "example": 1 }, "rating": { "type": "integer", "example": 5 }, "comment": { "type": "string", "example": "Great product!" }, "user_id": { "type": "integer", "example": 1 }, "product_id": { "type": "integer", "example": 10 }, "shop_id": { "type": "integer", "example": 2 }, "feedbacks": { "type": "array", "items": { "type": "object" } }, "images": { "type": "array", "items": { "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "user": { "$ref": "#/components/schemas/User" } }, "type": "object" }, "ShopSummary": { "description": "Shop summary for listings", "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Urban Threads Emporium" }, "slug": { "type": "string", "example": "urban-threads-emporium" }, "description": { "type": "string", "example": "Premium fashion and accessories store" }, "is_active": { "type": "boolean", "example": true }, "orders_count": { "type": "integer", "example": 150 }, "products_count": { "type": "integer", "example": 45 }, "logo": { "properties": { "id": { "type": "integer" }, "original": { "type": "string" }, "thumbnail": { "type": "string" } }, "type": "object" }, "cover_image": { "type": "object", "nullable": true } }, "type": "object" }, "Shop": { "description": "Full shop details", "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Urban Threads Emporium" }, "slug": { "type": "string", "example": "urban-threads-emporium" }, "description": { "type": "string", "example": "Premium fashion and accessories store" }, "is_active": { "type": "boolean", "example": true }, "orders_count": { "type": "integer", "example": 150 }, "products_count": { "type": "integer", "example": 45 }, "owner_id": { "type": "integer", "example": 1 }, "logo": { "type": "object", "nullable": true }, "cover_image": { "type": "object", "nullable": true }, "address": { "properties": { "street_address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" } }, "type": "object" }, "settings": { "properties": { "contact": { "type": "string" }, "website": { "type": "string" }, "location": { "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } }, "type": "object" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "owner": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "type": "object" }, "balance": { "properties": { "current_balance": { "type": "number" }, "total_earnings": { "type": "number" }, "withdrawn_amount": { "type": "number" } }, "type": "object", "nullable": true }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/CategorySummary" } } }, "type": "object" }, "PaginatedShops": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShopSummary" } }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 15 }, "total": { "type": "integer", "example": 11 } }, "type": "object" }, "StoreNotice": { "properties": { "id": { "type": "integer", "example": 1 }, "type": { "type": "string", "example": "all_vendor" }, "priority": { "type": "string", "example": "high" }, "notice": { "type": "string", "example": "System Maintenance" }, "description": { "type": "string", "example": "We will be down for 2 hours..." }, "effective_from": { "type": "string", "format": "date-time" }, "expired_at": { "type": "string", "format": "date-time" }, "is_read": { "type": "boolean", "example": false } }, "type": "object" }, "Tag": { "description": "Product tag details", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Organic" }, "slug": { "type": "string", "example": "organic" }, "details": { "type": "string", "example": "Fresh organic products", "nullable": true }, "image": { "type": "object", "nullable": true }, "icon": { "type": "string", "nullable": true }, "language": { "type": "string", "example": "en" }, "translated_languages": { "type": "array", "items": { "type": "string" }, "example": [ "en" ] }, "type": { "$ref": "#/components/schemas/Type" } }, "type": "object" }, "PaginatedTags": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 15 }, "total": { "type": "integer", "example": 50 }, "last_page": { "type": "integer", "example": 4 } }, "type": "object" }, "TermsAndConditions": { "properties": { "id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Privacy Policy" }, "slug": { "type": "string", "example": "privacy-policy" }, "description": { "type": "string", "example": "Our detailed privacy policy..." }, "shop_id": { "type": "integer", "nullable": true }, "is_approved": { "type": "boolean", "example": true }, "language": { "type": "string", "example": "en" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Type": { "description": "Product type details", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Grocery" }, "slug": { "type": "string", "example": "grocery" }, "language": { "type": "string", "example": "en" }, "translated_languages": { "type": "array", "items": { "type": "string" }, "example": [ "en" ] }, "icon": { "type": "string", "example": "FruitsVegetable", "nullable": true }, "images": { "type": "array", "items": { "type": "object" }, "nullable": true }, "banners": { "type": "array", "items": { "type": "object" } }, "promotional_sliders": { "type": "array", "items": { "type": "object" }, "nullable": true }, "settings": { "properties": { "isFullWidth": { "type": "boolean", "example": true }, "layoutType": { "type": "string", "example": "classic" } }, "type": "object" } }, "type": "object" }, "User": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "email_verified_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean", "example": true }, "shop_id": { "type": "integer", "nullable": true }, "profile": { "properties": { "avatar": { "type": "object" }, "bio": { "type": "string" }, "contact": { "type": "string" } }, "type": "object" }, "address": { "type": "array", "items": { "type": "object" } }, "permissions": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "store_owner" } }, "type": "object" } } }, "type": "object" }, "Withdraw": { "properties": { "id": { "type": "integer", "example": 1 }, "amount": { "type": "number", "format": "float", "example": 500 }, "shop_id": { "type": "integer", "example": 10 }, "payment_method": { "type": "string", "example": "bank_transfer" }, "details": { "type": "string", "example": "Bank Acct: 12345678" }, "note": { "type": "string", "example": "Monthly payout", "nullable": true }, "status": { "type": "string", "enum": [ "approved", "pending", "rejected", "processing", "on_hold" ], "example": "pending" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "shop": { "$ref": "#/components/schemas/Shop" } }, "type": "object" } }, "securitySchemes": { "sanctum": { "type": "http", "description": "Laravel Sanctum Bearer Token Authentication. Use the /token endpoint to get a token, then enter it here.", "scheme": "bearer", "bearerFormat": "sanctum" } } }, "tags": [ { "name": "Addresses", "description": "User address management" }, { "name": "AI", "description": "AI powered features - content generation and assistance" }, { "name": "Attachments", "description": "File upload and management endpoints" }, { "name": "Attributes", "description": "Product attributes management [STORE_OWNER, SUPER_ADMIN]" }, { "name": "Authors", "description": "Author management - browse and manage book authors" }, { "name": "BecameSeller", "description": "Endpoints for users to apply to become sellers" }, { "name": "Categories", "description": "Product category management - hierarchical categories with parent/child relationships" }, { "name": "Authentication", "description": "User authentication and registration endpoints [ALL ROLES]" }, { "name": "Password Management", "description": "Password reset and recovery endpoints [ALL ROLES]" }, { "name": "User Management", "description": "User management endpoints [SUPER_ADMIN, STORE_OWNER, STAFF, CUSTOMER]" }, { "name": "Staff Management", "description": "Shop staff management - add/remove staff members [STORE_OWNER]" }, { "name": "Shop Administration", "description": "Shop approval and management operations [SUPER_ADMIN]" }, { "name": "Withdrawal Management", "description": "Vendor payout requests and approval [SUPER_ADMIN, STORE_OWNER]" }, { "name": "Platform Configuration", "description": "Settings, taxes, and shipping configuration [SUPER_ADMIN]" }, { "name": "Content Moderation", "description": "Abuse reports and content approval management [SUPER_ADMIN]" }, { "name": "Puck Pages", "description": "Page builder endpoints for Puck integration [EDITOR, SUPER_ADMIN]" }, { "name": "CMS Pages", "description": "Content management system pages [EDITOR, SUPER_ADMIN]" }, { "name": "Component Data", "description": "Data endpoints for Puck page builder components (optimized for SSR)" }, { "name": "Conversations", "description": "Direct messaging between customers and shops" }, { "name": "Flash Sales", "description": "Public and admin flash sale management" }, { "name": "Manufacturers", "description": "Manufacturer/Brand management - browse and manage product brands" }, { "name": "Meem Products", "description": "Meem product catalog endpoints - browse and manage Meem integration products" }, { "name": "Messages", "description": "Messages within a conversation" }, { "name": "Orders", "description": "Order management endpoints [ALL ROLES]" }, { "name": "Products", "description": "Product catalog endpoints - browse, search, and manage products" }, { "name": "Questions", "description": "Product Q&A [STORE_OWNER, CUSTOMER]" }, { "name": "Refunds", "description": "Refund requests management" }, { "name": "Refund Policies", "description": "Public and shop-specific refund policy management" }, { "name": "Refund Reasons", "description": "Public and shop-specific refund reason management" }, { "name": "Reviews", "description": "Product Reviews [CUSTOMER, PUBLIC]" }, { "name": "Shops", "description": "Shop/store management - browse shops, follow shops, manage your own shop" }, { "name": "Tags", "description": "Product tags management - organize products with tags" }, { "name": "Terms & Conditions", "description": "Public and shop-specific terms and conditions management" }, { "name": "Types", "description": "Product types/collections management - e.g., Grocery, Bakery, Furniture" }, { "name": "Wishlist", "description": "User Wishlist management" }, { "name": "Analytics", "description": "Analytics" }, { "name": "Checkout", "description": "Checkout" }, { "name": "Coupons", "description": "Coupons" }, { "name": "FAQs", "description": "FAQs" }, { "name": "Store Notices", "description": "Store Notices" }, { "name": "Users", "description": "Users" } ] }