🛒 Ktor E-Commerce Backend

A high-performance, enterprise-grade e-commerce backend built with Kotlin & Ktor.

Documentation · Report Bug · Request Feature

🚀 Overview

Ktor-E-Commerce is a robust, scalable, and high-performance backend solution designed for modern e-commerce applications. Leveraging the power of Kotlin and Ktor, it provides an efficient service for handling complex e-commerce workflows, from multi-role authentication to advanced order processing and real-time inventory management.

Key Pillars

Performance: Built with Ktor's asynchronous engine for non-blocking I/O.
Security: JWT-based auth, rate limiting, and password complexity enforcement.
Quality: Strict static analysis with Ktlint and Detekt integrated.

Features

1. Role-Based Access Control

Customer Role: Shoppers with basic access to browse and make purchases.
Seller Role: Vendors can list products and manage their inventory.
Admin Role: Administrators have full control over the platform.

2. User Accounts and Authentication

User Registration: Allow customers to create accounts. Users can register with the same email for different roles (customer and seller).
User Authentication: Implement JWT-based authentication for user sessions.
User Profiles: Enable users to view and update their profiles.

3. Product Management

Product Listings: Create, update, and delete product listings.
Categories: Organize products into categories and brands for easy navigation.
Inventory Control: Keep track of product availability and stock levels.

4. Shopping Cart and Checkout

Shopping Cart: Add and remove products, update quantities, and calculate totals.
Checkout Summary: Retrieve detailed checkout summary with subtotal, shipping, tax, and discount breakdown.
Checkout: Streamline the checkout process with consolidated shipping address and method selection.
Stock Validation: Automatic stock validation during checkout using effective inventory levels.
Price Validation: Order totals validated against database prices to prevent tampering.
Cart Clearing: Automatic cart clearing after successful order placement.

5. Order Management

Order Processing: Handle order creation, status updates, and order history.
Order Status History: Comprehensive audit trail for every status transition (Placed, Confirmed, Shipped, etc.).
Automatic Taxation: Configurable tax calculation (default 5%) applied automatically during checkout.
Order Cancellation: Customers can cancel PENDING/CONFIRMED orders with automatic stock restoration.
Seller Orders: Sellers can view and manage orders from their shop.
Admin Orders: Admins can view all orders with advanced filters (status, date range).
Human-Readable Order Numbers: Sequential order numbers in format ORD-YYYYMMDD-XXXX.
Idempotency Support: Prevent duplicate orders with idempotency keys.
Payment Integration: Integrate with popular payment gateways for seamless transactions.
Payment Validation: Payment amounts validated against order totals.
Payment History: Track all payments for each order.

6. Discount & Coupon System

Promo Codes: Create and manage fixed or percentage-based discount coupons.
Usage Limits: Enforce expiration dates, usage limits per coupon, and minimum order amounts.
Admin Controls: Dedicated administrative interface for managing the coupon lifecycle.

7. Refund Management

Refund Requests: Customers can request refunds for order items with reasons and evidence images.
Refund Approval: Sellers and admins can approve, reject, or process refunds.
Return Shipping: Customers can mark approved refunds as shipped with tracking numbers.
Refund Tracking: Complete refund lifecycle tracking from request to resolution.

8. Scalability and Performance

Asynchronous Processing: Leverage Ktor's async capabilities for high performance.
Load Balancing: Easily scale your application to accommodate increased traffic.

9. Security

JWT Tokens: Implement JSON Web Tokens for secure authentication.
Refresh Tokens: Secure token refresh with hashed storage and automatic revocation.
Rate Limiting: Auth endpoints protected against brute-force attacks (5 req/10min).
Account Lockout: Automatic 30-minute lockout after 5 failed login attempts.
Password Strength: Enforced password complexity requirements (min 8 chars, mixed case, digit, special char).
Input Validation: Protect against common web vulnerabilities like SQL injection and cross-site scripting (XSS).
Atomic Stock Operations: Thread-safe inventory updates within database transactions.

10. Code Quality & Static Analysis

Ktlint: Automated Kotlin linting to ensure consistent code style.
Detekt: Static code analysis for finding potential bugs and code smells.
Pre-commit Hooks: Enforce quality standards before code is even committed.

Architecture

Fig. Clean Architecture

Built With 🛠

Ktor - An asynchronous framework for creating microservices, web applications, and more.
Exposed - A lightweight SQL library on top of JDBC driver for the Kotlin language.
PostgreSQL - A powerful, open-source object-relational database system.
Koin - A pragmatic lightweight dependency injection framework for Kotlin.
Ktlint - An anti-bikeshedding Kotlin linter with built-in formatter.
Detekt - A static code analysis tool for the Kotlin programming language.
Valiktor - A type-safe, powerful and extensible fluent DSL to validate objects in Kotlin.
Ktor OpenAPI/Swagger - Ktor's built-in OpenAPI generation and Swagger UI.

Requirements

Java: JDK 17 or latest
PostgreSQL: Version 12 or latest

Clone the repository

git clone [email protected]:piashcse/ktor-E-Commerce.git

Note: some installation instructions are for mac, for windows/linux please install accordingly.

Environment Configuration

This project uses DotEnv for configuration management. Follow these steps to set up your environment:

Create a .env file in the project root directory:
```
touch .env
```

Add the following variables to your .env file:

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ktor-ecommerce
DB_USER=postgres
DB_PASSWORD=p123

# Server Configuration
PORT=8080
HOST=localhost

# JWT Configuration
JWT_SECRET=your-super-secret-jwt-secret-key-change-in-production
JWT_ISSUER=ktor-ecommerce-app
JWT_AUDIENCE=ktor-ecommerce
JWT_REALM=ktor-ecommerce

# Email Configuration
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
[email protected]
EMAIL_PASSWORD=your-gmail-app-password

Update the values as needed for your environment, especially:
- Database credentials to match your PostgreSQL setup
- JWT secret with a strong, unique value for production
- Email credentials with your actual Gmail and app password

The .env file is included in .gitignore to prevent sensitive information from being committed to the repository.

Note: For email configuration, make sure to use a Gmail app password rather than your regular Gmail password. You can generate an app password in your Google Account settings under Security > 2-Step Verification > App passwords.

PgAdmin Setup

On Terminal

brew install --cask pgadmin4

Open PgAdmin

In the "Create - Server" dialog that appears, fill in the following information:

General tab:

Name: Give your server a name (e.g., "Ktor Ecommerce App")

Connection tab:

Host name/address: localhost (if your PostgreSQL server is on the same machine)
Port: 5432 (default PostgreSQL port)
Maintenance database: postgres (default database)
Username: piashcse (the user you created for your application)
Password: p123 (the password you set for piashcse)

server1

📧 SMTP Email Setup

This project uses Gmail’s SMTP service to send emails (e.g., for password recovery). The email configuration is managed through environment variables in your .env file.

🔧 SMTP Configuration

Configure your email settings in the .env file:

