# PhoenixKitEcommerce v0.5.0 - Table of Contents

> E-commerce module for PhoenixKit — products, categories, cart, checkout

## Modules

- [PhoenixKit.Modules.Shop.Cart](PhoenixKit.Modules.Shop.Cart.md): Compat alias for PhoenixKitEcommerce.Cart.
Used as Ecto schema in queries (from(c in PhoenixKit.Modules.Shop.Cart, ...)).

- [PhoenixKit.Modules.Shop.Web.Plugs.ShopSession](PhoenixKit.Modules.Shop.Web.Plugs.ShopSession.md): Compat alias for PhoenixKitEcommerce.Web.Plugs.ShopSession.
Must be a real Plug so `plug` macro works.

- [PhoenixKit.Modules.Shop.Web.Routes](PhoenixKit.Modules.Shop.Web.Routes.md): Compat alias for PhoenixKitEcommerce.Web.Routes.

- [PhoenixKit.Modules.Shop.Web.UserOrderDetails](PhoenixKit.Modules.Shop.Web.UserOrderDetails.md): Compat alias for PhoenixKitEcommerce.Web.UserOrderDetails.
LiveView — delegates mount, handle_params.

- [PhoenixKit.Modules.Shop.Web.UserOrders](PhoenixKit.Modules.Shop.Web.UserOrders.md): Compat alias for PhoenixKitEcommerce.Web.UserOrders.
LiveView — delegates mount, handle_params, handle_event.

- [PhoenixKitEcommerce](PhoenixKitEcommerce.md): E-commerce Shop Module for PhoenixKit.
- [PhoenixKitEcommerce.AITranslatable](PhoenixKitEcommerce.AITranslatable.md): `PhoenixKitAI.Translatable` adapter for shop products.
- [PhoenixKitEcommerce.Activity](PhoenixKitEcommerce.Activity.md): Thin wrapper around `PhoenixKit.Activity.log/1` for the shop module.
- [PhoenixKitEcommerce.Cart](PhoenixKitEcommerce.Cart.md): Shopping cart schema with support for guest and authenticated users.
- [PhoenixKitEcommerce.CartItem](PhoenixKitEcommerce.CartItem.md): Cart item schema with price snapshot for consistency.
- [PhoenixKitEcommerce.Catalogue.CategoryCommerce](PhoenixKitEcommerce.Catalogue.CategoryCommerce.md): Embedded schema for the shop fields a catalogue category stores under
`category.data["ecommerce"]`. See `PhoenixKitEcommerce.Catalogue.ItemCommerce`
moduledoc for the discovery contract this namespace is reached through.

- [PhoenixKitEcommerce.Catalogue.Extension](PhoenixKitEcommerce.Catalogue.Extension.md): Structurally implements `PhoenixKitCatalogue.Extension` — the catalogue
item/category form "extension slot" (spec §2 principle 8). `phoenix_kit_catalogue`
is an optional dependency, so this module does NOT declare `@behaviour
PhoenixKitCatalogue.Extension`; that would force it to be loaded at
compile time. Discovery is duck-typed, the same pattern as
`PhoenixKitEcommerce.AITranslatable` / `ai_translatables/0`: catalogue
finds this module via `PhoenixKitEcommerce.catalogue_extensions/0` and is
responsible for checking it is actually usable before calling it.

