Skip to main content

Cart Management

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: 2025-09-23
Version: v1.0

Short Description: The Cart Management API provides comprehensive shopping cart functionality for the NextGate e-commerce platform. It supports adding products to cart, updating quantities, removing items, real-time price calculations, stock validation, and automatic cart management with user authentication.

Hints:

  • All cart operations require user authentication via Bearer token
  • Cart is automatically created for each user upon first interaction
  • Each user has one persistent cart that maintains state across sessions
  • Real-time stock validation prevents overselling
  • Supports adding existing products with quantity updates
  • Real-time price calculations include discounts and promotions
  • Cart items are linked to active products only (ACTIVE status)
  • Automatic cart cleanup when products become unavailable
  • Optimized for concurrent access and inventory management
  • Cart items show shop information for multi-vendor marketplace support
  • Stock availability is validated on every cart operation
  • Cart persistence survives user logout/login cycles

Endpoints

1. Initialize Cart

Purpose: Creates or ensures cart exists for the authenticated user

Endpoint: POST /api/v1/cart/initialize

Access Level: 🔒 Protected (Requires authentication)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication

Response JSON Sample:

{
  "success": true,
  "message": "Shopping cart initialized successfully",
  "data": null
}

Business Logic:

  • Creates new cart if user doesn't have one
  • Returns success if cart already exists
  • Automatic cart creation on first use

Error Responses:

  • 401 Unauthorized: Authentication required or invalid token
  • 500 Internal Server Error: Server error during cart creation

2. Add Product to Cart

Purpose: Adds a product to the user's cart or updates quantity if already exists

Endpoint: POST /api/v1/cart/add

Access Level: 🔒 Protected (Requires authentication)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication
Content-Type string Yes application/json

Request JSON Sample:

{
  "productId": "456e7890-e89b-12d3-a456-426614174001",
  "quantity": 2
}

Request Body Parameters:

Parameter Type Required Description Validation
productId UUID Yes ID of the product to add Valid UUID, product must exist and be active
quantity integer Yes Quantity to add to cart Min: 1, must not exceed available stock

Response JSON Sample (New Item):

{
  "success": true,
  "message": "Product added to cart successfully",
  "data": null
}

Response JSON Sample (Updated Existing):

{
  "success": true,
  "message": "Product quantity updated in cart successfully",
  "data": null
}

Business Logic:

  • Creates cart automatically if doesn't exist
  • If product already in cart, adds to existing quantity
  • Validates total quantity doesn't exceed available stock
  • Only allows active products to be added
  • Real-time stock validation

Stock Validation:

  • Checks product current stock before adding
  • For existing items: validates (current cart quantity + new quantity) ≤ stock
  • Prevents overselling with detailed error messages

Error Responses:

  • 400 Bad Request: Invalid productId or quantity validation error
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Product not found or not active
  • 422 Unprocessable Entity: Insufficient stock available

Error Examples:

{
  "success": false,
  "message": "Insufficient stock for 'iPhone 15 Pro'. Only 3 units available",
  "data": null
}

{
  "success": false,
  "message": "Cannot add more items. Total quantity (8) would exceed available stock (5) for 'MacBook Pro'",
  "data": null
}

3. Get Shopping Cart

Purpose: Retrieves the complete shopping cart with all items, pricing, and calculations

Endpoint: GET /api/v1/cart

Access Level: 🔒 Protected (Requires authentication)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication

Response JSON Sample:

{
  "success": true,
  "message": "Shopping cart retrieved successfully",
  "data": {
    "user": {
      "userId": "111e2222-e89b-12d3-a456-426614174003",
      "userName": "john.doe",
      "name": "John Doe"
    },
    "cartSummary": {
      "totalItems": 3,
      "totalQuantity": 7,
      "subtotal": 2497.00,
      "totalDiscount": 200.00,
      "totalAmount": 2297.00
    },
    "cartItems": [
      {
        "itemId": "cart001-e89b-12d3-a456-426614174004",
        "productId": "456e7890-e89b-12d3-a456-426614174001",
        "productName": "iPhone 15 Pro Max 512GB",
        "productSlug": "iphone-15-pro-max-512gb",
        "productImage": "https://example.com/images/iphone15-pro-max.jpg",
        "unitPrice": 1199.00,
        "discountAmount": 100.00,
        "quantity": 2,
        "itemSubtotal": 2398.00,
        "itemDiscount": 200.00,
        "totalPrice": 2198.00,
        "shop": {
          "shopId": "123e4567-e89b-12d3-a456-426614174000",
          "shopName": "TechStore Pro",
          "shopSlug": "techstore-pro",
          "logoUrl": "https://example.com/logos/techstore-pro.png"
        },
        "availability": {
          "inStock": true,
          "stockQuantity": 25
        },
        "addedAt": "2025-09-23T10:30:00Z"
      },
      {
        "itemId": "cart002-e89b-12d3-a456-426614174005",
        "productId": "567e8901-e89b-12d3-a456-426614174002",
        "productName": "MacBook Air M3",
        "productSlug": "macbook-air-m3",
        "productImage": "https://example.com/images/macbook-air-m3.jpg",
        "unitPrice": 999.00,
        "discountAmount": 0.00,
        "quantity": 1,
        "itemSubtotal": 999.00,
        "itemDiscount": 0.00,
        "totalPrice": 999.00,
        "shop": {
          "shopId": "123e4567-e89b-12d3-a456-426614174000",
          "shopName": "TechStore Pro",
          "shopSlug": "techstore-pro",
          "logoUrl": "https://example.com/logos/techstore-pro.png"
        },
        "availability": {
          "inStock": true,
          "stockQuantity": 8
        },
        "addedAt": "2025-09-23T11:15:00Z"
      }
    ],
    "updatedAt": "2025-09-23T14:20:00Z"
  }
}