EMAIL_HOST: SMTP server host (e.g., smtp.gmail.com)
EMAIL_PORT: SMTP server port (e.g., 587 for TLS)
EMAIL_USERNAME: Your email address
EMAIL_PASSWORD: Your email app password

Important: Use Gmail app passwords instead of your regular Gmail password. Generate an app password in your Google Account settings under Security > 2-Step Verification > App passwords.

API Documentation & OpenAPI Specification

The application includes built-in API documentation and OpenAPI specification generation:

Accessing API Documentation

Swagger UI: Access interactive API documentation at the root / or /swagger endpoint when the application is running. The root URL automatically redirects to Swagger for easy API discovery.
Raw OpenAPI Specification: Get the OpenAPI JSON specification at /openapi endpoint.

Generating OpenAPI Specification

The static OpenAPI specification file is located at src/main/resources/openapi/openapi.json and includes documentation for all the main API endpoints.

To generate an updated OpenAPI specification file based on the current code:

./gradlew transformOpenApiJson

This will generate an updated OpenAPI specification and save it to src/main/resources/openapi/openapi.json.

Note: The OpenAPI generation feature is experimental in Ktor 3.x. The static specification file in resources provides stable documentation for all endpoints.

Run the project

On Terminal

./gradlew run

API Response Format

This API follows industry-standard patterns (Stripe, GitHub, OpenAI) for clean, predictable responses.

Success Responses

HTTP status code indicates success (200, 201, 204)
Response body contains data directly - no wrapper objects
No isSuccess or statusCode fields needed

Example (200 OK):

{
  "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
  "email": "[email protected]",
  "userType": "customer"
}

Error Responses

Standard Error (400/401/403/404/500):

{
  "message": "Invalid email or password"
}

Validation Error (400):

{
  "message": "Validation failed",
  "errors": [
    {"field": "email", "message": "Invalid email format"},
    {"field": "password", "message": "Password must be at least 8 characters with uppercase, lowercase, digit, and special character"}
  ]
}

Pagination

All collection-based endpoints support standardized pagination using limit and offset query parameters.

limit: Maximum number of items to return (default: 20)
offset: Number of items to skip (default: 0)

Paginated Response Format:

{
  "data": [
    { ... item 1 ... },
    { ... item 2 ... }
  ],
  "metadata": {
    "totalCount": 100,
    "limit": 20,
    "skip": 0
  }
}

Common Error Codes

Status Code	Description	Example Message
`400`	Bad Request	`"Invalid email address"`
`401`	Unauthorized	`"Authentication required"`
`403`	Forbidden	`"Insufficient permissions"`
`404`	Not Found	`"Product not found"`
`409`	Conflict	`"User already exists with this email"`
`410`	Gone	`"API version v0 for 'product' is no longer available"`
`500`	Internal Server Error	`"Internal server error"`

Message Constants

All error messages are centralized in Message.kt for consistency and maintainability:

Validation: Field-level validation messages
Auth: Authentication and authorization errors
Orders/Products/Shops: Domain-specific errors
General: Common error messages

This ensures consistent, actionable error messages across all endpoints.

Documentation

📖 MkDocs Documentation

Comprehensive API documentation is maintained using MkDocs and available in the docs/ directory. To view the documentation locally:

Install MkDocs: pip install mkdocs-material
Run the documentation server: mkdocs serve
Open http://localhost:8000 in your browser

🔗 API Endpoints

The API is organized into the following modules:

Authentication - Login, register, OTP, password reset
Profile - User profile management
Shop - Shop management for sellers
Product - Product catalog management
Cart - Shopping cart operations and summary
Order - Order processing, cancellation, and management
Payment - Payment processing and history
Refund Request - Refund lifecycle management
Inventory - Stock management
Wishlist - Product wishlist
Shipping - Shipping management
Review & Rating - Product reviews
Brand - Brand management
Product Category - Product categories
Shop Category - Shop categories
Privacy Policy - Policy management
Policy Consent - User consent tracking

🌐 Swagger/OpenAPI

Interactive API documentation is available via Swagger UI at http://localhost:8080/swagger when the application is running.

ROLE MANAGEMENT

Admin, Seller, Customer

Customer Role: Basic shoppers who can browse products, manage their cart, wishlist, shipping addresses, and place orders.
Seller Role: Vendors who can manage their own shops, list products, handle inventory, and manage orders and refund requests for their products.
Admin Role: Platform administrators with full access to manage all users, shops, categories, brands, coupons, shipping methods, and system-wide settings.

AUTH

POST /api/v1/auth/login

Description

Authenticate user with email, password and user type.

Security: Rate-limited to 5 requests per 10 minutes.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/auth/login' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "[email protected]",
  "password": "p123",
  "userType": "customer"
}'

Request URL

http://localhost:8080/api/v1/auth/login

Response

{
  "data": {
    "user": {
      "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
      "email": "[email protected]",
      "isVerified": true,
      "userType": "CUSTOMER",
      "isActive": true,
      "createdAt": "2024-05-06T12:00:00",
      "updatedAt": "2024-05-06T12:00:00"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "764b8a1c-9d6e-4c7b-8e1f-4a3b2c1d0e9f",
    "expiresIn": 86400,
    "tokenType": "Bearer"
  },
  "message": "Login successful"
}

POST /api/v1/auth/register

Description

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/auth/register' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "[email protected]",
  "password": "p123",
  "userType": "customer"
}'

Request URL

http://localhost:8080/api/v1/auth/register

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "email": "[email protected]",
    "message": "OTP sent to your email"
  },
  "message": "User registered successfully"
}

GET /api/v1/auth/otp-verification

Description

Verify user account or password reset with OTP.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/auth/otp-verification?userId=ce563774-d3d5-442e-ad1a-b884bb0a53f0&otp=123456' \
  -H 'accept: application/json'

Request URL

http://localhost:8080/api/v1/auth/otp-verification?userId={userId}&otp={otp}

Response

{
  "data": true,
  "message": "OTP verified successfully"
}

POST /api/v1/auth/forget-password

Description

Request password reset OTP.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/auth/forget-password' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "[email protected]",
  "userType": "customer"
}'

Request URL

http://localhost:8080/api/v1/auth/forget-password

Response

{
  "data": null,
  "message": "OTP sent to your email"
}

POST /api/v1/auth/reset-password

Description

Reset password using OTP verification.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/auth/reset-password' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "[email protected]",
  "userType": "customer",
  "verificationCode": "123456",
  "newPassword": "newPassword123!"
}'

Request URL

http://localhost:8080/api/v1/auth/reset-password

Response

{
  "data": null,
  "message": "Password changed successfully"
}

POST /api/v1/auth/refresh-token

Description

Refresh access token using refresh token.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/auth/refresh-token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "refreshToken": "764b8a1c-9d6e-4c7b-8e1f-4a3b2c1d0e9f"
}'

Request URL

http://localhost:8080/api/v1/auth/refresh-token

Response

{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "8f2a3b4c-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
    "expiresIn": 86400
  },
  "message": "Token refreshed successfully"
}