- [PhoenixKitEcommerce.Catalogue.ItemCommerce](PhoenixKitEcommerce.Catalogue.ItemCommerce.md): Embedded schema for the shop fields a catalogue item stores under
`item.data["ecommerce"]`.
- [PhoenixKitEcommerce.Catalogue.SetSlug](PhoenixKitEcommerce.Catalogue.SetSlug.md): Normalizes a Shopify option name (e.g. `"Cup Color"`, `"Größe"`) into the
bare attribute-set slug `Writer.sync_variants/2` looks the catalogue set
up by (`"catalogue_set_" <> slug` is the blueprint's own `:name`).
- [PhoenixKitEcommerce.Catalogue.ShopSections](PhoenixKitEcommerce.Catalogue.ShopSections.md): Function components rendering the "Shop" section that
`PhoenixKitEcommerce.Catalogue.Extension` adds to the catalogue item and
category forms. Field names/labels are ported from
`PhoenixKitEcommerce.Web.ProductForm`'s Pricing card and
`PhoenixKitEcommerce.Web.CategoryForm`'s basic-fields card, adapted to the
`item[ecommerce][...]` / `category[ecommerce][...]` namespace the
extension slot absorbs (see `PhoenixKitCatalogue.Extensions.absorb/3`).
- [PhoenixKitEcommerce.Catalogue.ValueResolver](PhoenixKitEcommerce.Catalogue.ValueResolver.md): Resolves a raw label — text as it arrives from an external source such
as a Shopify option value ("Small", "Rouge") — to the value SLUG a
catalogue attribute set already uses for that same choice, creating a
new `draft` value when the set has none matching.
- [PhoenixKitEcommerce.Catalogue.Writer](PhoenixKitEcommerce.Catalogue.Writer.md): Writes Shopify sync changes into `phoenix_kit_catalogue` items — the
write side of Block 3's "sync 6a" (`docs/superpowers/specs/2026-09-05-
catalogue-as-shop-product-list-design.md` §5 Блок 3) and Block 7's 6b
(same doc, same §, "Блок 7"), active only when `ProductSource.
current/0` is `Catalogue`. `update_from_shopify/3`/`create_from_shopify/2`
are called by `PhoenixKitEcommerce.Shopify.Sync`; `sync_variants/2` (and
the images/collections writers Block 7 adds alongside it) is called
directly by the sync worker instead — nothing here touches
`phoenix_kit_shop_products` (the legacy writer, `Shop.update_product/2`,
stays the write path for the legacy source).
- [PhoenixKitEcommerce.Category](PhoenixKitEcommerce.Category.md): Category schema for product organization.
- [PhoenixKitEcommerce.Errors](PhoenixKitEcommerce.Errors.md): Central mapping from the error atoms returned by the e-commerce module's
context, importers, image services, and web layer to translated
human-readable strings.
- [PhoenixKitEcommerce.Events](PhoenixKitEcommerce.Events.md): PubSub event broadcasting for Shop module.
- [PhoenixKitEcommerce.Gettext](PhoenixKitEcommerce.Gettext.md): Gettext backend for `phoenix_kit_ecommerce`.
- [PhoenixKitEcommerce.HtmlText](PhoenixKitEcommerce.HtmlText.md): Plain-text extraction from HTML.
- [PhoenixKitEcommerce.HtmlToMarkdown](PhoenixKitEcommerce.HtmlToMarkdown.md): Converts HTML (as Shopify's `body_html` product field always is) into
Markdown.
- [PhoenixKitEcommerce.Import.CSVAnalyzer](PhoenixKitEcommerce.Import.CSVAnalyzer.md): Analyze Shopify CSV files to extract option metadata.
- [PhoenixKitEcommerce.Import.CSVParser](PhoenixKitEcommerce.Import.CSVParser.md): Parse Shopify CSV and group rows by Handle.
- [PhoenixKitEcommerce.Import.CSVValidator](PhoenixKitEcommerce.Import.CSVValidator.md): Validates CSV files before import processing.
- [PhoenixKitEcommerce.Import.Filter](PhoenixKitEcommerce.Import.Filter.md): Filter products for import based on configurable rules.
- [PhoenixKitEcommerce.Import.FormatDetector](PhoenixKitEcommerce.Import.FormatDetector.md): Auto-detect CSV format from file headers.
- [PhoenixKitEcommerce.Import.ImportFormat](PhoenixKitEcommerce.Import.ImportFormat.md): Behaviour for CSV import format adapters.
- [PhoenixKitEcommerce.Import.Money](PhoenixKitEcommerce.Import.Money.md): Money parsing for supplier CSV feeds.
- [PhoenixKitEcommerce.Import.OptionBuilder](PhoenixKitEcommerce.Import.OptionBuilder.md): Build option values and price modifiers from Shopify variant rows.
- [PhoenixKitEcommerce.Import.ProductTransformer](PhoenixKitEcommerce.Import.ProductTransformer.md): Transform Shopify CSV rows into PhoenixKit Product format.
- [PhoenixKitEcommerce.Import.PromUaFormat](PhoenixKitEcommerce.Import.PromUaFormat.md): Prom.ua CSV format adapter implementing `ImportFormat` behaviour.
- [PhoenixKitEcommerce.Import.ShopifyCSV](PhoenixKitEcommerce.Import.ShopifyCSV.md): Main orchestrator for Shopify CSV import.
- [PhoenixKitEcommerce.Import.ShopifyFormat](PhoenixKitEcommerce.Import.ShopifyFormat.md): Shopify CSV format adapter implementing `ImportFormat` behaviour.
- [PhoenixKitEcommerce.ImportConfig](PhoenixKitEcommerce.ImportConfig.md): ImportConfig schema for configurable CSV import filtering.
- [PhoenixKitEcommerce.ImportLog](PhoenixKitEcommerce.ImportLog.md): ImportLog schema for tracking CSV import history.
- [PhoenixKitEcommerce.LocalizedSlug](PhoenixKitEcommerce.LocalizedSlug.md): Shared per-language slug generation for Product and Category.
- [PhoenixKitEcommerce.Migrations](PhoenixKitEcommerce.Migrations.md): Module-owned migration chain for the shop tables (`phoenix_kit_shop_config`,
`phoenix_kit_shop_shipping_methods`, `phoenix_kit_shop_categories`,
`phoenix_kit_shop_products`, `phoenix_kit_shop_product_slugs`,
`phoenix_kit_shop_category_slugs`, `phoenix_kit_shop_carts`,
`phoenix_kit_shop_cart_items`, `phoenix_kit_shop_import_configs`,
`phoenix_kit_shop_import_logs`) plus the two slug-projection functions and
their triggers.
- [PhoenixKitEcommerce.Notifications](PhoenixKitEcommerce.Notifications.md): Shop notifications: who hears about an order or an import, and when.
- [PhoenixKitEcommerce.OptionTypes](PhoenixKitEcommerce.OptionTypes.md): Supported option types for product options.
- [PhoenixKitEcommerce.Options](PhoenixKitEcommerce.Options.md): Context for managing product options.
- [PhoenixKitEcommerce.Options.MetadataValidator](PhoenixKitEcommerce.Options.MetadataValidator.md): Validates and normalizes product metadata for options and pricing.
- [PhoenixKitEcommerce.Policy](PhoenixKitEcommerce.Policy.md): Admin-controllable policy for the shop, in one place.
- [PhoenixKitEcommerce.PriceDisplay](PhoenixKitEcommerce.PriceDisplay.md): How a price is written on the storefront: `From €40.00 /hour`.
- [PhoenixKitEcommerce.Product](PhoenixKitEcommerce.Product.md): Product schema for e-commerce shop.
- [PhoenixKitEcommerce.ProductSource](PhoenixKitEcommerce.ProductSource.md): Behaviour for the storefront's product/category read path.
- [PhoenixKitEcommerce.ProductSource.Catalogue](PhoenixKitEcommerce.ProductSource.Catalogue.md): `ProductSource` adapter reading `phoenix_kit_catalogue` items/categories
and returning hand-built `%Product{}`/`%Category{}` view-structs (see
`PhoenixKitEcommerce.ProductSource.Catalogue.View`) so the facade,
`Options`, `PriceDisplay`, `CartItem` and the storefront never need to
know which adapter is active.
- [PhoenixKitEcommerce.ProductSource.Catalogue.Query](PhoenixKitEcommerce.ProductSource.Catalogue.Query.md): Ecto queries over `phoenix_kit_catalogue`'s `Item`/`Category` schemas,
scoped to the one catalogue the shop reads (`get_config("shop_catalogue")`,
default name `"decor3dprint"`, resolved through `Catalogue.list_catalogues/0`).
- [PhoenixKitEcommerce.ProductSource.Catalogue.View](PhoenixKitEcommerce.ProductSource.Catalogue.View.md): Builds hand-built `%PhoenixKitEcommerce.Product{}` / `%PhoenixKitEcommerce.Category{}`
view-structs from a `phoenix_kit_catalogue` item/category, so the facade,
`Options`, `PriceDisplay`, `CartItem` and the storefront templates read
exactly the field names they read today from `phoenix_kit_shop_products`/
`phoenix_kit_shop_categories` — no behavior change on their side.
- [PhoenixKitEcommerce.ProductSource.Legacy](PhoenixKitEcommerce.ProductSource.Legacy.md): `ProductSource` adapter over `phoenix_kit_shop_products` and
`phoenix_kit_shop_categories`.
- [PhoenixKitEcommerce.Services.ImageDownloader](PhoenixKitEcommerce.Services.ImageDownloader.md): Service for downloading images from external URLs and storing them in the Storage module.
- [PhoenixKitEcommerce.Services.ImageMigration](PhoenixKitEcommerce.Services.ImageMigration.md): Orchestrates batch migration of product images from external URLs to Storage module.
- [PhoenixKitEcommerce.ShippingMethod](PhoenixKitEcommerce.ShippingMethod.md): Shipping method schema for E-Commerce module.
- [PhoenixKitEcommerce.ShopConfig](PhoenixKitEcommerce.ShopConfig.md): Shop configuration storage schema (key-value JSONB).
- [PhoenixKitEcommerce.Shopify.AdminClient](PhoenixKitEcommerce.Shopify.AdminClient.md): Thin REST client for the Shopify Admin API's `products.json` endpoint.
- [PhoenixKitEcommerce.Shopify.CollectionSync](PhoenixKitEcommerce.Shopify.CollectionSync.md): Maps Shopify collections onto catalogue categories, preserving both
orders — Block 7 Task 4 (`docs/superpowers/plans/2026-09-06-block7-
shopify-media-collections.md`, §5 Блок 7 in the design spec), with the
live-store allowlist and most-specific assignment added by Block 7b
Task 2 (`docs/superpowers/plans/2026-09-06-block7b-shopify-live-fixes.md`)
— the real store has 143 collections, of which only ~12
`3d-printed-*` ones are our categories; the rest (an "all products",
a curated cross-category "featured" mix, per-tag collections, ...)
must never become categories or move an item at all.
- [PhoenixKitEcommerce.Shopify.ProductDiff](PhoenixKitEcommerce.Shopify.ProductDiff.md): Compares local products against Shopify Admin API product data.
- [PhoenixKitEcommerce.Shopify.ProductDiff.Change](PhoenixKitEcommerce.Shopify.ProductDiff.Change.md): One local product's field-by-field diff against its matched Shopify
product. `changes` only contains fields that actually differ, keyed by
field atom, each holding `%{current:, incoming:}`. `price_extreme?` is
true only when `:price` is in `changes` and the current/incoming ratio
exceeds 3x.
- [PhoenixKitEcommerce.Shopify.Provider](PhoenixKitEcommerce.Shopify.Provider.md): `PhoenixKit.Integrations` provider definition for Shopify.
- [PhoenixKitEcommerce.Shopify.Source](PhoenixKitEcommerce.Shopify.Source.md): Picks where a sync reads Shopify product data from: the Admin API
(primary, full-fidelity) or the public storefront JSON endpoint
(fallback, price-only — see `PhoenixKitEcommerce.Shopify.StorefrontClient`
for why it is deliberately narrow).
- [PhoenixKitEcommerce.Shopify.StorefrontClient](PhoenixKitEcommerce.Shopify.StorefrontClient.md): Reads live product/price data from a store's public storefront JSON
endpoint (`/products.json`) — no Admin API token required, because
nothing is authenticated. This is the fallback price source: when the
Admin API token configured for a store is missing or rejected, price
sync keeps working through this keyless path instead of stalling until
someone notices and rotates the token.
- [PhoenixKitEcommerce.Shopify.Sync](PhoenixKitEcommerce.Shopify.Sync.md): Orchestrates a Shopify → local product sync: fetch, diff, and selectively
apply confirmed changes.
- [PhoenixKitEcommerce.Shopify.TextDiff](PhoenixKitEcommerce.Shopify.TextDiff.md): Word-level diff between two versions of a text field.
- [PhoenixKitEcommerce.Shopify.VariantMapper](PhoenixKitEcommerce.Shopify.VariantMapper.md): Pure mapping from a Shopify Admin API product payload's `"options"`/
`"variants"` into the shape `PhoenixKitEcommerce.Catalogue.Writer.
sync_variants/2` attaches as catalogue attribute sets: one set per real
option (Shopify's auto-generated single-option "no variants" product —
option name `"Title"`, its lone value `"Default Title"` — is skipped,
same as it never becomes a `_option_slots` entry on the legacy CSV
path), values in the order they first appear across `variants[]`, and
a per-value price modifier.
- [PhoenixKitEcommerce.SlugResolver](PhoenixKitEcommerce.SlugResolver.md): Resolves URL slugs to Products and Categories with language awareness.
- [PhoenixKitEcommerce.Translations](PhoenixKitEcommerce.Translations.md): Localized fields helper for Shop module.
- [PhoenixKitEcommerce.Vocabulary](PhoenixKitEcommerce.Vocabulary.md): What the storefront calls the things it sells.
- [PhoenixKitEcommerce.Web](PhoenixKitEcommerce.Web.md): Provides common imports and setup for Shop module LiveViews.
- [PhoenixKitEcommerce.Web.Authz](PhoenixKitEcommerce.Web.Authz.md): Sub-permission checks for the bundled admin LiveViews.
- [PhoenixKitEcommerce.Web.CartPage](PhoenixKitEcommerce.Web.CartPage.md): Public cart page LiveView for E-Commerce module.
- [PhoenixKitEcommerce.Web.Carts](PhoenixKitEcommerce.Web.Carts.md): Carts admin list LiveView for E-Commerce module.

- [PhoenixKitEcommerce.Web.CatalogCategory](PhoenixKitEcommerce.Web.CatalogCategory.md): Public shop category page.
Shows products filtered by category.

- [PhoenixKitEcommerce.Web.CatalogProduct](PhoenixKitEcommerce.Web.CatalogProduct.md): Public product detail page with add-to-cart functionality.
- [PhoenixKitEcommerce.Web.Categories](PhoenixKitEcommerce.Web.Categories.md): Categories list LiveView for Shop module.
- [PhoenixKitEcommerce.Web.CategoryForm](PhoenixKitEcommerce.Web.CategoryForm.md): Category create/edit form LiveView for Shop module.
- [PhoenixKitEcommerce.Web.CheckoutComplete](PhoenixKitEcommerce.Web.CheckoutComplete.md): Order confirmation page after successful checkout.

- [PhoenixKitEcommerce.Web.CheckoutPage](PhoenixKitEcommerce.Web.CheckoutPage.md): Checkout page LiveView for converting cart to order.
Supports both logged-in users (with billing profiles) and guest checkout.
- [PhoenixKitEcommerce.Web.Components.CatalogSidebar](PhoenixKitEcommerce.Web.Components.CatalogSidebar.md): Reusable sidebar component for the shop storefront.
- [PhoenixKitEcommerce.Web.Components.FilterHelpers](PhoenixKitEcommerce.Web.Components.FilterHelpers.md): Shared helpers for storefront filter state management.
- [PhoenixKitEcommerce.Web.Components.SettingRows](PhoenixKitEcommerce.Web.Components.SettingRows.md): Rows for the admin settings cards: a title and its explanation on the
left, the control on the right.
- [PhoenixKitEcommerce.Web.Components.ShopCards](PhoenixKitEcommerce.Web.Components.ShopCards.md): Reusable product display components for the shop storefront.
- [PhoenixKitEcommerce.Web.Components.ShopLayouts](PhoenixKitEcommerce.Web.Components.ShopLayouts.md): Shared layout wrapper for the shop storefront public pages.
- [PhoenixKitEcommerce.Web.Components.TranslationTabs](PhoenixKitEcommerce.Web.Components.TranslationTabs.md): Translation tabs component for Shop module forms.
- [PhoenixKitEcommerce.Web.Dashboard](PhoenixKitEcommerce.Web.Dashboard.md): E-Commerce module dashboard LiveView.
- [PhoenixKitEcommerce.Web.Helpers](PhoenixKitEcommerce.Web.Helpers.md): Shared helper functions for Shop public LiveViews.
- [PhoenixKitEcommerce.Web.ImportConfigs](PhoenixKitEcommerce.Web.ImportConfigs.md): Import configurations management LiveView.
- [PhoenixKitEcommerce.Web.ImportShow](PhoenixKitEcommerce.Web.ImportShow.md): LiveView for displaying import details.
- [PhoenixKitEcommerce.Web.Imports](PhoenixKitEcommerce.Web.Imports.md): Admin LiveView for managing CSV product imports.
- [PhoenixKitEcommerce.Web.OptionState](PhoenixKitEcommerce.Web.OptionState.md): Encapsulates option-related state for product form.
- [PhoenixKitEcommerce.Web.OptionsSettings](PhoenixKitEcommerce.Web.OptionsSettings.md): Global product options settings LiveView.
- [PhoenixKitEcommerce.Web.Plugs.ShopSession](PhoenixKitEcommerce.Web.Plugs.ShopSession.md): Plug that ensures a persistent shop session ID exists.
- [PhoenixKitEcommerce.Web.ProductDetail](PhoenixKitEcommerce.Web.ProductDetail.md): Product detail view LiveView for Shop module.

- [PhoenixKitEcommerce.Web.ProductForm](PhoenixKitEcommerce.Web.ProductForm.md): Product create/edit form LiveView for Shop module.
- [PhoenixKitEcommerce.Web.Products](PhoenixKitEcommerce.Web.Products.md): Products list LiveView for Shop module.

- [PhoenixKitEcommerce.Web.Routes](PhoenixKitEcommerce.Web.Routes.md): Shop module routes.
- [PhoenixKitEcommerce.Web.SEOHelpers](PhoenixKitEcommerce.Web.SEOHelpers.md): Catalog SEO assigns (canonical / hreflang / og) for the public shop
LiveViews, multi-domain aware.
- [PhoenixKitEcommerce.Web.Settings](PhoenixKitEcommerce.Web.Settings.md): E-Commerce module settings LiveView.
- [PhoenixKitEcommerce.Web.ShippingMethodForm](PhoenixKitEcommerce.Web.ShippingMethodForm.md): Shipping method create/edit form LiveView.

- [PhoenixKitEcommerce.Web.ShippingMethods](PhoenixKitEcommerce.Web.ShippingMethods.md): Shipping methods list LiveView for E-Commerce module admin.

- [PhoenixKitEcommerce.Web.ShopCatalog](PhoenixKitEcommerce.Web.ShopCatalog.md): Public shop catalog main page.
Shows categories and featured/active products.

- [PhoenixKitEcommerce.Web.ShopifySync](PhoenixKitEcommerce.Web.ShopifySync.md): Admin LiveView for the Shopify → shop one-way sync.
- [PhoenixKitEcommerce.Web.TestShop](PhoenixKitEcommerce.Web.TestShop.md): Test module for verifying Shop functionality:
- Specification price modifiers (fixed and percent)
- Storage image integration
- Price calculation

- [PhoenixKitEcommerce.Web.UserOrderDetails](PhoenixKitEcommerce.Web.UserOrderDetails.md): LiveView for displaying order details to the order owner.
- [PhoenixKitEcommerce.Web.UserOrders](PhoenixKitEcommerce.Web.UserOrders.md): LiveView for displaying user's shop orders.
- [PhoenixKitEcommerce.Workers.CSVImportWorker](PhoenixKitEcommerce.Workers.CSVImportWorker.md): Oban worker for background CSV import.
- [PhoenixKitEcommerce.Workers.ImageMigrationWorker](PhoenixKitEcommerce.Workers.ImageMigrationWorker.md): Oban worker for migrating product images from external URLs to Storage module.
- [PhoenixKitEcommerce.Workers.ShopifyMediaSyncWorker](PhoenixKitEcommerce.Workers.ShopifyMediaSyncWorker.md): Oban worker driving the three Block 7 catalogue writers as background
jobs — Task 5 of `docs/superpowers/plans/2026-09-06-block7-shopify-
media-collections.md`.
- [PromUaCSV](PromUaCSV.md)
- [ShopifyCSV](ShopifyCSV.md)
- [ValidatorCSV](ValidatorCSV.md)

## Mix Tasks

- [mix phoenix_kit_ecommerce.deduplicate_products](Mix.Tasks.PhoenixKitEcommerce.DeduplicateProducts.md): Finds and merges duplicate products by slug.
- [mix phoenix_kit_ecommerce.install](Mix.Tasks.PhoenixKitEcommerce.Install.md): Installs PhoenixKit E-commerce module into parent application.

