Install Smart PIM

Edit on GitHub

Smart PIM is an AI tool embedded in the Back Office product creation and editing pages. It provides AI-powered capabilities for improving product content, generating image alt text, suggesting categories, and translating product data. This document describes how to install the Smart PIM feature.

Install the feature core

Follow the steps in the following sections to install the Smart PIM feature core.

Prerequisites

Install the required features:

NAME VERSION INSTALLATION GUIDE
AI Commerce 202606.0 Install AI Commerce
Product Management 202606.0

Make sure the following modules are installed at the required minimum versions:

MODULE MINIMUM VERSION
spryker/ai-commerce ^0.4.2
spryker/product-category ^4.33.1
spryker/product-management ^0.20.9
spryker/product-management-extension ^1.11.0
spryker-shop/quick-order-page-extension ^1.3.0

1) Generate transfers and run database migration

console transfer:generate
console propel:install

2) Add configuration constants

Add the project-level constants interface to define the Smart PIM configuration name and the Back Office setting keys:

src/Pyz/Shared/AiCommerce/AiCommerceConstants.php

<?php

declare(strict_types = 1);

namespace Pyz\Shared\AiCommerce;

use SprykerFeature\Shared\AiCommerce\AiCommerceConstants as SprykerFeatureAiCommerceConstants;

interface AiCommerceConstants extends SprykerFeatureAiCommerceConstants
{
    public const string CONFIGURATION_KEY_OPENAI_API_TOKEN = 'ai_vendor:openai:general:api_token';
    public const string CONFIGURATION_KEY_SMART_PIM_AI_CONFIGURATION = 'ai_commerce:smart_pim:ai_vendor:ai_configuration';
    public const string CONFIGURATION_KEY_SMART_PIM_OPENAI_MODEL = 'ai_commerce:smart_pim:ai_vendor:openai_model';

    public const string AI_CONFIGURATION_SMART_PIM_OPENAI = 'AI_COMMERCE:AI_CONFIGURATION_SMART_PIM_OPENAI';
}

3) Configure AI models for Smart PIM

Add the Smart PIM named AI configuration entry to config/Shared/config_ai.php. The API token and model are resolved at runtime from the Back Office Configuration UI using the CONFIGURATION_REFERENCE_PREFIX:

config/Shared/config_ai.php

<?php

use Pyz\Shared\AiCommerce\AiCommerceConstants;
use Spryker\Shared\AiFoundation\AiFoundationConstants;

$config[AiFoundationConstants::AI_CONFIGURATIONS][AiCommerceConstants::AI_CONFIGURATION_SMART_PIM_OPENAI] = [
    'provider_name' => AiFoundationConstants::PROVIDER_OPENAI,
    'provider_config' => [
        'key' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_OPENAI_API_TOKEN,
        'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_SMART_PIM_OPENAI_MODEL,
    ],
];
Multiple AI providers

The example above registers an OpenAI configuration. To offer AWS Bedrock and Anthropic as selectable providers for Smart PIM, see Configure multiple AI providers.

4) Configure Smart PIM

Override AiCommerceConfig in the Zed layer to route all Smart PIM capabilities to the Smart PIM named configuration. Each capability reads the vendor selected in the Back Office and returns the matching configuration name, defaulting to the OpenAI configuration:

src/Pyz/Zed/AiCommerce/AiCommerceConfig.php

<?php

declare(strict_types = 1);

namespace Pyz\Zed\AiCommerce;

use Pyz\Shared\AiCommerce\AiCommerceConstants;
use SprykerFeature\Zed\AiCommerce\AiCommerceConfig as SprykerFeatureAiCommerceConfig;

class AiCommerceConfig extends SprykerFeatureAiCommerceConfig
{
    public function getContentImproverAiConfigurationName(): ?string
    {
        return $this->getSmartPimAiConfigurationName();
    }