POST /api/v1/auth/logout

Description

Logout authenticated user and revoke refresh token.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/auth/logout' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "refreshToken": "764b8a1c-9d6e-4c7b-8e1f-4a3b2c1d0e9f"
}'

Request URL

http://localhost:8080/api/v1/auth/logout

Response

{
  "data": null,
  "message": "Logged out successfully"
}

PUT /api/v1/auth/change-password

Description

Change password for authenticated user.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/auth/change-password?oldPassword=p123&newPassword=newPassword123!' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/auth/change-password?oldPassword={oldPassword}&newPassword={newPassword}

Response

{
  "data": null,
  "message": "Password changed successfully"
}

PUT /api/v1/admin/auth/{userId}/change-user-type

Description

Admin: Change user role (CUSTOMER, SELLER, ADMIN).

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/admin/auth/ce563774-d3d5-442e-ad1a-b884bb0a53f0/change-user-type?userType=seller' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/auth/{userId}/change-user-type?userType={userType}

Response

{
  "data": null,
  "message": "User type updated successfully"
}

PUT /api/v1/admin/auth/{userId}/deactivate

Description

Admin: Deactivate a user account.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/admin/auth/ce563774-d3d5-442e-ad1a-b884bb0a53f0/deactivate' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/auth/{userId}/deactivate

Response

{
  "data": null,
  "message": "User deactivated successfully"
}

PUT /api/v1/admin/auth/{userId}/activate

Description

Admin: Activate a user account.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/admin/auth/ce563774-d3d5-442e-ad1a-b884bb0a53f0/activate' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/auth/{userId}/activate

Response

{
  "data": null,
  "message": "User activated successfully"
}

PROFILE

GET /api/v1/profile

Description

Retrieve the authenticated user's profile information.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/profile' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/profile

Response

{
  "data": {
    "userId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "image": "http://localhost:8080/uploads/profile/profile.jpg",
    "firstName": "John",
    "lastName": "Doe",
    "mobile": "+1234567890",
    "faxNumber": null,
    "streetAddress": "123 Main St",
    "city": "New York",
    "identificationType": "Passport",
    "identificationNo": "AB123456",
    "occupation": "Developer",
    "postCode": "10001",
    "gender": "Male"
  },
  "message": "Profile retrieved successfully"
}

PUT /api/v1/profile

Description

Update the authenticated user's profile information.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/profile?firstName=John&lastName=Doe&mobile=%2B1234567890' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/profile?firstName={firstName}&lastName={lastName}&mobile={mobile}...

Response

{
  "data": {
    "userId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "image": "http://localhost:8080/uploads/profile/profile.jpg",
    "firstName": "John",
    "lastName": "Doe",
    "mobile": "+1234567890",
    "faxNumber": null,
    "streetAddress": "123 Main St",
    "city": "New York",
    "identificationType": "Passport",
    "identificationNo": "AB123456",
    "occupation": "Developer",
    "postCode": "10001",
    "gender": "Male"
  },
  "message": "Profile updated successfully"
}

POST /api/v1/profile/image-upload

Description

Upload a profile image.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/profile/image-upload' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'image=@/path/to/image.jpg'

Request URL

http://localhost:8080/api/v1/profile/image-upload

Response

{
  "data": "http://localhost:8080/uploads/profile/profile_uuid.jpg",
  "message": "Image uploaded successfully"
}

SHOP CATEGORY

POST /api/v1/admin/shop-categories

Description

Admin: Create a new shop category.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/admin/shop-categories' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Electronics"
}'

Request URL

http://localhost:8080/api/v1/admin/shop-categories

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "name": "Electronics"
  },
  "message": "Shop category created successfully"
}

PUT /api/v1/admin/shop-categories/{id}

Description

Admin: Update an existing shop category name.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/admin/shop-categories/ce563774-d3d5-442e-ad1a-b884bb0a53f0?name=Mobile%20Phones' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/shop-categories/{id}?name={name}

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "name": "Mobile Phones"
  },
  "message": "Shop category updated successfully"
}

DELETE /api/v1/admin/shop-categories/{id}

Description

Admin: Permanently delete a shop category.

Curl

curl -X 'DELETE' \
  'http://localhost:8080/api/v1/admin/shop-categories/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/shop-categories/{id}

Response

{
  "data": true,
  "message": "Shop category deleted successfully"
}

SHOP

GET /api/v1/shops/{id}

Description

Retrieve detailed information about a specific shop.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/shops/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json'

Request URL

http://localhost:8080/api/v1/shops/{id}

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "userId": "user-uuid",
    "shopName": "Tech Hub",
    "shopDescription": "Best electronics shop",
    "shopImage": "http://localhost:8080/uploads/shop/shop.jpg",
    "shopCategory": {
      "id": "cat-uuid",
      "name": "Electronics"
    },
    "status": "ACTIVE"
  },
  "message": "Shop details retrieved"
}

GET /api/v1/shops/public

Description

Retrieve public shops with filters (status, category).

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/shops/public?status=ACTIVE&limit=10' \
  -H 'accept: application/json'

Request URL

http://localhost:8080/api/v1/shops/public?status={status}&category={category}&limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
        "shopName": "Tech Hub",
        "status": "ACTIVE"
      }
    ],
    "metadata": {
      "totalCount": 1,
      "limit": 10,
      "skip": 0
    }
  },
  "message": "Shops retrieved successfully"
}

GET /api/v1/shops/category/{categoryId}

Description

Retrieve shops by category.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/shops/category/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json'

Request URL

http://localhost:8080/api/v1/shops/category/{categoryId}?limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
        "shopName": "Tech Hub"
      }
    ],
    "metadata": {
      "totalCount": 1,
      "limit": 20,
      "skip": 0
    }
  },
  "message": "Shops retrieved successfully"
}

GET /api/v1/shops/featured

Description

Retrieve featured shops.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/shops/featured' \
  -H 'accept: application/json'

Request URL

http://localhost:8080/api/v1/shops/featured?limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
        "shopName": "Featured Shop"
      }
    ],
    "metadata": {
      "totalCount": 5,
      "limit": 20,
      "skip": 0
    }
  },
  "message": "Featured shops retrieved"
}

POST /api/v1/seller/shops

Description

Seller: Create a new shop.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/seller/shops' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <seller-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "shopName": "My New Shop",
  "shopDescription": "Selling amazing gadgets",
  "categoryId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0"
}'

Request URL

http://localhost:8080/api/v1/seller/shops

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "shopName": "My New Shop",
    "status": "PENDING"
  },
  "message": "Shop created successfully and pending approval"
}

GET /api/v1/seller/shops

Description

Seller: Retrieve owned shops.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/seller/shops' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <seller-token>'

Request URL

http://localhost:8080/api/v1/seller/shops?limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
        "shopName": "My New Shop"
      }
    ],
    "metadata": {
      "totalCount": 1,
      "limit": 20,
      "skip": 0
    }
  },
  "message": "Shops retrieved"
}

