EventCatalog | Entities

Overview

The ShoppingCart entity manages the customer’s shopping experience before checkout. It tracks selected products, quantities, pricing, and supports both registered customer and guest shopping scenarios.

Entity Properties

Name	Type	Required	Description
`cartId`	`UUID`	Required	Unique identifier for the shopping cart
`customerId`	`UUID`	Optional	Customer who owns this cart (null for guest carts)
`sessionId`	`string`	Optional	Session identifier for guest carts
`status`	`string`	Required	Current status of the cart
`cartItems`	`array`	Optional	Items in the shopping cart
`subtotal`	`decimal`	Required	Subtotal amount before taxes and shipping
`taxAmount`	`decimal`	Optional	Calculated tax amount
`shippingAmount`	`decimal`	Optional	Calculated shipping amount
`discountAmount`	`decimal`	Optional	Total discount amount applied
`totalAmount`	`decimal`	Required	Final total amount including taxes and shipping
`currency`	`string`	Required	Currency code for all amounts
`appliedCoupons`	`array`	Optional	Coupon codes applied to this cart
`shippingAddress`	`Address`	Optional	Selected shipping address
`billingAddress`	`Address`	Optional	Selected billing address
`notes`	`string`	Optional	Customer notes or special instructions
`abandonedAt`	`DateTime`	Optional	Date and time when cart was abandoned
`convertedToOrderId`	`UUID`	Optional	Order ID if cart was successfully converted
`expiresAt`	`DateTime`	Optional	Date and time when cart expires
`createdAt`	`DateTime`	Required	Date and time when the cart was created
`updatedAt`	`DateTime`	Optional	Date and time when the cart was last updated

Relationships

Customer: A cart can belong to one Customer (identified by customerId).
CartItem: A cart contains multiple CartItem entities with product details.
Address: A cart can reference shipping and billing Address entities.
Order: A cart can be converted to one Order (identified by convertedToOrderId).

Cart States

active → abandoned
   ↓       ↓
converted  expired

Examples

Cart #1: Customer cart with 3 items, $299.99 total, active status.
Cart #2: Guest cart abandoned after 24 hours, contains 1 high-value item.
Cart #3: Converted cart that became Order #12345, marked as converted.

Business Rules

Guest carts are identified by session ID when customer ID is null
Cart totals are recalculated when items are added/removed
Abandoned carts trigger marketing automation after configured time
Expired carts are cleaned up after retention period
Cart conversion creates an order and marks cart as converted
Inventory is not reserved until checkout begins
Applied coupons are validated on each cart update
Cart items maintain snapshot of product prices at time of addition

ShoppingCart (v1.0.0)