PhoenixKitEcommerce.CartItem (PhoenixKitEcommerce v0.5.0)

Copy Markdown View Source

Cart item schema with price snapshot for consistency.

When a product is added to the cart, we snapshot the current price and product details. This ensures that:

  1. Price changes after adding don't affect the cart total unexpectedly
  2. If the product is deleted, we still have the title and other info
  3. We can show users when prices have changed since they added items

Fields

  • cart_uuid - Reference to the cart (required)
  • product_uuid - Reference to the product (nullable, ON DELETE SET NULL)
  • product_title - Product title snapshot (required)
  • product_slug - Product slug snapshot
  • product_sku - Product SKU snapshot
  • product_image - Product image URL snapshot
  • unit_price - Price per unit at time of adding (required), frozen in the CART's own currency (§4.3.1, §4.4, §12.1)
  • compare_at_price - Original price for showing discounts, frozen the same way and at the same rate as unit_price (§4.3.1) — never a raw base amount alongside an already-converted unit_price, or the displayed discount misstates itself
  • quantity - Number of items (required, > 0)
  • line_total - Calculated: unit_price * quantity
  • weight_grams - Weight for shipping calculation
  • taxable - Whether item is taxable
  • selected_specs - JSON object for specification-based pricing (e.g., {"material": "PETG", "color": "Gold"})

Summary

Functions

changeset(item, attrs)

Changeset for cart item creation and updates.

discount_percentage(item)

Returns discount percentage for sale items.

from_product(product, quantity \\ 1, language_or_opts \\ nil)

Creates changeset attributes from a product.

on_sale?(cart_item)

Returns true if this item is on sale (has compare_at_price > unit_price).

price_difference(item, product)

Returns the price difference if the product price has changed. Positive = price increased, Negative = price decreased.

product_changed?(item, product)

Returns true if product data has changed since the item was added. Useful for showing price change warnings.

product_deleted?(arg1)

Returns true if the product has been deleted (product_uuid is nil after ON DELETE SET NULL).

Functions

changeset(item, attrs)

Changeset for cart item creation and updates.

discount_percentage(item)

Returns discount percentage for sale items.

from_product(product, quantity \\ 1, language_or_opts \\ nil)

Creates changeset attributes from a product.

Parameters

  • product - The Product struct
  • quantity - Number of items (default: 1)
  • language - Language code for localized fields (default: system default)

Examples

iex> from_product(product, 2)
%{
  product_uuid: "01234567-...",
  product_title: "Widget",
  product_slug: "widget",
  unit_price: Decimal.new("19.99"),
  quantity: 2,
  ...
}

iex> from_product(product, 1, "ru")
%{product_title: "Виджет", product_slug: "vidzhet", ...}

on_sale?(cart_item)

Returns true if this item is on sale (has compare_at_price > unit_price).

price_difference(item, product)

Returns the price difference if the product price has changed. Positive = price increased, Negative = price decreased.

product_changed?(item, product)

Returns true if product data has changed since the item was added. Useful for showing price change warnings.

product_deleted?(arg1)

Returns true if the product has been deleted (product_uuid is nil after ON DELETE SET NULL).

Catalogue-backed lines never store product_uuid — their identity is metadata["catalogue_item_uuid"] — so a nil uuid is not a deletion signal for those.