Response Structure:

User Summary

Field Description
userId Unique identifier of the cart owner
userName User's login username
name User's full name (firstName + lastName)

Cart Summary

Field Description
totalItems Number of distinct products in cart
totalQuantity Total quantity of all items combined
subtotal Total price before discounts
totalDiscount Total discount amount applied
totalAmount Final amount after discounts

Cart Item Details

Field Description
itemId Unique identifier for the cart item
productId Product identifier
productName Current product name
productSlug URL-friendly product identifier
productImage Primary product image URL
unitPrice Current product price per unit
discountAmount Discount per unit (if product on sale)
quantity Quantity of this product in cart
itemSubtotal unitPrice × quantity
itemDiscount discountAmount × quantity
totalPrice itemSubtotal - itemDiscount
shop Shop information (id, name, slug, logo)
availability Real-time stock information
addedAt When item was first added to cart

Real-time Calculations:

  • Prices reflect current product pricing
  • Discounts applied automatically for sale items
  • Stock quantities show real-time availability
  • Calculations updated on each cart retrieval

Error Responses:

  • 401 Unauthorized: Authentication required
  • 404 Not Found: User not found

4. Update Cart Item Quantity

Purpose: Updates the quantity of a specific item in the cart

Endpoint: PUT /api/v1/cart/items/{itemId}

Access Level: 🔒 Protected (Requires authentication)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication
Content-Type string Yes application/json

Path Parameters:

Parameter Type Required Description Validation
itemId UUID Yes ID of the cart item to update Valid UUID, must belong to user's cart

Request JSON Sample:

{
  "quantity": 3
}

Request Body Parameters:

Parameter Type Required Description Validation
quantity integer Yes New quantity for the cart item Min: 1, must not exceed available stock

Response JSON Sample:

{
  "success": true,
  "message": "Product quantity updated successfully",
  "data": null
}

Business Logic:

  • Updates quantity to exact specified value (not additive)
  • Validates new quantity doesn't exceed current stock
  • Only allows updating user's own cart items

Stock Validation:

  • Checks current product stock before updating
  • Prevents quantity exceeding available inventory
  • Provides detailed error message if stock insufficient

Error Responses:

  • 400 Bad Request: Invalid quantity value
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Cart item not found in user's cart
  • 422 Unprocessable Entity: Insufficient stock for requested quantity

Error Example:

{
  "success": false,
  "message": "Insufficient stock for 'iPhone 15 Pro'. Only 2 units available",
  "data": null
}

5. Remove Cart Item

Purpose: Removes a specific item completely from the cart

Endpoint: DELETE /api/v1/cart/items/{itemId}

Access Level: 🔒 Protected (Requires authentication)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication

Path Parameters:

Parameter Type Required Description Validation
itemId UUID Yes ID of the cart item to remove Valid UUID, must belong to user's cart

Response JSON Sample:

{
  "success": true,
  "message": "Product removed from cart successfully",
  "data": null
}

Business Logic:

  • Completely removes the cart item and all its quantity
  • Only allows removing user's own cart items
  • Cart item is permanently deleted from database

Error Responses:

  • 401 Unauthorized: Authentication required
  • 404 Not Found: Cart item not found in user's cart

6. Clear Shopping Cart

Purpose: Removes all items from the user's cart

Endpoint: DELETE /api/v1/cart/clear

Access Level: 🔒 Protected (Requires authentication)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication

Response JSON Sample:

{
  "success": true,
  "message": "Shopping cart cleared successfully",
  "data": null
}

Business Logic:

  • Removes all cart items for the authenticated user
  • Cart entity remains but becomes empty
  • Cannot be undone - permanent deletion of all items

