Visual Add to Cart

Last updated:
Edit on GitHub

Visual Add to Cart lets storefront users upload a product image on the Quick Order page. AI automatically recognizes the products in the image and populates the quick order form with matching catalog items.

For the business overview and storefront usage, see Visual Add to Cart.

Architecture

The feature is built on the AiFoundation abstraction layer, which decouples the image recognition logic from any specific AI provider. The AI model and provider are configured per named configuration entry, so you can swap or reconfigure them without changing application code.

The Yves-side plugin AiCommerceQuickOrderImageToCartFormPlugin handles the upload form and orchestrates the workflow. Catalog matching is done via a configurable text-similarity threshold to tolerate minor differences between AI-returned product names and catalog names.

How it works

  1. The user uploads an image on the Quick Order page.
  2. The system validates the file format and size.
  3. The image is encoded and sent to the AI model via the AiFoundation abstraction layer.
  4. The AI returns a list of recognized products with quantities.
  5. Each recognized product name is searched in the catalog.
  6. Matched products are added to the quick order form with their SKU and quantity.
  7. Products that are not matched generate a flash notification.

Configuration

The following options can be configured at the project level in AiCommerceConfig:

CONFIGURATION DEFAULT DESCRIPTION
isQuickOrderImageToCartEnabled() false Enables or disables the feature.
getQuickOrderImageToCartSupportedMimeTypes() image/jpeg, image/png Allowed upload MIME types.
getQuickOrderImageToCartMaxFileSizeInBytes() 10485760 (10 MB) Maximum upload file size.
getQuickOrderImageToCartMaxProducts() 20 Maximum number of products recognized per image.
getQuickOrderImageToCartTextSimilarityThresholdPercent() 30 Minimum word-overlap percentage required to consider a catalog match valid.
getQuickOrderImageToCartAiConfigurationName() null Named AI model configuration identifier used to look up the provider config from AiFoundation. When null, the default configuration is used.

System prompt

The prompt used to recognize products from an uploaded image on the Quick Order page is managed in the Back Office under AI Commerce > Quick Order > System Prompts. The default prompt is defined in ai_commerce.configuration.yml and can be customized per environment through the configuration UI or a project configuration file, without a code change.

CONFIGURATION KEY DESCRIPTION
AiCommerceConstants::CONFIGURATION_KEY_QUICK_ORDER_IMAGE_RECOGNITION_PROMPT Prompt used to recognize products and quantities from an uploaded image. Keeps the %s placeholder for the current store locale.

If the overridden prompt is blank or contains only whitespace, Visual Add to Cart falls back to the default prompt instead of sending an empty value to the AI provider.

Install

Install Visual Add to Cart