Adds item to cart.

Options

• :selected_specs - Map of selected specifications (for dynamic pricing)

Examples

# Add simple product
add_to_cart(cart, product, 2)

# Add product with specification-based pricing
add_to_cart(cart, product, 1, selected_specs: %{"material" => "PETG", "color" => "Gold"})

Aggregates filter values for sidebar display.

Returns a map of filter_key => aggregated data. For price_range: %{min: Decimal, max: Decimal} For vendor: [%{value: "Vendor", count: 5}, ...] For metadata_option: [%{value: "8 inches", count: 3}, ...]

Options:

• :category_uuid - Scope aggregation to a specific category by UUID

PhoenixKitAI translation adapters (duck-typed discovery — see PhoenixKitAI.Translatables).

Auto-selects payment option if only one is available.

If cart already has a payment option selected, does nothing. If only one option is available, selects it.

Auto-selects the cheapest available shipping method for a cart.

If cart already has a shipping method selected, does nothing. If only one method is available, selects it. If multiple methods are available, selects the cheapest one.

Bulk delete categories. Returns count of deleted categories. Nullifies category references on orphaned products.

Bulk delete products. Returns count of deleted products.

Bulk update category parent. Returns count of updated categories. Excludes the target parent from the update set to prevent self-reference. Uses a single UPDATE with subquery to resolve parent_uuid.

Bulk update category status. Returns count of updated categories.

Bulk update product category. Returns count of updated products.

Bulk update product status. Returns count of updated products.

Calculates the final price for a product based on selected specifications.

Applies option price modifiers (fixed and percent) to the base price. Fixed modifiers are applied first, then percent modifiers.

Example

product = %Product{price: Decimal.new("20.00")}
selected_specs = %{"material" => "PETG", "finish" => "Premium"}

# If PETG has +$10 fixed and Premium has +20% percent:
calculate_product_price(product, selected_specs)
# => Decimal.new("36.00")  # ($20 + $10) * 1.20

Whether any line in the cart needs physical shipping.

Reads the "requires_shipping" flag snapshotted onto each cart item at add time. Rows created before the snapshot existed fall back to the live product's flag (batched, one query); a line whose product is GONE counts as requiring shipping — the conservative default, since charging shipping on a digital line is a smaller failure than shipping-free physical goods.

Digital-only carts skip the shipping-method requirement, the shipping charge, and the shipping line on the resulting order.

@spec cart_session_id(String.t() | any()) :: String.t() | nil

Returns just the session_id of a cart, without loading items.

Used to authorize order confirmation pages for orders placed BEFORE metadata["session_id"] was recorded on the order itself. Those orders still carry metadata["cart_uuid"], and the cart row survives conversion (mark_cart_converted/2 flips its status, it is never deleted) with its session_id intact — so the placing session is still recoverable for them.

Deliberately a narrow select rather than get_cart/1: this runs on a page load purely to compare one string, and get_cart/1 preloads items and the shipping method.

@spec cart_url(String.t()) :: String.t()

Generates a localized URL for the cart page.

Examples

iex> Shop.cart_url("ru")
"/ru/cart"

iex> Shop.cart_url("en")
"/cart"

@spec catalog_url(String.t()) :: String.t()

Generates a localized URL for the shop catalog.

Examples

iex> Shop.catalog_url("es-ES")
"/es/shop"

iex> Shop.catalog_url("en")
"/shop"

Returns categories as options for select input. Returns list of {localized_name, id} tuples.

Checks if a category slug exists for a language.

Examples

iex> Shop.category_slug_exists?("jarrones-macetas", "es-ES")
true

@spec category_url(PhoenixKitEcommerce.Category.t(), String.t()) :: String.t()

Generates a localized URL for a category.

Returns the correct locale-prefixed URL with translated slug.

Parameters

• category - The Category struct
• language - Language code (e.g., "en-US", "ru", "es-ES")

Examples

iex> Shop.category_url(category, "es-ES")
"/es/shop/category/jarrones-macetas"