PUT /api/v1/seller/shops/{id}

Description

Seller: Update shop details.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/seller/shops/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <seller-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "shopName": "Updated Shop Name",
  "shopDescription": "New description"
}'

Request URL

http://localhost:8080/api/v1/seller/shops/{id}

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "shopName": "Updated Shop Name"
  },
  "message": "Shop updated successfully"
}

PUT /api/v2/seller/shops/{shopId}

Description

Seller: Update shop details with optimized response.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v2/seller/shops/ce563774-d3d5-442e-ad1a-b884bb0a53f0?source=mobile' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <seller-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "shopName": "V2 Updated Name"
}'

Request URL

http://localhost:8080/api/v2/seller/shops/{shopId}?source={source}

Response

{
  "data": {
    "v2_data": {
      "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
      "shopName": "V2 Updated Name"
    },
    "source": "mobile"
  },
  "message": "Shop updated (V2)"
}

GET /api/v1/admin/shops/status

Description

Admin: Retrieve shops filtered by status.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/admin/shops/status?status=PENDING' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/shops/status?status={status}&limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
        "shopName": "Pending Shop"
      }
    ],
    "metadata": {
      "totalCount": 3,
      "limit": 20,
      "skip": 0
    }
  },
  "message": "Shops retrieved"
}

PUT /api/v1/admin/shops/approve/{id}

Description

Admin: Approve a pending shop application.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/admin/shops/approve/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/shops/approve/{id}

Response

{
  "data": true,
  "message": "Shop approved successfully"
}

PUT /api/v1/admin/shops/reject/{id}

Description

Admin: Reject a shop application.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/admin/shops/reject/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/shops/reject/{id}

Response

{
  "data": true,
  "message": "Shop application rejected"
}

PUT /api/v1/admin/shops/suspend/{id}

Description

Admin: Suspend an active shop.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/admin/shops/suspend/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/shops/suspend/{id}

Response

{
  "data": true,
  "message": "Shop suspended"
}

PUT /api/v1/admin/shops/activate/{id}

Description

Admin: Activate a suspended shop.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/admin/shops/activate/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/shops/activate/{id}

Response

{
  "data": true,
  "message": "Shop activated"
}

BRAND

GET /api/v1/brands

Description

Retrieve a paginated list of all brands.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/brands?limit=20&offset=0' \
  -H 'accept: application/json'

Request URL

http://localhost:8080/api/v1/brands?limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
        "name": "Samsung"
      }
    ],
    "metadata": {
      "totalCount": 50,
      "limit": 20,
      "skip": 0
    }
  },
  "message": "Brands retrieved"
}

POST /api/v1/admin/brands

Description

Admin: Create a new brand.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/admin/brands' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Apple"
}'

Request URL

http://localhost:8080/api/v1/admin/brands

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "name": "Apple"
  },
  "message": "Brand created successfully"
}

PUT /api/v1/admin/brands/{id}

Description

Admin: Update an existing brand.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/admin/brands/ce563774-d3d5-442e-ad1a-b884bb0a53f0?name=Apple%20Inc' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/brands/{id}?name={name}

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "name": "Apple Inc"
  },
  "message": "Brand updated successfully"
}

DELETE /api/v1/admin/brands/{id}

Description

Admin: Delete a brand.

Curl

curl -X 'DELETE' \
  'http://localhost:8080/api/v1/admin/brands/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/brands/{id}

Response

{
  "data": true,
  "message": "Brand deleted successfully"
}

PRODUCT CATEGORY

GET /api/v1/product-categories

Description

Retrieve a paginated list of all product categories.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/product-categories?limit=20&offset=0' \
  -H 'accept: application/json'

Request URL

http://localhost:8080/api/v1/product-categories?limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
        "name": "Smartphones"
      }
    ],
    "metadata": {
      "totalCount": 15,
      "limit": 20,
      "skip": 0
    }
  },
  "message": "Categories retrieved"
}

POST /api/v1/admin/product-categories

Description

Admin: Create a new product category.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/admin/product-categories?name=Laptops' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/product-categories?name={name}

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "name": "Laptops"
  },
  "message": "Category created successfully"
}

PUT /api/v1/admin/product-categories/{id}

Description

Admin: Update an existing product category.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/admin/product-categories/ce563774-d3d5-442e-ad1a-b884bb0a53f0?name=Gaming%20Laptops' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/product-categories/{id}?name={name}

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "name": "Gaming Laptops"
  },
  "message": "Category updated successfully"
}

DELETE /api/v1/admin/product-categories/{id}

Description

Admin: Permanently delete a product category.

Curl

curl -X 'DELETE' \
  'http://localhost:8080/api/v1/admin/product-categories/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/product-categories/{id}

Response

{
  "data": true,
  "message": "Category deleted successfully"
}

PRODUCT SUB CATEGORY

GET /api/v1/product-subcategories

Description

Retrieve subcategories for a specific category (require categoryId).

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/product-subcategories?categoryId=ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json'

Request URL

http://localhost:8080/api/v1/product-subcategories?categoryId={categoryId}&limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "id": "sub-uuid",
        "categoryId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
        "name": "Android Phones"
      }
    ],
    "metadata": {
      "totalCount": 5,
      "limit": 20,
      "skip": 0
    }
  },
  "message": "Subcategories retrieved"
}

POST /api/v1/admin/product-subcategories

Description

Admin: Create a new product subcategory.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/admin/product-subcategories' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "categoryId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
  "name": "iPhones"
}'

Request URL

http://localhost:8080/api/v1/admin/product-subcategories

Response

{
  "data": {
    "id": "sub-uuid",
    "categoryId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "name": "iPhones"
  },
  "message": "Subcategory created successfully"
}

PUT /api/v1/admin/product-subcategories/{id}

Description

Admin: Update an existing product subcategory name.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/admin/product-subcategories/sub-uuid?name=Apple%20iPhones' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/product-subcategories/{id}?name={name}

Response

{
  "data": {
    "id": "sub-uuid",
    "name": "Apple iPhones"
  },
  "message": "Subcategory updated successfully"
}

DELETE /api/v1/admin/product-subcategories/{id}

Description

Admin: Permanently delete a product subcategory.

Curl

curl -X 'DELETE' \
  'http://localhost:8080/api/v1/admin/product-subcategories/sub-uuid' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/product-subcategories/{id}

Response

{
  "data": true,
  "message": "Subcategory deleted successfully"
}

PRODUCT

GET /api/v1/products/{id}

Description

Retrieve detailed information about a specific product.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/products/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json'

Request URL

http://localhost:8080/api/v1/products/{id}

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "name": "Galaxy S24",
    "productDescription": "Latest flagship phone",
    "productPrice": 999.99,
    "productStock": 50,
    "productImage": "http://localhost:8080/uploads/product/s24.jpg",
    "categoryId": "cat-uuid",
    "subCategoryId": "sub-uuid",
    "brandId": "brand-uuid"
  },
  "message": "Product details retrieved"
}

GET /api/v1/products

