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 shopping cart functionality for the NextGate e-commerce platform. It supports adding products to cart, updating quantities, removing items, and real-time stock validation.

Base URL: api/v1/e-commerce/cart

Hints:

  • All cart operations require user authentication via Bearer token
  • Each user has one persistent cart that maintains state across sessions
  • Real-time stock validation prevents overselling
  • Adding an existing product updates its quantity (additive)
  • Cart persistence survives user logout/login cycles

Endpoints

1. Add Product to Cart

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

Endpoint: POST {base}/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 Not null, product must exist and be active
quantity integer Yes Quantity to add to cart Min: 1

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 one 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

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
}

2. Get Shopping Cart

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

Endpoint: GET {base}

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": 2,
      "totalQuantity": 3,
      "subtotal": 2198.00,
      "totalDiscount": 0.00,
      "totalAmount": 2198.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",
        "productType": "PHYSICAL",
        "unitPrice": 1199.00,
        "quantity": 2,
        "itemSubtotal": 2398.00,
        "totalPrice": 2398.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,
          "availableQuantity": 25,
          "maxPerCustomer": 5
        },
        "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",
        "productType": "PHYSICAL",
        "unitPrice": 999.00,
        "quantity": 1,
        "itemSubtotal": 999.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,
          "availableQuantity": 8,
          "maxPerCustomer": null
        },
        "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
productType PHYSICAL or DIGITAL
unitPrice Current product price per unit
quantity Quantity of this product in cart
itemSubtotal unitPrice × quantity
totalPrice itemSubtotal after discounts
shop Shop information (id, name, slug, logo)
availability Real-time stock information
addedAt When item was first added to cart

Product Availability

Field Description
inStock Whether the product is currently in stock
availableQuantity Current available inventory
maxPerCustomer Maximum quantity a single customer can purchase (null if no limit)

Error Responses:

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

3. Update Cart Item Quantity

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

Endpoint: PUT {base}/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
itemId UUID Yes ID of the cart item to update

Request JSON Sample:

{
  "quantity": 3
}

Request Body Parameters:

Parameter Type Required Description Validation
quantity integer Yes New quantity for the cart item Min: 1

Response JSON Sample:

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

Business Logic:

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

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
}

4. Remove Cart Item

Purpose: Removes a specific item completely from the cart

Endpoint: DELETE {base}/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
itemId UUID Yes ID of the cart item to remove

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 items from the authenticated user's own cart

Error Responses:

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

5. Clear Shopping Cart

Purpose: Removes all items from the user's cart

Endpoint: DELETE {base}/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

Error Responses:

  • 401 Unauthorized: Authentication required
  • 404 Not Found: User not foundrl at

No comments to display

Back to top