iex> Shop.category_url(category, "en")
"/shop/category/vases-planters"  # Default language - no prefix

Returns a changeset for category form.

Returns a changeset for tracking import config changes.

Returns a changeset for product form.

Returns a changeset for shipping method form.

@spec checkout_url(String.t()) :: String.t()

Generates a localized URL for the checkout page.

Examples

iex> Shop.checkout_url("ru")
"/ru/checkout"

iex> Shop.checkout_url("en")
"/checkout"

Atomically claims a one-shot boolean flag on the cart's metadata.

Returns true exactly once per (cart, flag) — the caller that wins the claim; false for everyone after (or on any error). Used to deduplicate per-cart notifications under concurrent tabs.

Clears all items from cart.

Clears the cart's shipping selection and recalculates totals.

Used when the selected method stops being eligible for the cart as it is NOW (weight change, last physical line removed) — leaving it selected showed a zero-cost method the cart had outgrown and let checkout proceed to an inevitable conversion failure.

Collects all storage file UUIDs associated with a single product.

Collects all storage file UUIDs for a list of product UUIDs.

Marks import as completed.

Converts a cart to a Billing.Order.

Takes an active cart with items and creates an Order with:

• All cart items as line_items
• Shipping as additional line item (if selected)
• Billing profile snapshot (from profile_uuid or direct billing_data)
• Cart marked as "converted"

For guest checkout (no user_uuid on cart):

• Creates a guest user via Auth.create_guest_user/1
• Guest user has confirmed_at = nil until email verification
• Sends confirmation email automatically
• Order remains in "pending" status

Options

• billing_profile_uuid: uuid - Use existing billing profile (for logged-in users)
• billing_data: map - Use direct billing data (for guest checkout)

Returns

• {:ok, order} - Order created successfully
• {:error, :cart_not_active} - Cart is not active
• {:error, :cart_empty} - Cart has no items
• {:error, :no_shipping_method} - No shipping method selected
• {:error, :email_already_registered} - Guest email belongs to confirmed user
• {:error, changeset} - Validation errors

Counts active carts.

Creates a new cart.

Creates a new category.

Creates an import config.

Creates a new import log entry.

Creates a new product.

Automatically normalizes metadata (price modifiers, option values) before saving to ensure consistent storage format.

Creates a new shipping method.

Tailwind source roots contributed to the host's CSS build.

Both README.md and AGENTS.md claimed this was implemented; it was not, and the use PhoenixKit.Module default returns []. The consequence was invisible rather than loud: core's :phoenix_kit_css_sources compiler collects this from every discovered module and writes assets/css/_phoenix_kit_sources.css, so with shop contributing nothing, Tailwind purged every class used only by this module's storefront and admin templates from the host build.

It stayed hidden because the compiler only warns when the TOTAL source list is empty — any other installed module masked the absence.

Resolves the currency a PERSISTED record was denominated in.

Order and cart pages used to load today's default currency, so changing the shop currency silently relabeled every historical order's amounts. Given the code stored on the record, this returns its Currency struct; an unresolvable code returns nil — callers then show the bare code rather than borrowing today's default symbol for an amount it does not describe.

Returns the default storefront filter configuration.

Deletes a category.

Deletes an import config.

Deletes an import log.

Deletes a product.

Deletes a shipping method.

Disables the shop system.

Discovers filterable option keys from product metadata.

Returns a list of {key, product_count} tuples sorted by count descending. Used by admin UI to auto-suggest available filters.

Enables the shop system.

Checks if the shop system is enabled.

Creates the legacy default import config if no configs exist.

Returns {:created, config} if a new config was created, or :exists if configs already exist.

Ensures a category has a featured_product_uuid set.

If the category has no image_uuid and no featured_product_uuid, auto-detects the first active product with an image and saves it. Returns the (possibly updated) category with :featured_product preloaded.

Ensures a default Prom.ua import config exists. Creates one if no config with name "prom_ua_default" is found.

