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

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

@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(PhoenixKit.Modules.Shop.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"

Clears all items from cart.

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.

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 localized fields from new attributes into existing product.

Preserves existing translations while adding new ones from attrs. Non-localized fields are replaced entirely.

Examples

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

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(PhoenixKit.Modules.Shop.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

Removes item from cart.

Sets payment option for cart.

Sets shipping method for cart.

Sets the shipping country for the cart.

Marks import as started.

Returns translation helpers module for direct access.

Examples

iex> Shop.translations()
PhoenixKit.Modules.Shop.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"]}}