Description

Retrieve a paginated list of products with optional filters.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/products?maxPrice=1000&sortBy=price&sortOrder=asc' \
  -H 'accept: application/json'

Request URL

http://localhost:8080/api/v1/products?maxPrice={maxPrice}&minPrice={minPrice}&categoryId={categoryId}&subCategoryId={subCategoryId}&brandId={brandId}&sortBy={sortBy}&sortOrder={sortOrder}&limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
        "name": "Galaxy S24",
        "productPrice": 999.99
      }
    ],
    "metadata": {
      "totalCount": 100,
      "limit": 10,
      "skip": 0
    }
  },
  "message": "Products retrieved"
}

GET /api/v1/products/search

Description

Search for products by name.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/products/search?name=Galaxy' \
  -H 'accept: application/json'

Request URL

http://localhost:8080/api/v1/products/search?name={name}&limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
        "name": "Galaxy S24"
      }
    ],
    "metadata": {
      "totalCount": 10,
      "limit": 10,
      "skip": 0
    }
  },
  "message": "Search results retrieved"
}

GET /api/v1/seller/products

Description

Seller: Retrieve seller products with filters.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/seller/products' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <seller-token>'

Request URL

http://localhost:8080/api/v1/seller/products?limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
        "name": "Galaxy S24"
      }
    ],
    "metadata": {
      "totalCount": 5,
      "limit": 10,
      "skip": 0
    }
  },
  "message": "Seller products retrieved"
}

POST /api/v1/seller/products

Description

Seller: Add a new product listing.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/seller/products' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <seller-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "New Product",
  "productDescription": "Description",
  "productPrice": 199.99,
  "productStock": 100,
  "categoryId": "cat-uuid",
  "subCategoryId": "sub-uuid",
  "brandId": "brand-uuid"
}'

Request URL

http://localhost:8080/api/v1/seller/products

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "name": "New Product"
  },
  "message": "Product created successfully"
}

PUT /api/v1/seller/products/{id}

Description

Seller: Update an existing product listing.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/seller/products/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <seller-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "productPrice": 189.99
}'

Request URL

http://localhost:8080/api/v1/seller/products/{id}

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "productPrice": 189.99
  },
  "message": "Product updated successfully"
}

DELETE /api/v1/seller/products/{id}

Description

Seller: Permanently delete a product listing.

Curl

curl -X 'DELETE' \
  'http://localhost:8080/api/v1/seller/products/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <seller-token>'

Request URL

http://localhost:8080/api/v1/seller/products/{id}

Response

{
  "data": true,
  "message": "Product deleted successfully"
}

POST /api/v1/seller/products/image-upload

Description

Seller: Upload a product image.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/seller/products/image-upload' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <seller-token>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'image=@/path/to/product.jpg'

Request URL

http://localhost:8080/api/v1/seller/products/image-upload

Response

{
  "data": "http://localhost:8080/uploads/product/prod_uuid.jpg",
  "message": "Product image uploaded"
}

DELETE /api/v1/admin/products/{id}

Description

Admin: Permanently delete any product.

Curl

curl -X 'DELETE' \
  'http://localhost:8080/api/v1/admin/products/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/products/{id}

Response

{
  "data": true,
  "message": "Product deleted by admin"
}

REVIEW RATING

GET /api/v1/reviews

Description

Retrieve reviews and ratings for a specific product.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/reviews?productId=ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json'

Request URL

http://localhost:8080/api/v1/reviews?productId={productId}&limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "id": "review-uuid",
        "userId": "user-uuid",
        "productId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
        "review": "Excellent product!",
        "rating": 5,
        "createdAt": "2024-05-06T12:00:00"
      }
    ],
    "metadata": {
      "totalCount": 1,
      "limit": 20,
      "skip": 0
    }
  },
  "message": "Reviews retrieved successfully"
}

POST /api/v1/reviews

Description

Submit a new review and rating for a product.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/reviews' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "productId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
  "review": "Very good product",
  "rating": 4
}'

Request URL

http://localhost:8080/api/v1/reviews

Response

{
  "data": {
    "id": "review-uuid",
    "review": "Very good product",
    "rating": 4
  },
  "message": "Review submitted successfully"
}

PUT /api/v1/reviews/{id}

Description

Update an existing review and rating.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/reviews/review-uuid?review=Updated%20review&rating=5' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/reviews/{id}?review={review}&rating={rating}

Response

{
  "data": {
    "id": "review-uuid",
    "review": "Updated review",
    "rating": 5
  },
  "message": "Review updated successfully"
}

DELETE /api/v1/reviews/{id}

Description

Delete a review and rating.

Curl

curl -X 'DELETE' \
  'http://localhost:8080/api/v1/reviews/review-uuid' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/reviews/{id}

Response

{
  "data": true,
  "message": "Review deleted successfully"
}

CART

POST /api/v1/carts

Description

Add an item to the authenticated user's cart.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/carts' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "productId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
  "quantity": 2
}'

Request URL

http://localhost:8080/api/v1/carts

Response

{
  "data": {
    "productId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "quantity": 2
  },
  "message": "Item added to cart"
}

GET /api/v1/carts

Description

Retrieve all items in the authenticated user's cart.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/carts' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/carts?limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "productId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
        "quantity": 2,
        "productName": "Galaxy S24",
        "price": 999.99
      }
    ],
    "metadata": {
      "totalCount": 1,
      "limit": 20,
      "skip": 0
    }
  },
  "message": "Cart items retrieved"
}

PUT /api/v1/carts/update

Description

Update the quantity of an item in the cart.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/carts/update' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "productId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
  "quantity": 5
}'

Request URL

http://localhost:8080/api/v1/carts/update

Response

{
  "data": {
    "productId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "quantity": 5
  },
  "message": "Cart quantity updated"
}

DELETE /api/v1/carts/remove

Description

Remove a specific item from the cart (require productId).

Curl

curl -X 'DELETE' \
  'http://localhost:8080/api/v1/carts/remove?productId=ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/carts/remove?productId={productId}

Response

{
  "data": true,
  "message": "Item removed from cart"
}

DELETE /api/v1/carts/all

Description

Remove all items from the authenticated user's cart.

Curl

curl -X 'DELETE' \
  'http://localhost:8080/api/v1/carts/all' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/carts/all

Response

{
  "data": true,
  "message": "Cart cleared successfully"
}

GET /api/v1/carts/summary

Description

Retrieve a summary of the cart (totals, counts).

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/carts/summary' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/carts/summary

Response

{
  "data": {
    "totalItems": 2,
    "subTotal": 1999.98,
    "shipping": 10.00,
    "tax": 99.99,
    "total": 2109.97
  },
  "message": "Cart summary retrieved"
}

WISHLIST

POST /api/v1/wishlists

Description

Add a product to the authenticated user's wishlist.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/wishlists' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "productId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0"
}'

Request URL

http://localhost:8080/api/v1/wishlists

Response

{
  "data": {
    "productId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0"
  },
  "message": "Added to wishlist"
}