Expires old guest carts.

Marks import as failed.

Finds active cart by user_uuid or session_id.

Search priority:

1. If user_uuid is provided, search by user_uuid first
2. If not found and session_id is provided, search by session_id (handles guest->login transition)
3. If only session_id is provided, search by session_id with no user_uuid

Finds an existing product by any slug in the provided slug map.

Searches through each slug value in the map to find a matching product. Returns the first product found, or nil if no match.

Examples

iex> find_product_by_slug_map(%{"en-US" => "planter"})
%Product{} | nil

iex> find_product_by_slug_map(%{"en-US" => "planter", "es-ES" => "maceta"})
%Product{} | nil  # Finds by first matching slug

Formats the product price for catalog display.

Returns:

• "$19.99" for products without price-affecting options
• "From $19.99" if options have different price modifiers
• "$19.99 - $38.00" for range display

Gets available shipping methods for a cart. Filters by weight, subtotal, and country.

Gets a cart by ID or UUID with items preloaded.

Gets a cart by ID or UUID, raises if not found.

Gets a category by ID or UUID.

Gets a category by ID or UUID, raises if not found.

Finds a category by slug in any language.

Examples

iex> Shop.get_category_by_any_slug("jarrones-macetas")
{:ok, %Category{}, "es"}

Gets a category by slug.

Supports localized slugs stored as JSONB maps.

Options

• :language - Language code for slug lookup (default: system default)
• :preload - Associations to preload

Examples

iex> get_category_by_slug("planters")
%Category{}

iex> get_category_by_slug("kashpo", language: "ru")
%Category{}

Gets a category by slug with language awareness.

Searches both translated slugs and canonical slug for the specified language.

Parameters

• slug - The URL slug to search for
• language - Language code (e.g., "es-ES" or base code "en")
• opts - Options: :preload, :status

Examples

iex> Shop.get_category_by_slug_localized("jarrones-macetas", "es-ES")
{:ok, %Category{}}

Gets the localized slug for a category.

Examples

iex> Shop.get_category_slug(category, "es-ES")
"jarrones-macetas"

Returns the current shop configuration.

Returns dashboard statistics for the shop.

Gets the default currency struct from Billing module.

Gets the default currency code from Billing module. Falls back to "USD" if Billing has no default currency configured.

Gets the default import config, if one exists.

@spec get_default_language() :: String.t()

Gets the default language code (base code, e.g., "en").

Reads from Languages module configuration or falls back to "en".

Returns only enabled storefront filters, sorted by position.

Gets an import config by ID.

Gets an import config by ID, raises if not found.

Gets an import config by name.

Gets an import log by ID.

Gets an import log by ID, raises if not found.

Gets or creates a cart for the current user/session.

Options

• :user_uuid - User UUID (for authenticated users)
• :session_id - Session ID (for guests)

Gets price-affecting options for a product.

Convenience wrapper around Options.get_price_affecting_specs_for_product/1.

Gets the price range for a product based on option modifiers.

Returns {min_price, max_price} where:

• min_price = minimum possible price (base + min modifiers)
• max_price = maximum possible price (base + max modifiers)

Example

# Product with base $20, material options (0, +5, +10), finish options (0%, +20%)
get_price_range(product)
# => {Decimal.new("20.00"), Decimal.new("36.00")}

Gets a product by ID or UUID.

Gets a product by ID or UUID, raises if not found.

Finds a product by slug in any language.

Searches across all translated slugs to find the product. Useful for cross-language redirect when user visits with a slug from a different language.

Examples

iex> Shop.get_product_by_any_slug("maceta-geometrica")
{:ok, %Product{}, "es"}

iex> Shop.get_product_by_any_slug("nonexistent")
{:error, :not_found}

Gets a product by slug.

Supports localized slugs stored as JSONB maps.

Options

• :language - Language code for slug lookup (default: system default)
• :preload - Associations to preload

Examples

iex> get_product_by_slug("planter")
%Product{}