    public function getImageAltTextAiConfigurationName(): ?string
    {
        return $this->getSmartPimAiConfigurationName();
    }

    public function getCategorySuggestionAiConfigurationName(): ?string
    {
        return $this->getSmartPimAiConfigurationName();
    }

    public function getTranslationAiConfigurationName(): ?string
    {
        return $this->getSmartPimAiConfigurationName();
    }

    protected function getSmartPimAiConfigurationName(): ?string
    {
        return $this->getModuleConfig(
            AiCommerceConstants::CONFIGURATION_KEY_SMART_PIM_AI_CONFIGURATION,
            AiCommerceConstants::AI_CONFIGURATION_SMART_PIM_OPENAI,
        );
    }
}

5) Set up behavior

Register the following plugins to wire Smart PIM into the product management form.

Register the category lifecycle plugins in ProductDependencyProvider:

PLUGIN SPECIFICATION PREREQUISITES NAMESPACE
ProductCategoryProductAbstractPostCreatePlugin Saves category assignments when an abstract product is created. Required for Smart PIM category suggestions to be persisted. Spryker\Zed\ProductCategory\Communication\Plugin\Product
ProductCategoryProductAbstractAfterUpdatePlugin Updates category assignments when an abstract product is updated. Required for Smart PIM category suggestions to be persisted. Spryker\Zed\ProductCategory\Communication\Plugin\Product

src/Pyz/Zed/Product/ProductDependencyProvider.php

<?php

namespace Pyz\Zed\Product;

use Spryker\Zed\Kernel\Container;
use Spryker\Zed\Product\ProductDependencyProvider as SprykerProductDependencyProvider;
use Spryker\Zed\ProductCategory\Communication\Plugin\Product\ProductCategoryProductAbstractAfterUpdatePlugin;
use Spryker\Zed\ProductCategory\Communication\Plugin\Product\ProductCategoryProductAbstractPostCreatePlugin;

class ProductDependencyProvider extends SprykerProductDependencyProvider
{
    /**
     * @return array<\Spryker\Zed\ProductExtension\Dependency\Plugin\ProductAbstractPostCreatePluginInterface>
     */
    protected function getProductAbstractPostCreatePlugins(): array
    {
        return [
            // ... other plugins
            new ProductCategoryProductAbstractPostCreatePlugin(),
        ];
    }

    /**
     * @param \Spryker\Zed\Kernel\Container $container
     *
     * @return array<\Spryker\Zed\ProductExtension\Dependency\Plugin\ProductAbstractAfterUpdatePluginInterface>
     */
    protected function getProductAbstractAfterUpdatePlugins(Container $container): array
    {
        return [
            // ... other plugins
            new ProductCategoryProductAbstractAfterUpdatePlugin(),
        ];
    }
}

Register the product form plugins in ProductManagementDependencyProvider:

PLUGIN SPECIFICATION PREREQUISITES NAMESPACE
ProductCategoryAbstractFormExpanderPlugin Adds the category field to the abstract product form, enabling Smart PIM to populate and display category suggestions. Spryker\Zed\ProductCategory\Communication\Plugin\ProductManagement
ProductManagementAiProductAbstractFormTabContentProviderWithPriorityPlugin Adds the Smart PIM AI panel as a tab content provider in the abstract product form. SprykerFeature\Zed\AiCommerce\Communication\Plugin\ProductManagement

src/Pyz/Zed/ProductManagement/ProductManagementDependencyProvider.php

<?php

namespace Pyz\Zed\ProductManagement;

use Spryker\Zed\ProductManagement\ProductManagementDependencyProvider as SprykerProductManagementDependencyProvider;
use Spryker\Zed\ProductCategory\Communication\Plugin\ProductManagement\ProductCategoryAbstractFormExpanderPlugin;
use SprykerFeature\Zed\AiCommerce\Communication\Plugin\ProductManagement\ProductManagementAiProductAbstractFormTabContentProviderWithPriorityPlugin;