GET /api/v1/wishlists

Description

Retrieve all items in the user's wishlist.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/wishlists' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/wishlists?limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "productId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
        "productName": "Galaxy S24",
        "price": 999.99
      }
    ],
    "metadata": {
      "totalCount": 1,
      "limit": 20,
      "skip": 0
    }
  },
  "message": "Wishlist retrieved"
}

DELETE /api/v1/wishlists/remove

Description

Remove a specific product from the wishlist.

Curl

curl -X 'DELETE' \
  'http://localhost:8080/api/v1/wishlists/remove?productId=ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/wishlists/remove?productId={productId}

Response

{
  "data": true,
  "message": "Removed from wishlist"
}

GET /api/v1/wishlists/check

Description

Check if a specific product is in the user's wishlist.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/wishlists/check?productId=ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/wishlists/check?productId={productId}

Response

{
  "data": true,
  "message": "Product is in wishlist"
}

CHECKOUT

POST /api/v1/checkout/shipping-address

Description

Add a new shipping address for the authenticated user.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/checkout/shipping-address' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "addressName": "Home",
  "firstName": "John",
  "lastName": "Doe",
  "mobile": "+1234567890",
  "streetAddress": "123 Main St",
  "city": "New York",
  "postCode": "10001",
  "country": "USA"
}'

Request URL

http://localhost:8080/api/v1/checkout/shipping-address

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "addressName": "Home",
    "city": "New York"
  },
  "message": "Shipping address added"
}

GET /api/v1/checkout/shipping-address

Description

Retrieve all shipping addresses for the authenticated user.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/checkout/shipping-address' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/checkout/shipping-address

Response

{
  "data": [
    {
      "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
      "addressName": "Home",
      "streetAddress": "123 Main St"
    }
  ],
  "message": "Shipping addresses retrieved"
}

PUT /api/v1/checkout/shipping-address/{id}

Description

Update an existing shipping address.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/checkout/shipping-address/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "addressName": "Office"
}'

Request URL

http://localhost:8080/api/v1/checkout/shipping-address/{id}

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "addressName": "Office"
  },
  "message": "Shipping address updated"
}

DELETE /api/v1/checkout/shipping-address/{id}

Description

Delete a shipping address.

Curl

curl -X 'DELETE' \
  'http://localhost:8080/api/v1/checkout/shipping-address/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/checkout/shipping-address/{id}

Response

{
  "data": true,
  "message": "Shipping address deleted"
}

GET /api/v1/checkout/shipping-method

Description

Retrieve all available shipping methods.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/checkout/shipping-method' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/checkout/shipping-method

Response

{
  "data": [
    {
      "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
      "name": "Express Shipping",
      "price": 15.00
    }
  ],
  "message": "Shipping methods retrieved"
}

POST /api/v1/checkout/summary

Description

Get a summary of the checkout (totals) without placing an order.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/checkout/summary' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "shippingAddressId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
  "shippingMethodId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
  "couponCode": "SUMMER20"
}'

Request URL

http://localhost:8080/api/v1/checkout/summary

Response

{
  "data": {
    "subTotal": 1999.98,
    "shipping": 15.00,
    "tax": 99.99,
    "discount": 200.00,
    "total": 1914.97
  },
  "message": "Checkout summary generated"
}

POST /api/v1/checkout/place-order

Description

Place a new order from the cart.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/checkout/place-order' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "shippingAddressId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
  "shippingMethodId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
  "paymentMethod": "STRIPE"
}'

Request URL

http://localhost:8080/api/v1/checkout/place-order

Response

{
  "data": {
    "orderId": "ORD-20240506-ABCD",
    "total": 1914.97,
    "status": "PLACED"
  },
  "message": "Order placed successfully"
}

ORDER

GET /api/v1/orders

Description

Retrieve all orders for the authenticated customer.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/orders?limit=10&offset=0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/orders?limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "id": "ORD-20240506-ABCD",
        "total": 1914.97,
        "status": "PLACED",
        "createdAt": "2024-05-06T12:00:00"
      }
    ],
    "metadata": {
      "totalCount": 1,
      "limit": 10,
      "skip": 0
    }
  },
  "message": "Orders retrieved"
}

PATCH /api/v1/orders/status/{id}

Description

Update order status (Customer: CANCELED/RECEIVED, Seller: CONFIRMED/DELIVERED).

Curl

curl -X 'PATCH' \
  'http://localhost:8080/api/v1/orders/status/ORD-20240506-ABCD?status=canceled' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/orders/status/{id}?status={status}

Response

{
  "data": {
    "id": "ORD-20240506-ABCD",
    "status": "CANCELED"
  },
  "message": "Order status updated"
}

POST /api/v1/orders/{id}/cancel

Description

Cancel an order.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/orders/ORD-20240506-ABCD/cancel' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "reason": "Changed my mind"
}'

Request URL

http://localhost:8080/api/v1/orders/{id}/cancel

Response

{
  "data": true,
  "message": "Order cancelled successfully"
}

GET /api/v1/seller/orders

Description

Seller: Retrieve orders for the seller's shop.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/seller/orders?status=PLACED' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <seller-token>'

Request URL

http://localhost:8080/api/v1/seller/orders?status={status}&limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "id": "ORD-20240506-ABCD",
        "total": 1914.97,
        "status": "PLACED"
      }
    ],
    "metadata": {
      "totalCount": 1,
      "limit": 10,
      "skip": 0
    }
  },
  "message": "Seller orders retrieved"
}

PATCH /api/v1/admin/orders/status/{id}

Description

Admin: Update the status of any order.

Curl

curl -X 'PATCH' \
  'http://localhost:8080/api/v1/admin/orders/status/ORD-20240506-ABCD?status=shipped' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/orders/status/{id}?status={status}

Response

{
  "data": {
    "id": "ORD-20240506-ABCD",
    "status": "SHIPPED"
  },
  "message": "Order status updated by admin"
}

POST /api/v1/admin/orders/{id}/cancel

Description

Admin: Cancel any order.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/admin/orders/ORD-20240506-ABCD/cancel' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "reason": "Fraudulent activity"
}'

Request URL

http://localhost:8080/api/v1/admin/orders/{id}/cancel

Response

{
  "data": true,
  "message": "Order cancelled by admin"
}

GET /api/v1/admin/orders

Description

Admin: Retrieve all orders with advanced filtering (status, startDate, endDate).

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/admin/orders?status=PLACED&startDate=2024-05-01T00:00:00Z' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/orders?status={status}&startDate={startDate}&endDate={endDate}&limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "id": "ORD-20240506-ABCD",
        "status": "PLACED"
      }
    ],
    "metadata": {
      "totalCount": 10,
      "limit": 10,
      "skip": 0
    }
  },
  "message": "All orders retrieved"
}

PAYMENT

POST /api/v1/payments

Description

Create a new payment record for an order.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/payments' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "orderId": "ORD-20240506-ABCD",
  "transactionId": "TXN-123456",
  "paymentMethod": "STRIPE",
  "amount": 1914.97,
  "status": "SUCCESS"
}'