iex> get_product_by_slug("kashpo", language: "ru")
%Product{}

Gets a product by slug with language awareness.

Searches both translated slugs and canonical slug for the specified language.

Parameters

• slug - The URL slug to search for
• language - Language code (e.g., "es-ES" or base code "en")
• opts - Options: :preload, :status

Examples

iex> Shop.get_product_by_slug_localized("maceta-geometrica", "es-ES")
{:ok, %Product{}}

iex> Shop.get_product_by_slug_localized("geometric-planter", "en")
{:ok, %Product{}}

Gets the localized slug for a product.

Returns translated slug if available, otherwise canonical slug.

Examples

iex> Shop.get_product_slug(product, "es-ES")
"maceta-geometrica"

Gets all selectable options for a product (for UI display).

Returns all select/multiselect options regardless of whether they affect price. This includes options like Color that may not have price modifiers but should still be selectable in the UI.

Convenience wrapper around Options.get_selectable_specs_for_product/1.

Gets a shipping method by ID or UUID.

Gets a shipping method by ID or UUID, raises if not found.

Gets a shipping method by slug.

Gets storefront filter configuration from shop_config.

Returns a list of filter definition maps with keys: key, type, label, enabled, position.

Default: price filter only.

Lists active categories only (for storefront display).

Lists carts with filters for admin.

Lists all categories.

Options

• :parent_uuid - Filter by parent UUID (nil for root categories)
• :status - Filter by status: "active", "hidden", "archived", or list of statuses
• :search - Search in name
• :preload - Associations to preload

Lists categories with translated fields for a specific language.

Parameters

• language - Language code for translations
• opts - Standard list options

Examples

iex> Shop.list_categories_localized("es-ES", status: "active")
[%Category{localized: %{name: "Jarrones...", ...}}, ...]

Lists categories with count for pagination.

Returns a list of {name, id} tuples for products in a category that have images. Used for the featured product dropdown in the admin category form.

Lists categories that have no products assigned.

Lists all active import configs.

Lists recent import logs.

Lists categories visible in storefront navigation/menu. Only active categories appear in menus. Semantic alias for list_active_categories/1.

Lists all products with optional filters.

Options

• :status - Filter by status (draft, active, archived)
• :product_type - Filter by type (physical, digital)
• :category_uuid - Filter by category
• :search - Search in title and description
• :page - Page number
• :per_page - Items per page
• :preload - Associations to preload

Lists products by their IDs.

Returns products in the order of the provided IDs.

Lists products with translated fields for a specific language.

Returns products with an additional :localized virtual map containing translated fields with fallback to defaults.

Parameters

• language - Language code for translations
• opts - Standard list options: :page, :per_page, :status, :category_uuid, etc.

Examples

iex> Shop.list_products_localized("es-ES", status: "active")
[%Product{localized: %{title: "Maceta...", ...}}, ...]

Lists products with count for pagination.

Lists root categories (no parent).

Lists all shipping methods.

Options

• :active - Filter by active status
• :country - Filter by country availability

Lists categories whose products are visible in storefront. Includes both active and unlisted categories. Use for product filtering, not for navigation menus.

Marks abandoned carts (no activity for X days).

Merges guest cart into user cart after login. Accepts a user struct or user_uuid (string).

Merges import attributes into an existing product.

A feed states what it knows; it cannot state what it does not know. The importers always emit the full attribute set, so a column the file omits arrives as a blank — and treating that blank as an instruction meant a routine second import DELETED data the file never mentioned:

• a blank Body (HTML) cell erased that product's description in every language, not merely the imported one;
• a feed with no image columns cleared the product's images and vendor;
• metadata was rebuilt from the feed, dropping the admin's option price modifiers, image mappings, price-display unit and custom keys.

So a blank incoming value leaves the stored one alone, localized maps merge per language, and metadata merges per key. Anything the feed does carry still wins — including a value that clears a single translation.

Examples

