Skip to main content

Notes on Cart API

Cart Lifecycle​

  • Each authenticated user has exactly one cart that persists across sessions
  • Carts are automatically created when users first add items
  • Cart data is automatically updated and synchronized with current product prices and availability

Stock Validation​

  • The API validates product stock availability before adding items or increasing quantities
  • Products with stock_type = "unlimited" have no quantity restrictions
  • Products with stock_type = "limited" are validated against current stock levels
  • Products with stock_type = "out_of_stock" or stock_type = "call" cannot be added to cart

Price Calculations​

  • All prices are calculated server-side and cannot be manipulated by clients
  • Item totals include current product prices and any applicable discounts
  • Cart totals are automatically recalculated whenever items are modified
  • Price fields (unit_price, unit_discount, subtotal, discount, total) are read-only

Product Information​

  • Each cart item includes basic product information (ID, name, image)
  • Product data is fetched with optimized queries including image relationships
  • Product availability and pricing are validated in real-time

Cart Operations​

  • Add Item: Adds new products or increases quantity for existing items
  • Update Item: Modify quantity or notes for existing items
  • Remove Item: Completely removes an item from the cart
  • Increase/Decrease: Convenient endpoints for quantity adjustments
  • Clear Cart: Removes all items while preserving cart settings

Validation Rules​

  • Minimum quantity is 1 for all operations
  • Maximum quantity is limited by product stock (for limited stock items)
  • Notes field has a 500 character limit
  • Address must belong to the authenticated user
  • Payment and shipping methods must be active and compatible with the cart

Address and Method Selection​

  • Cart supports selecting delivery address, shipping method, and payment method
  • Selected address must belong to the authenticated user
  • Payment and shipping methods must be active and validate against the cart contents
  • These selections persist until changed or cart is cleared

Security Features​

  • Users can only access and modify their own carts
  • Product prices are server-authoritative and cannot be manipulated
  • Address ownership is validated to prevent unauthorized access
  • All cart operations require authentication