Request URL

http://localhost:8080/api/v1/payments

Response

{
  "data": {
    "id": "pay-uuid",
    "orderId": "ORD-20240506-ABCD",
    "status": "SUCCESS"
  },
  "message": "Payment recorded"
}

GET /api/v1/payments/{id}

Description

Retrieve payment details by ID.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/payments/pay-uuid' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/payments/{id}

Response

{
  "data": {
    "id": "pay-uuid",
    "orderId": "ORD-20240506-ABCD",
    "amount": 1914.97,
    "status": "SUCCESS"
  },
  "message": "Payment details retrieved"
}

GET /api/v1/payments/order/{orderId}

Description

Retrieve all payments for a specific order.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/payments/order/ORD-20240506-ABCD' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/payments/order/{orderId}

Response

{
  "data": {
    "data": [
      {
        "id": "pay-uuid",
        "amount": 1914.97,
        "status": "SUCCESS"
      }
    ],
    "metadata": {
      "totalCount": 1,
      "limit": 20,
      "skip": 0
    }
  },
  "message": "Payments retrieved"
}

PRIVACY POLICY

GET /api/v1/policies/{policyType}

Description

Retrieve the latest active version of a policy by type.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/policies/privacy_policy' \
  -H 'accept: application/json'

Request URL

http://localhost:8080/api/v1/policies/{policyType}

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "policyType": "PRIVACY_POLICY",
    "content": "Our privacy policy content...",
    "version": "1.0",
    "isActive": true
  },
  "message": "Policy retrieved successfully"
}

POST /api/v1/admin/policies

Description

Admin: Create a new policy document or new version.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/admin/policies' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "policyType": "PRIVACY_POLICY",
  "content": "Updated privacy policy content...",
  "version": "1.1"
}'

Request URL

http://localhost:8080/api/v1/admin/policies

Response

{
  "data": {
    "id": "new-policy-uuid",
    "version": "1.1"
  },
  "message": "Policy version created"
}

GET /api/v1/admin/policies/{policyType}/history

Description

Admin: Retrieve all versions of a specific policy type.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/admin/policies/privacy_policy/history' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/policies/{policyType}/history

Response

{
  "data": [
    {
      "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
      "version": "1.0",
      "isActive": false
    },
    {
      "id": "new-policy-uuid",
      "version": "1.1",
      "isActive": true
    }
  ],
  "message": "Policy history retrieved"
}

PRIVACY POLICY CONSENT

POST /api/v1/policy-consents/consent

Description

Record user consent for a specific policy document.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/policy-consents/consent' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "policyId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0"
}'

Request URL

http://localhost:8080/api/v1/policy-consents/consent

Response

{
  "data": {
    "id": "consent-uuid",
    "policyId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "consentedAt": "2024-05-06T12:00:00"
  },
  "message": "Consent recorded successfully"
}

GET /api/v1/policy-consents

Description

Retrieve all consent records for the authenticated user.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/policy-consents' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/policy-consents

Response

{
  "data": [
    {
      "id": "consent-uuid",
      "policyType": "PRIVACY_POLICY",
      "consentedAt": "2024-05-06T12:00:00"
    }
  ],
  "message": "User consents retrieved"
}

GET /api/v1/policy-consents/{policyType}

Description

Check if the user has consented to a specific policy type.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/policy-consents/privacy_policy' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/policy-consents/{policyType}

Response

{
  "data": {
    "hasConsented": true
  },
  "message": "Consent status retrieved"
}

REFUND REQUEST

POST /api/v1/refund-requests/{orderId}

Description

Create a refund request for an order item.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/refund-requests/ORD-20240506-ABCD' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "productId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
  "reason": "Damaged product",
  "quantity": 1
}'

Request URL

http://localhost:8080/api/v1/refund-requests/{orderId}

Response

{
  "data": {
    "id": "refund-uuid",
    "status": "PENDING"
  },
  "message": "Refund request submitted"
}

POST /api/v1/refund-requests/{id}/ship

Description

Mark an approved refund as shipped.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/refund-requests/refund-uuid/ship' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "trackingNumber": "TRK123456",
  "courierName": "FedEx"
}'

Request URL

http://localhost:8080/api/v1/refund-requests/{id}/ship

Response

{
  "data": true,
  "message": "Refund shipment recorded"
}

GET /api/v1/refund-requests/order/{orderId}

Description

Get refund requests for an order.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/refund-requests/order/ORD-20240506-ABCD' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/refund-requests/order/{orderId}

Response

{
  "data": {
    "data": [
      {
        "id": "refund-uuid",
        "status": "PENDING"
      }
    ],
    "metadata": {
      "totalCount": 1,
      "limit": 10,
      "skip": 0
    }
  },
  "message": "Refund requests retrieved"
}

GET /api/v1/refund-requests/{id}

Description

Get refund request details.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/refund-requests/refund-uuid' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Request URL

http://localhost:8080/api/v1/refund-requests/{id}

Response

{
  "data": {
    "id": "refund-uuid",
    "orderId": "ORD-20240506-ABCD",
    "reason": "Damaged product",
    "status": "PENDING"
  },
  "message": "Refund details retrieved"
}

PUT /api/v1/seller/refund-requests/{id}/status

Description

Seller: Update refund request status.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/seller/refund-requests/refund-uuid/status' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <seller-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "status": "APPROVED",
  "comment": "Returning approved"
}'

Request URL

http://localhost:8080/api/v1/seller/refund-requests/{id}/status

Response

{
  "data": {
    "id": "refund-uuid",
    "status": "APPROVED"
  },
  "message": "Refund status updated by seller"
}

GET /api/v1/admin/refund-requests/order/{orderId}

Description

Admin: Get all refund requests for an order.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/admin/refund-requests/order/ORD-20240506-ABCD' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/refund-requests/order/{orderId}

Response

{
  "data": {
    "data": [
      {
        "id": "refund-uuid",
        "status": "APPROVED"
      }
    ],
    "metadata": {
      "totalCount": 1,
      "limit": 10,
      "skip": 0
    }
  },
  "message": "Refund requests retrieved by admin"
}

PUT /api/v1/admin/refund-requests/{id}/status

Description

Admin: Update refund status.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/admin/refund-requests/refund-uuid/status' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "status": "REFUNDED"
}'

Request URL

http://localhost:8080/api/v1/admin/refund-requests/{id}/status

Response

{
  "data": {
    "id": "refund-uuid",
    "status": "REFUNDED"
  },
  "message": "Refund status updated by admin"
}

COUPON

GET /api/v1/coupons/{code}

Description

Retrieve detailed information about a coupon by its code.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/coupons/SUMMER20' \
  -H 'accept: application/json'

Request URL

http://localhost:8080/api/v1/coupons/{code}

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "code": "SUMMER20",
    "discountType": "PERCENTAGE",
    "discountValue": 20.0,
    "minOrderAmount": 50.0,
    "expiryDate": "2024-09-01T00:00:00Z"
  },
  "message": "Coupon details retrieved"
}