class ProductManagementDependencyProvider extends SprykerProductManagementDependencyProvider
{
    /**
     * @return array<\Spryker\Zed\ProductManagementExtension\Dependency\Plugin\ProductAbstractFormExpanderPluginInterface>
     */
    protected function getProductAbstractFormExpanderPlugins(): array
    {
        return [
            // ... other plugins
            new ProductCategoryAbstractFormExpanderPlugin(),
        ];
    }

    /**
     * @return array<\Spryker\Zed\ProductManagementExtension\Dependency\Plugin\ProductAbstractFormTabContentProviderWithPriorityPluginInterface>
     */
    protected function getProductAbstractFormTabContentProviderWithPriorityPlugins(): array
    {
        return [
            // ... other plugins
            new ProductManagementAiProductAbstractFormTabContentProviderWithPriorityPlugin(),
        ];
    }
}

Register the Twig plugin to make Smart PIM Twig utilities available in the Back Office:

PLUGIN SPECIFICATION PREREQUISITES NAMESPACE
AiCommerceTwigPlugin Registers Twig functions and variables required by Smart PIM modals on product pages. SprykerFeature\Zed\AiCommerce\Communication\Plugin\Twig

src/Pyz/Zed/Twig/TwigDependencyProvider.php

<?php

namespace Pyz\Zed\Twig;

use Spryker\Zed\Twig\TwigDependencyProvider as SprykerTwigDependencyProvider;
use SprykerFeature\Zed\AiCommerce\Communication\Plugin\Twig\AiCommerceTwigPlugin;

class TwigDependencyProvider extends SprykerTwigDependencyProvider
{
    /**
     * @return array<\Spryker\Shared\TwigExtension\Dependency\Plugin\TwigPluginInterface>
     */
    protected function getTwigPlugins(): array
    {
        return [
            // ... other plugins
            new AiCommerceTwigPlugin(),
        ];
    }
}

6) Extend product management templates

Override the following product management Twig templates to include the Smart PIM AI modals partial. Each template extends its core counterpart and includes the partial in the content block:

src/Pyz/Zed/ProductManagement/Presentation/Add/index.twig


{% extends '@Spryker:ProductManagement/Add/index.twig' %}
{% block content %}
    {{ parent() }}
    {% include '@SprykerFeature:AiCommerce/SmartProductManagement/_partials/product-management-ai-modals.twig' ignore missing %}
{% endblock %}

src/Pyz/Zed/ProductManagement/Presentation/AddVariant/index.twig


{% extends '@Spryker:ProductManagement/AddVariant/index.twig' %}
{% block content %}
    {{ parent() }}
    {% include '@SprykerFeature:AiCommerce/SmartProductManagement/_partials/product-management-ai-modals.twig' ignore missing %}
{% endblock %}

src/Pyz/Zed/ProductManagement/Presentation/Edit/index.twig


{% extends '@Spryker:ProductManagement/Edit/index.twig' %}
{% block content %}
    {{ parent() }}
    {% include '@SprykerFeature:AiCommerce/SmartProductManagement/_partials/product-management-ai-modals.twig' ignore missing %}
{% endblock %}

src/Pyz/Zed/ProductManagement/Presentation/Edit/variant.twig


{% extends '@Spryker:ProductManagement/Edit/variant.twig' %}
{% block content %}
    {{ parent() }}
    {% include '@SprykerFeature:AiCommerce/SmartProductManagement/_partials/product-management-ai-modals.twig' ignore missing %}
{% endblock %}

Verification

In the Back Office, open a product create or edit page. Make sure the Smart PIM AI panel is visible in the product form.

7) Sync configuration and build frontend assets

Define the AI configuration and model settings for Smart PIM in data/configuration/ai_commerce.configuration.yml. These settings back the configuration:: references registered in config/Shared/config_ai.php, so they must exist before syncing:

data/configuration/ai_commerce.configuration.yml