Use Cases:

  • User wants to start fresh with empty cart
  • Clear cart after successful order completion
  • Administrative cart cleanup

Error Responses:

  • 401 Unauthorized: Authentication required
  • 404 Not Found: User not found

Quick Reference Guide

Common HTTP Status Codes

  • 200 OK: Successful GET/PUT/DELETE request
  • 201 Created: Successful POST request (cart initialization)
  • 400 Bad Request: Invalid request data or validation errors
  • 401 Unauthorized: Authentication required or invalid token
  • 404 Not Found: Cart item, product, or user not found
  • 422 Unprocessable Entity: Stock validation errors
  • 500 Internal Server Error: Server error during processing

Authentication Requirements

  • Bearer Token: Include Authorization: Bearer your_token in headers
  • All endpoints require authentication - no public cart operations
  • User-specific carts - each user has their own isolated cart

Data Format Standards

  • Dates: Use ISO 8601 format (2025-09-23T14:30:00Z)
  • Prices: Decimal with 2 decimal places (999.00)
  • UUIDs: Standard UUID format (123e4567-e89b-12d3-a456-426614174000)
  • Quantities: Positive integers only (minimum 1)

Cart Business Rules

Stock Management

  • Real-time Validation: Stock checked on every cart operation
  • Prevent Overselling: Cannot add more than available inventory
  • Active Products Only: Only products with ACTIVE status can be added
  • Stock Updates: Cart shows current stock, not stock at time of adding

Quantity Management

  • Minimum Quantity: All quantities must be at least 1
  • Additive Adding: Adding existing product increases quantity
  • Absolute Updates: Update operations set exact quantity (not additive)
  • Stock Limits: Cannot exceed available inventory at any time

Cart Persistence

  • User-Specific: Each authenticated user has one persistent cart
  • Session Independent: Cart survives logout/login cycles
  • Automatic Creation: Cart created automatically on first interaction
  • Cleanup: No automatic expiration (persists indefinitely)

Price Calculation Logic

Item-Level Calculations

Item Subtotal = Unit Price × Quantity
Item Discount = Discount Amount × Quantity (if product on sale)
Item Total = Item Subtotal - Item Discount

Cart-Level Calculations

Total Items = Count of distinct products
Total Quantity = Sum of all item quantities
Subtotal = Sum of all item subtotals
Total Discount = Sum of all item discounts  
Total Amount = Subtotal - Total Discount

Real-time Price Updates

  • Prices reflect current product pricing on each cart retrieval
  • Discounts applied automatically for products on sale
  • No price locking - prices may change between cart operations

Error Handling Patterns

Stock Validation Errors

{
  "success": false,
  "message": "Insufficient stock for '{productName}'. Only {available} units available"
}

Cart Item Not Found

{
  "success": false,  
  "message": "Cart item not found"
}

Authentication Errors

{
  "success": false,
  "message": "User not authenticated"
}

Best Practices for Cart Management

For Frontend Applications

  1. Check stock before adding - validate availability client-side when possible
  2. Handle stock errors gracefully - show clear messages about availability
  3. Refresh cart regularly - prices and stock change in real-time
  4. Implement quantity controls - prevent users from entering invalid quantities
  5. Show loading states - cart operations may take time due to validation
  6. Cache cart data briefly - but refresh before checkout
  7. Handle authentication errors - redirect to login when tokens expire
  8. Display shop information - help users understand multi-vendor items
  9. Show stock warnings - alert users about low stock items
  10. Implement optimistic updates - with fallback for failures

For Backend Integration

  1. Always authenticate users before cart operations
  2. Validate stock in real-time - inventory changes frequently
  3. Handle concurrent access - multiple devices may access same cart
  4. Log cart operations - for debugging and analytics
  5. Monitor stock levels - prevent overselling scenarios
  6. Implement rate limiting - prevent cart abuse
  7. Clean up orphaned items - when products become inactive
  8. Validate product availability - ensure products are still active
  9. Handle shop changes - when products move between shops
  10. Implement cart recovery - for interrupted operations

Common Use Cases

  • Add to Cart: POST /api/v1/cart/add with productId and quantity
  • View Cart: GET /api/v1/cart for complete cart with calculations
  • Update Quantity: PUT /api/v1/cart/items/{itemId} with new quantity
  • Remove Item: DELETE /api/v1/cart/items/{itemId}
  • Clear Cart: DELETE /api/v1/cart/clear

Validation Summary

  • All endpoints require authentication
  • Stock validation on add/update operations
  • Only active products can be added to cart
  • Quantities must be positive integers (minimum 1)
  • Real-time price calculations on cart retrieval

No comments to display

Back to top