Cart Management
Author: NextGate Development Team, Backend Engineering Last Updated: 2025-09-22 Version: v1.0
Short Description: The Cart Management API provides comprehensive shopping cart functionality for the NexGate e-commerce platform. It allows users to manage their shopping cart items, including adding products, updating quantities, and calculating totals with real-time pricing and discount information.
Hints:
All endpoints require user authentication via Bearer token
Cart is automatically initialized for new users on first interaction
Real-time stock validation prevents overselling
Prices and discounts are calculated dynamically based on current product data
Maximum quantity per item is limited by available stock
Cart items are sorted by creation date (newest first)
Endpoints
1. Initialize Cart
Purpose: Creates a new shopping cart for the authenticated user or returns existing cart
Endpoint: POST /api/v1/cart/initialize
Access Level: 🔒 Protected (Requires Authentication)
Authentication: Bearer Token
Request Headers:
Authorization
string
Yes
Bearer token for user authentication
Content-Type
string
Yes
Must be "application/json"
Response JSON Sample:
{
"success": true,
"message": "Shopping cart initialized successfully",
"data": null,
"timestamp": "2025-09-22T14:30:00Z"
}Response Fields:
success
Boolean indicating operation success
message
Human-readable success message
data
Always null for this endpoint
timestamp
ISO 8601 timestamp of response
Error Responses:
401 Unauthorized: Authentication token missing or invalid404 Not Found: User account not found500 Internal Server Error: Database or server error
2. Add Product to Cart
Purpose: Adds a product to the user's shopping cart or updates quantity if already exists
Endpoint: POST /api/v1/cart/add
Access Level: 🔒 Protected (Requires Authentication)
Authentication: Bearer Token
Request Headers:
Authorization
string
Yes
Bearer token for user authentication
Content-Type
string
Yes
Must be "application/json"
Request JSON Sample:
{
"productId": "123e4567-e89b-12d3-a456-426614174000",
"quantity": 2
}Request Body Parameters:
productId
UUID
Yes
Unique identifier of the product to add
Must be valid UUID format
quantity
integer
Yes
Number of items to add to cart
Min: 1, Max: limited by stock
Response JSON Sample:
{
"success": true,
"message": "Product added to cart successfully",
"data": null,
"timestamp": "2025-09-22T14:30:00Z"
}Response Fields:
success
Boolean indicating operation success
message
Success message indicating if product was added or quantity updated
data
Always null for this endpoint
timestamp
ISO 8601 timestamp of response
Error Responses:
400 Bad Request: Invalid request data or validation errors401 Unauthorized: Authentication token missing or invalid404 Not Found: Product not found or user not found422 Unprocessable Entity: Insufficient stock or product unavailable500 Internal Server Error: Database or server error
3. Get Cart Contents
Purpose: Retrieves the complete shopping cart with all items, pricing, and summary information
Endpoint: GET /api/v1/cart
Access Level: 🔒 Protected (Requires Authentication)
Authentication: Bearer Token
Request Headers:
Authorization
string
Yes
Bearer token for user authentication
Response JSON Sample:
{
"success": true,
"message": "Shopping cart retrieved successfully",
"data": {
"user": {
"userId": "123e4567-e89b-12d3-a456-426614174000",
"userName": "John Doe",
"name": null
},
"cartSummary": {
"totalItems": 2,
"totalQuantity": 5,
"subtotal": 299.98,
"totalDiscount": 29.99,
"totalAmount": 269.99
},
"cartItems": [
{
"itemId": "987fcdeb-51a2-43d7-8f6e-123456789abc",
"productId": "123e4567-e89b-12d3-a456-426614174000",
"productName": "Wireless Bluetooth Headphones",
"productSlug": "wireless-bluetooth-headphones",
"productImage": "https://example.com/images/headphones.jpg",
"unitPrice": 99.99,
"discountAmount": 10.00,
"quantity": 2,
"itemSubtotal": 199.98,
"itemDiscount": 20.00,
"totalPrice": 179.98,
"shop": {
"shopId": "456e7890-e12f-34g5-h678-901234567890",
"shopName": "TechStore Pro",
"shopSlug": "techstore-pro",
"logoUrl": "https://example.com/logos/techstore.jpg"
},
"availability": {
"inStock": true,
"stockQuantity": 50
},
"addedAt": "2025-09-22T12:15:30Z"
}
],
"updatedAt": "2025-09-22T14:30:00Z"
},
"timestamp": "2025-09-22T14:30:00Z"
}Response Fields:
success
Boolean indicating operation success
message
Human-readable success message
data.user
User information summary
data.cartSummary
Cart totals and summary statistics
data.cartItems
Array of cart items with full product details
data.updatedAt
Last modification timestamp of the cart
timestamp
ISO 8601 timestamp of response
Error Responses:
401 Unauthorized: Authentication token missing or invalid404 Not Found: User not found500 Internal Server Error: Database or server error
4. Update Cart Item Quantity
Purpose: Updates the quantity of a specific item in the shopping cart
Endpoint: PUT /api/v1/cart/items/{itemId}
Access Level: 🔒 Protected (Requires Authentication)
Authentication: Bearer Token
Request Headers:
Authorization
string
Yes
Bearer token for user authentication
Content-Type
string
Yes
Must be "application/json"
Path Parameters:
itemId
UUID
Yes
Unique identifier of the cart item to update
Must be valid UUID format
Request JSON Sample:
{
"quantity": 3
}Request Body Parameters:
quantity
integer
Yes
New quantity for the cart item
Min: 1, Max: limited by stock
Response JSON Sample:
{
"success": true,
"message": "Product quantity updated successfully",
"data": null,
"timestamp": "2025-09-22T14:30:00Z"
}Response Fields:
success
Boolean indicating operation success
message
Human-readable success message
data
Always null for this endpoint
timestamp
ISO 8601 timestamp of response
Error Responses:
400 Bad Request: Invalid request data or validation errors401 Unauthorized: Authentication token missing or invalid404 Not Found: Cart item not found or user not found422 Unprocessable Entity: Insufficient stock for requested quantity500 Internal Server Error: Database or server error
5. Remove Cart Item
Purpose: Removes a specific item completely from the shopping cart
Endpoint: DELETE /api/v1/cart/items/{itemId}
Access Level: 🔒 Protected (Requires Authentication)
Authentication: Bearer Token
Request Headers:
Authorization
string
Yes
Bearer token for user authentication
Path Parameters:
itemId
UUID
Yes
Unique identifier of the cart item to remove
Must be valid UUID format
Response JSON Sample:
{
"success": true,
"message": "Product removed from cart successfully",
"data": null,
"timestamp": "2025-09-22T14:30:00Z"
}Response Fields:
success
Boolean indicating operation success
message
Human-readable success message
data
Always null for this endpoint
timestamp
ISO 8601 timestamp of response
Error Responses:
401 Unauthorized: Authentication token missing or invalid404 Not Found: Cart item not found or user not found500 Internal Server Error: Database or server error
6. Clear Entire Cart
Purpose: Removes all items from the user's shopping cart
Endpoint: DELETE /api/v1/cart/clear
Access Level: 🔒 Protected (Requires Authentication)
Authentication: Bearer Token
Request Headers:
Authorization
string
Yes
Bearer token for user authentication
Response JSON Sample:
{
"success": true,
"message": "Shopping cart cleared successfully",
"data": null,
"timestamp": "2025-09-22T14:30:00Z"
}Response Fields:
success
Boolean indicating operation success
message
Human-readable success message
data
Always null for this endpoint
timestamp
ISO 8601 timestamp of response
Error Responses:
401 Unauthorized: Authentication token missing or invalid404 Not Found: User not found500 Internal Server Error: Database or server error
Quick Reference Guide
Common HTTP Status Codes
200 OK: Successful GET/PUT request201 Created: Successful POST request204 No Content: Successful DELETE request400 Bad Request: Invalid request data401 Unauthorized: Authentication required/failed403 Forbidden: Insufficient permissions404 Not Found: Resource not found422 Unprocessable Entity: Validation errors or business logic violations429 Too Many Requests: Rate limit exceeded500 Internal Server Error: Server error
Authentication Types
Bearer Token: Include
Authorization: Bearer your_jwt_tokenin headers
Data Format Standards
Dates: Use ISO 8601 format (2025-09-22T14:30:00Z)
Currency: Use decimal format with 2 decimal places (99.99)
IDs: UUID format (123e4567-e89b-12d3-a456-426614174000)
Quantities: Positive integers starting from 1
Business Rules
Stock Validation: All quantity operations are validated against current product stock
Cart Persistence: Cart items persist until explicitly removed or user session expires
Price Calculation: Prices and discounts are calculated in real-time based on current product data
Automatic Cart Creation: Cart is automatically created for authenticated users when needed
Item Deduplication: Adding an existing product updates the quantity instead of creating duplicate entries
Last updated