features:
    - key: ai_commerce
      tabs:
          - key: smart_pim
            name: Smart PIM
            description: Smart PIM AI configuration shared across category suggestion, translation, image alt text, and content improver features.
            enabled: true
            order: 3
            groups:
                - key: ai_vendor
                  name: AI Vendor
                  description: AI configuration and vendor model used for all Smart PIM features (category suggestion, translation, image alt text, content improver). Only the model field matching the selected AI Configuration is shown.
                  enabled: true
                  order: 1
                  scopes:
                      - global
                  settings:
                      - key: ai_configuration
                        name: AI Configuration
                        description: AI configuration used for all Smart PIM features (category suggestion, translation, image alt text, content improver).
                        type: radio
                        default_value: 'AI_COMMERCE:AI_CONFIGURATION_SMART_PIM_OPENAI'
                        enabled: true
                        secret: false
                        storefront: false
                        order: 1
                        scopes:
                            - global
                        options:
                            - value: 'AI_COMMERCE:AI_CONFIGURATION_SMART_PIM_OPENAI'
                              label: OpenAI
                            - value: 'AI_COMMERCE:AI_CONFIGURATION_SMART_PIM_AWS'
                              label: AWS Bedrock
                            - value: 'AI_COMMERCE:AI_CONFIGURATION_SMART_PIM_ANTHROPIC'
                              label: Anthropic
                      - key: openai_model
                        name: OpenAI Model
                        description: The OpenAI model used for the Smart PIM AI configuration. Model must support image input and structured output.
                        type: string
                        default_value: 'gpt-4o-mini'
                        enabled: true
                        secret: false
                        storefront: false
                        order: 2
                        scopes:
                            - global
                        dependencies:
                            - when:
                                  any:
                                      - setting: ai_commerce:smart_pim:ai_vendor:ai_configuration
                                        operator: equals
                                        value: 'AI_COMMERCE:AI_CONFIGURATION_SMART_PIM_OPENAI'
                      - key: aws_model
                        name: AWS Bedrock Model
                        description: The AWS Bedrock model identifier used for the Smart PIM AI configuration. Model must support image input and structured output.
                        type: string
                        default_value: 'eu.anthropic.claude-haiku-4-5-20251001-v1:0'
                        enabled: true
                        secret: false
                        storefront: false
                        order: 3
                        scopes:
                            - global
                        dependencies:
                            - when:
                                  any:
                                      - setting: ai_commerce:smart_pim:ai_vendor:ai_configuration
                                        operator: equals
                                        value: 'AI_COMMERCE:AI_CONFIGURATION_SMART_PIM_AWS'
                      - key: anthropic_model
                        name: Anthropic Model
                        description: The Anthropic model used for the Smart PIM AI configuration. Model must support image input and structured output.
                        type: string
                        default_value: 'claude-haiku-4-5'
                        enabled: true
                        secret: false
                        storefront: false
                        order: 4
                        scopes:
                            - global
                        dependencies:
                            - when:
                                  any:
                                      - setting: ai_commerce:smart_pim:ai_vendor:ai_configuration
                                        operator: equals
                                        value: 'AI_COMMERCE:AI_CONFIGURATION_SMART_PIM_ANTHROPIC'

Sync the AI Commerce configuration to the database and build frontend assets:

console configuration:sync
console frontend:project:install-dependencies
console frontend:zed:build
console twig:cache:warmer

8) Configure OpenAI settings

Set the OpenAI API credentials and model settings in the Back Office:

  1. In the Back Office, go to AI Commerce > Open AI.
  2. Enter the OpenAI API Token.
  3. Set the OpenAI Default Model (default: gpt-4o) and OpenAI Smart Model (default: gpt-4.1).
  4. Click Save.
Verification

In the Back Office, open a product create or edit page and use a Smart PIM capability such as content improvement or category suggestion. Make sure the AI returns a valid response.