POST /api/v1/admin/coupons

Description

Admin: Create a new discount coupon.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/admin/coupons' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "NEWYEAR25",
  "discountType": "FIXED",
  "discountValue": 10.0,
  "minOrderAmount": 30.0,
  "expiryDate": "2025-01-31T23:59:59Z"
}'

Request URL

http://localhost:8080/api/v1/admin/coupons

Response

{
  "data": {
    "id": "new-coupon-uuid",
    "code": "NEWYEAR25"
  },
  "message": "Coupon created successfully"
}

GET /api/v1/admin/coupons

Description

Admin: Retrieve a list of all coupons.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/admin/coupons?limit=10&offset=0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/coupons?limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
        "code": "SUMMER20"
      }
    ],
    "metadata": {
      "totalCount": 5,
      "limit": 10,
      "skip": 0
    }
  },
  "message": "Coupons retrieved"
}

PUT /api/v1/admin/coupons/{id}

Description

Admin: Update an existing coupon.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/admin/coupons/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "discountValue": 25.0
}'

Request URL

http://localhost:8080/api/v1/admin/coupons/{id}

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "discountValue": 25.0
  },
  "message": "Coupon updated successfully"
}

DELETE /api/v1/admin/coupons/{id}

Description

Admin: Delete a coupon.

Curl

curl -X 'DELETE' \
  'http://localhost:8080/api/v1/admin/coupons/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/coupons/{id}

Response

{
  "data": true,
  "message": "Coupon deleted successfully"
}

INVENTORY

POST /api/v1/seller/inventories

Description

Seller: Initialize or update inventory for a product.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/seller/inventories' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <seller-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "productId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
  "quantity": 100,
  "lowStockThreshold": 10
}'

Request URL

http://localhost:8080/api/v1/seller/inventories

Response

{
  "data": {
    "productId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "quantity": 100
  },
  "message": "Inventory updated"
}

PUT /api/v1/seller/inventories/stock/{productId}

Description

Seller: Update stock quantity.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/seller/inventories/stock/ce563774-d3d5-442e-ad1a-b884bb0a53f0?quantity=10&operation=add' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <seller-token>'

Request URL

http://localhost:8080/api/v1/seller/inventories/stock/{productId}?quantity={quantity}&operation={operation}

Response

{
  "data": {
    "productId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "newQuantity": 110
  },
  "message": "Stock quantity updated"
}

GET /api/v1/seller/inventories/product/{productId}

Description

Seller: Retrieve inventory item details by product ID.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/seller/inventories/product/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <seller-token>'

Request URL

http://localhost:8080/api/v1/seller/inventories/product/{productId}

Response

{
  "data": {
    "productId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "quantity": 110,
    "lowStockThreshold": 10
  },
  "message": "Inventory details retrieved"
}

GET /api/v1/seller/inventories/shop/{shopId}

Description

Seller: Retrieve all inventory items for a shop.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/seller/inventories/shop/shop-uuid' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <seller-token>'

Request URL

http://localhost:8080/api/v1/seller/inventories/shop/{shopId}?limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "productId": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
        "quantity": 110
      }
    ],
    "metadata": {
      "totalCount": 15,
      "limit": 10,
      "skip": 0
    }
  },
  "message": "Shop inventory retrieved"
}

GET /api/v1/seller/inventories/low-stock

Description

Seller: Retrieve items with stock below a threshold.

Curl

curl -X 'GET' \
  'http://localhost:8080/api/v1/seller/inventories/low-stock' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <seller-token>'

Request URL

http://localhost:8080/api/v1/seller/inventories/low-stock?limit={limit}&offset={offset}

Response

{
  "data": {
    "data": [
      {
        "productId": "low-stock-prod-uuid",
        "quantity": 2
      }
    ],
    "metadata": {
      "totalCount": 1,
      "limit": 10,
      "skip": 0
    }
  },
  "message": "Low stock items retrieved"
}

SHIPPING METHOD

POST /api/v1/admin/shipping-methods

Description

Admin: Create a new shipping method.

Curl

curl -X 'POST' \
  'http://localhost:8080/api/v1/admin/shipping-methods' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Standard Shipping",
  "price": 5.00,
  "estimatedDays": "3-5 days"
}'

Request URL

http://localhost:8080/api/v1/admin/shipping-methods

Response

{
  "data": {
    "id": "new-shipping-uuid",
    "name": "Standard Shipping"
  },
  "message": "Shipping method created"
}

PUT /api/v1/admin/shipping-methods/{id}

Description

Admin: Update an existing shipping method.

Curl

curl -X 'PUT' \
  'http://localhost:8080/api/v1/admin/shipping-methods/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "price": 7.50
}'

Request URL

http://localhost:8080/api/v1/admin/shipping-methods/{id}

Response

{
  "data": {
    "id": "ce563774-d3d5-442e-ad1a-b884bb0a53f0",
    "price": 7.50
  },
  "message": "Shipping method updated"
}

DELETE /api/v1/admin/shipping-methods/{id}

Description

Admin: Delete a shipping method.

Curl

curl -X 'DELETE' \
  'http://localhost:8080/api/v1/admin/shipping-methods/ce563774-d3d5-442e-ad1a-b884bb0a53f0' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <admin-token>'

Request URL

http://localhost:8080/api/v1/admin/shipping-methods/{id}

Response

{
  "data": true,
  "message": "Shipping method deleted"
}

👨 Developed By

Mehedi Hassan Piash

License


Copyright 2023 piashcse (Mehedi Hassan Piash)

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

ktor-E-Commerce

About ktor-E-Commerce

Platforms

Languages

Links

README.md

🛒 Ktor E-Commerce Backend

Documentation · Report Bug · Request Feature

🚀 Overview

Key Pillars

Features

1. Role-Based Access Control

2. User Accounts and Authentication

3. Product Management

4. Shopping Cart and Checkout

5. Order Management

6. Discount & Coupon System

7. Refund Management

8. Scalability and Performance

9. Security

10. Code Quality & Static Analysis

Architecture

Built With 🛠

Requirements

Clone the repository

Environment Configuration

PgAdmin Setup

📧 SMTP Email Setup

🔧 SMTP Configuration

API Documentation & OpenAPI Specification

Accessing API Documentation

Generating OpenAPI Specification

Run the project

API Response Format

Success Responses

Error Responses

Pagination

Common Error Codes

Message Constants

Documentation

📖 MkDocs Documentation

🔗 API Endpoints

🌐 Swagger/OpenAPI

ROLE MANAGEMENT

AUTH

Description

Curl

Request URL

Response

Description

Curl

Request URL

Response

Description

Curl

Request URL

Response

Description

Curl

Request URL

Response

Description

Curl

Request URL

Response

Description

Curl

Request URL

Response

Description

Curl

Request URL

Response

Description

Curl

Request URL

Response

Description

Curl

Request URL