iex> merge_localized_attrs(%Product{title: %{"en-US" => "Old"}}, %{title: %{"es-ES" => "Nuevo"}})
%{title: %{"en-US" => "Old", "es-ES" => "Nuevo"}}

Merges built-in default filters missing from a saved filter config.

Configs saved before a built-in filter existed (e.g. search) never gain it on their own; this merges the absent built-ins in as disabled so admins can discover and enable them from the settings page without changing storefront behavior until they do.

Missing filters are positioned below every saved filter's "position" (preserving their relative order from default_storefront_filters/0) rather than reusing their default position outright — a saved config predating the new filter can already hold that same position number, and a tie would fall back to list order once enabled, silently overriding the intended placement (e.g. search no longer sorting first).

Notification types this module contributes (duck-typed, discovered by core's Notifications.Types).

Two audiences, deliberately separate sub-types so a shop operator can mute the order firehose without silencing their own receipts — and so a customer's confirmation is never governed by an admin-facing preference.

⚠️ The actions registered here are the NOTIFY actions. The audit trail uses different action strings on purpose: Activity.log/1 auto-derives notifications from registered actions, so an audit row written with a notify action would deliver a second, duplicate notification.

Whether operators asked to be notified about the given storefront event.

@spec preview_checkout_totals(
  PhoenixKitEcommerce.Cart.t(),
  keyword()
) :: {:ok, PhoenixKitEcommerce.Cart.t()} | {:error, term()}

Applies the checkout billing country to the cart and recalculates totals, WITHOUT converting anything.

The review step must show the amount the customer is about to be charged. The cart page deliberately leaves shipping_country nil ("set at checkout"), and tax is zero for a nil-country cart — so before this existed, a customer reviewed a pre-tax total and convert_cart_to_order/2 then applied the country, recalculated, and charged more. Cart 100.00 + shipping 10.00 at 20%: review said 110.00, the order said 130.00.

That gap opened the moment tax started working at all, so it ships with the same change. Runs the identical country resolution and recalculation the conversion uses, so the two cannot disagree.

Takes the same :billing_profile_uuid / :billing_data options as convert_cart_to_order/2. Returns the reloaded cart.

Returns a map of category_uuid => product_count for all categories.

Checks if a product slug exists for a language.

Useful for validation during translation editing.

Examples

iex> Shop.product_slug_exists?("maceta-geometrica", "es-ES")
true

iex> Shop.product_slug_exists?("maceta-geometrica", "es-ES", exclude_uuid: "some-uuid")
false

@spec product_url(PhoenixKitEcommerce.Product.t(), String.t()) :: String.t()

Generates a localized URL for a product.

Returns the correct locale-prefixed URL with translated slug. The URL respects the PhoenixKit URL prefix configuration.

Parameters

• product - The Product struct
• language - Language code (e.g., "en-US", "ru", "es-ES")

Examples

iex> Shop.product_url(product, "es-ES")
"/es/shop/product/maceta-geometrica"

iex> Shop.product_url(product, "ru")
"/ru/shop/product/geometricheskoe-kashpo"

iex> Shop.product_url(product, "en")
"/shop/product/geometric-planter"  # Default language - no prefix

@spec rekey_cart_session(String.t(), String.t()) :: :ok | :error

Moves a live guest cart from one shop-session id to another.

Used by the pre-signing cookie migration. The plug mints a FRESH id and re-keys the cart onto it, rather than re-signing whatever the client presented — re-signing a replayed value would have turned it into a fully trusted session on the very next request, which is the capability the signing exists to prevent.

Scoped to active, unclaimed carts for the same reason session_has_cart?/1 is: a converted or account-owned cart must never be re-keyed by an unsigned cookie. Returns :ok when exactly one cart moved.

Removes item from cart.

@spec session_has_cart?(String.t() | any()) :: boolean()

Whether any cart exists for this shop session id.

Used by PhoenixKitEcommerce.Web.Plugs.ShopSession to decide whether an unsigned, pre-migration cookie names a real session worth adopting. Existence only — no cart is loaded and nothing is authorized by this.

Sets payment option for cart.

Sets shipping method for cart.

Sets the shipping country for the cart.

Where the buyer picks a shipping method: on the cart page (legacy) or as a checkout step after billing, when the destination country is known.

Effective shipping-skip mode for checkout.

• :off — shipping method required (legacy behavior)
• :fallback — required when available; orders proceed without one when no method covers the buyer's country
• :always — shipping step disabled entirely

@spec shipping_skippable?(PhoenixKitEcommerce.Cart.t()) ::
  false | {:skip, :always} | {:skip, :no_method_for_country}

Whether this cart may convert without a shipping method, and why.

The country checked is the effective checkout country - cart.shipping_country as of apply_checkout_shipping_country/2, which must have already run. Returns false (never skippable) when the mode is :off, or when the mode is :fallback but a method still covers the cart's country - that case stays a hard requirement, not a fallback.

Marks import as started.

Returns translation helpers module for direct access.

Examples

iex> Shop.translations()
PhoenixKitEcommerce.Translations

Updates item quantity in cart.

Updates a category.

Updates translation for a specific language on a category.

Parameters

• category - The category struct
• language - Language code (e.g., "es-ES")
• attrs - Translation attributes: name, slug, description

Examples

iex> Shop.update_category_translation(category, "es-ES", %{
...>   "name" => "Jarrones y Macetas",
...>   "slug" => "jarrones-macetas"
...> })
{:ok, %Category{}}

Updates an import config.

Updates an import log.

Updates import progress.

Updates a product.

Automatically normalizes metadata (price modifiers, option values) before saving to ensure consistent storage format.

Updates translation for a specific language on a product.

Parameters

• product - The product struct
• language - Language code (e.g., "es-ES")
• attrs - Translation attributes: title, slug, description, body_html, seo_title, seo_description

Examples

iex> Shop.update_product_translation(product, "es-ES", %{
...>   "title" => "Maceta Geométrica",
...>   "slug" => "maceta-geometrica"
...> })
{:ok, %Product{}}

Updates a shipping method.

Saves storefront filter configuration.

Creates or updates a product by slug.

Uses explicit find-or-create pattern with proper localized field merging. After V47 migration, slug is a JSONB map (e.g., %{"en-US" => "my-slug"}), so ON CONFLICT doesn't work correctly - this function handles the lookup manually.

Returns {:ok, product, action} where action is :inserted or :updated.

Parameters

• attrs - Product attributes including localized fields as maps

Examples

# Create new product
iex> upsert_product(%{title: %{"en-US" => "Planter"}, slug: %{"en-US" => "planter"}, price: 10})
{:ok, %Product{}, :inserted}

# Update existing product (found by slug)
iex> upsert_product(%{title: %{"en-US" => "Planter V2"}, slug: %{"en-US" => "planter"}, price: 15})
{:ok, %Product{}, :updated}

# Add translation to existing product
iex> upsert_product(%{title: %{"es-ES" => "Maceta"}, slug: %{"es-ES" => "maceta", "en-US" => "planter"}, price: 10})
{:ok, %Product{title: %{"en-US" => "Planter", "es-ES" => "Maceta"}}, :updated}

Validates selected_specs against product's option schema.

Checks:

• All spec keys exist in the option schema
• All spec values are in allowed values list (if defined)
• All required options have values

Returns

• :ok - All specs are valid
• {:error, :unknown_option_key, key} - Key not in schema
• {:error, :invalid_option_value, %{key: key, value: value, allowed: list}} - Value not allowed
• {:error, :missing_required_option, key} - Required option not provided

Examples

iex> validate_selected_specs(product, %{"material" => "PETG"})
:ok

iex> validate_selected_specs(product, %{"material" => "Unobtainium"})
{:error, :invalid_option_value, %{key: "material", value: "Unobtainium", allowed: ["PLA", "PETG"]}}