Cart Module - API & Integration Guide

Audience: Mobile/web frontend developers integrating cart Scope: DTOs, error codes, business rules

1. How to Read / Quick Metadata

• Module: Cart
• Auth models:
  • Customer/mobile routes: JwtAuthGuard
  • Admin routes: JwtAuthGuard + RoleGuard + @Permissions(...)
• Primary base URLs:
  • Customer: /api/cart
  • Mobile-composed customer: /api/mobile/cart
  • Admin: /api/admin/cart
• Response envelope: successful endpoints return ResponseDto<T>
• Swagger tags used by controllers:
  • Cart (Mobile)
  • Cart (Admin)

2. High-Level Overview

Cart API is focused on authenticated cart management for physical products and legacy digital compatibility:

• fetch current cart
• add item
• remove item
• clear cart

Cart eligibility behavior:

• Physical product types: thangka, singing_bowl, statue, jewellery

Payment initiation endpoints (checkout, buy-now) are owned by order APIs, not cart controller routes.

3. Core Concepts and Terminology

• cart: active per-user basket (cart table)
• cart item: one product line with monetary snapshot (cart_item table)
• applied coupon projection: appliedPromotionId, appliedPromotionCode, appliedDiscount
• final payable: totalSp - (appliedDiscount ?? 0)
• cart lifecycle: active, checkout, completed, abandoned
• async cart jobs: cart.clear_after_order_confirmed, cart.expire

4. Route Summary

4.1 Customer / Mobile

Mobile-composed equivalents are available under /api/mobile/cart....

4.2 Admin

Cart GET

Cart Add Item

5. Query Parameters

Cart endpoints do not define list/filter query contracts.

• GET /api/cart and mutating cart endpoints do not consume query DTOs.
• Admin GET /api/admin/cart/users/:userId is path-param only.

6. Response Shape Examples

6.1 Add item request

"
  "productId": 101
"

6.2 Cart response

"
  "id": 1,
  "status": "active",
  "items": [
    "
      "id": 10,
      "productId": 101,
      "productThumbnail": "https://cdn.example.com/thumb.jpg",
      "unitMrp": 15000,
      "unitSp": 12000,
      "discount": 3000
    ""
  ],
  "totalMrp": 15000,
  "totalSp": 12000,
  "totalDiscount": 3000,
  "appliedCoupon": "
    "promotionId": 1,
    "code": "SUMMER2024",
    "discount": 1000
  "",
  "finalPayable": 11000
"

6.3 Clear cart response

"
  "cleared": true
"

7. Enums

7.1 cart_status

• active
• checkout
• completed
• abandoned

7.2 Allowed cart product types (service-level)

• thangka
• singing_bowl
• statue
• jewellery

8. Integration Diagram

9. Caching

Cache keyspaces:

• cart:user:

TTL env:

• CART_CUSTOMER_CACHE_TTL_SECONDS (default 60)

Invalidation triggers:

• add item / remove item / clear cart / coupon updates invalidate cart:user:userId:<encoded>*
• failures in Redis cache operations are logged and request path falls back to DB behavior

10. Error Handling

All cart API errors return the standard error envelope:

"
  "statusCode": 404,
  "errorCode": "CART_NOT_FOUND",
  "message": "Cart not found",
  "timestamp": "2026-03-20T10:00:00.000Z",
  "path": "/api/cart"
"

Representative error map:

Time fields in this module are stored as timezone-aware values and should be handled as ISO-8601 instants by API consumers.

11. Endpoint Reference + Payload Cheatsheet

11.1 Payload Cheatsheet Table (Every Endpoint)

11.1.1 Customer Cart Endpoint Query Variations

11.1.2 Add Item Request Variations

11.1.3 Remove Item Request Variations

11.1.4 Cart Response Field Variations

11.1.5 Error Response Variations

11.1.6 Cache Invalidation Variations

11.1.7 Cart Item Fields in Response

11.1.8 Cart Summary Fields in Response

12. Testing Scenarios

12.1 Add Item to Cart

Test Case: Successful add item to empty cart

1. Authenticated user with no items in cart
2. POST /api/cart/items with "" "productId": 101 ""
3. Expect 200 with ResponseDto<CartDto> containing the new item
4. Verify cart status is active
5. Verify item productType, unitMrp, unitSp, discount populated correctly

12.2 Add Duplicate Item

Test Case: Adding already-added product returns conflict

1. User has product 101 already in cart
2. POST /api/cart/items with "" "productId": 101 ""
3. Expect 409 with errorCode CART_PRODUCT_ALREADY_IN_CART

12.3 Remove Item from Cart

Test Case: Remove single item from cart

1. User has cart with multiple items
2. DELETE /api/cart/items/10 (itemId)
3. Expect 200 with updated cart without the removed item
4. Verify remaining items still have correct pricing

12.4 Clear Entire Cart

Test Case: Clear all items from cart

1. User has cart with multiple items
2. DELETE /api/cart
3. Expect 200 with "" "cleared": true ""
4. Verify subsequent GET /api/cart returns empty items array

12.5 Cart with Promo Code

Test Case: Apply valid promo code to cart

1. User adds items to cart totaling Rs. 15,000
2. Apply promotion via order checkout (promo applied at order, not cart level)
3. Verify finalPayable reflects discount
4. Verify appliedCoupon populated in cart response

12.6 Admin View User Cart

Test Case: Admin retrieves user cart by userId

1. Admin with appropriate permissions
2. GET /api/admin/cart/users/:userId
3. Expect 200 with full cart details including items and pricing

See Also

• Feature Guide: See Cart - Feature List Section 6 (State Models) for cart state diagram.
• Backend Reference: See Cart - Backend Documentation Section 9 for system architecture diagram.