Spryker Documentation

Configure multiple AI providers for AI Commerce

Wed, 13 May 2026 12:41:46 +0000

AI Commerce supports three AI providers: OpenAI, AWS Bedrock, and Anthropic. Each feature — Back Office Assistant, Visual Add to Cart (Quick Order), Search by Image, and Smart PIM — can use a different provider independently. This lets you optimize cost, latency, or capability per feature without changing any application code.

How it works

Each AI Commerce feature resolves its active provider at runtime by reading a named AI configuration from AiFoundationConstants::AI_CONFIGURATIONS. The configuration key used is controlled by a Back Office setting stored in the database. When you switch a feature to a different provider in the Back Office, it starts reading a different entry from the configuration map on the next request.

The config/Shared/config_ai.php file must define a configuration entry for every provider-feature combination you want to make available.

Prerequisites

AI Commerce is installed. For instructions, see Install AI Commerce.
You have credentials for the providers you want to use.

1) Configure AI providers in config_ai.php

The following example configures all three providers for all AI Commerce features. Include only the configurations for providers you plan to use.

config/Shared/config_ai.php

<?php

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

$config[AiFoundationConstants::AI_CONFIGURATIONS] = [

    // Smart PIM
    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,
        ],
    ],
    AiCommerceConstants::AI_CONFIGURATION_SMART_PIM_AWS => [
        'provider_name' => AiFoundationConstants::PROVIDER_BEDROCK,
        'provider_config' => [
            'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_SMART_PIM_AWS_MODEL,
            'bedrockRuntimeClient' => [
                'region' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_AWS_REGION,
                'token' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_AWS_API_TOKEN,
            ],
        ],
    ],
    AiCommerceConstants::AI_CONFIGURATION_SMART_PIM_ANTHROPIC => [
        'provider_name' => AiFoundationConstants::PROVIDER_ANTHROPIC,
        'provider_config' => [
            'key' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_ANTHROPIC_API_TOKEN,
            'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_SMART_PIM_ANTHROPIC_MODEL,
        ],
    ],

    // Quick Order Image-to-Cart (Visual Add to Cart)
    AiCommerceConstants::AI_CONFIGURATION_QUICK_ORDER_IMAGE_TO_CART_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_QUICK_ORDER_IMAGE_TO_CART_OPENAI_MODEL,
        ],
    ],
    AiCommerceConstants::AI_CONFIGURATION_QUICK_ORDER_IMAGE_TO_CART_AWS => [
        'provider_name' => AiFoundationConstants::PROVIDER_BEDROCK,
        'provider_config' => [
            'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_QUICK_ORDER_IMAGE_TO_CART_AWS_MODEL,
            'bedrockRuntimeClient' => [
                'region' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_AWS_REGION,
                'token' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_AWS_API_TOKEN,
            ],
        ],
    ],
    AiCommerceConstants::AI_CONFIGURATION_QUICK_ORDER_IMAGE_TO_CART_ANTHROPIC => [
        'provider_name' => AiFoundationConstants::PROVIDER_ANTHROPIC,
        'provider_config' => [
            'key' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_ANTHROPIC_API_TOKEN,
            'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_QUICK_ORDER_IMAGE_TO_CART_ANTHROPIC_MODEL,
        ],
    ],

    // Search by Image
    AiCommerceConstants::AI_CONFIGURATION_SEARCH_BY_IMAGE_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_SEARCH_BY_IMAGE_OPENAI_MODEL,
        ],
    ],
    AiCommerceConstants::AI_CONFIGURATION_SEARCH_BY_IMAGE_AWS => [
        'provider_name' => AiFoundationConstants::PROVIDER_BEDROCK,
        'provider_config' => [
            'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_SEARCH_BY_IMAGE_AWS_MODEL,
            'bedrockRuntimeClient' => [
                'region' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_AWS_REGION,
                'token' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_AWS_API_TOKEN,
            ],
        ],
    ],
    AiCommerceConstants::AI_CONFIGURATION_SEARCH_BY_IMAGE_ANTHROPIC => [
        'provider_name' => AiFoundationConstants::PROVIDER_ANTHROPIC,
        'provider_config' => [
            'key' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_ANTHROPIC_API_TOKEN,
            'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_SEARCH_BY_IMAGE_ANTHROPIC_MODEL,
        ],
    ],

    // Back Office Assistant (Intent Router, General, Order Management, Discount Management, Form Fill)
    AiCommerceConstants::AI_CONFIGURATION_INTENT_ROUTER_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_BACKOFFICE_ASSISTANT_OPENAI_MODEL,
        ],
    ],
    AiCommerceConstants::AI_CONFIGURATION_INTENT_ROUTER_AWS => [
        'provider_name' => AiFoundationConstants::PROVIDER_BEDROCK,
        'provider_config' => [
            'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_AWS_MODEL,
            'bedrockRuntimeClient' => [
                'region' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_AWS_REGION,
                'token' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_AWS_API_TOKEN,
            ],
        ],
    ],
    AiCommerceConstants::AI_CONFIGURATION_INTENT_ROUTER_ANTHROPIC => [
        'provider_name' => AiFoundationConstants::PROVIDER_ANTHROPIC,
        'provider_config' => [
            'key' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_ANTHROPIC_API_TOKEN,
            'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_ANTHROPIC_MODEL,
        ],
    ],
    AiCommerceConstants::AI_CONFIGURATION_GENERAL_AGENT_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_BACKOFFICE_ASSISTANT_OPENAI_MODEL,
        ],
        'system_prompt' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_GENERAL_PURPOSE_SYSTEM_PROMPT,
    ],
    AiCommerceConstants::AI_CONFIGURATION_GENERAL_AGENT_AWS => [
        'provider_name' => AiFoundationConstants::PROVIDER_BEDROCK,
        'provider_config' => [
            'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_AWS_MODEL,
            'bedrockRuntimeClient' => [
                'region' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_AWS_REGION,
                'token' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_AWS_API_TOKEN,
            ],
        ],
        'system_prompt' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_GENERAL_PURPOSE_SYSTEM_PROMPT,
    ],
    AiCommerceConstants::AI_CONFIGURATION_GENERAL_AGENT_ANTHROPIC => [
        'provider_name' => AiFoundationConstants::PROVIDER_ANTHROPIC,
        'provider_config' => [
            'key' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_ANTHROPIC_API_TOKEN,
            'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_ANTHROPIC_MODEL,
        ],
        'system_prompt' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_GENERAL_PURPOSE_SYSTEM_PROMPT,
    ],
    AiCommerceConstants::AI_CONFIGURATION_ORDER_MANAGEMENT_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_BACKOFFICE_ASSISTANT_OPENAI_MODEL,
        ],
        'system_prompt' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_ORDER_MANAGEMENT_SYSTEM_PROMPT,
    ],
    AiCommerceConstants::AI_CONFIGURATION_ORDER_MANAGEMENT_AWS => [
        'provider_name' => AiFoundationConstants::PROVIDER_BEDROCK,
        'provider_config' => [
            'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_AWS_MODEL,
            'bedrockRuntimeClient' => [
                'region' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_AWS_REGION,
                'token' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_AWS_API_TOKEN,
            ],
        ],
        'system_prompt' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_ORDER_MANAGEMENT_SYSTEM_PROMPT,
    ],
    AiCommerceConstants::AI_CONFIGURATION_ORDER_MANAGEMENT_ANTHROPIC => [
        'provider_name' => AiFoundationConstants::PROVIDER_ANTHROPIC,
        'provider_config' => [
            'key' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_ANTHROPIC_API_TOKEN,
            'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_ANTHROPIC_MODEL,
        ],
        'system_prompt' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_ORDER_MANAGEMENT_SYSTEM_PROMPT,
    ],
    AiCommerceConstants::AI_CONFIGURATION_DISCOUNT_MANAGEMENT_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_BACKOFFICE_ASSISTANT_OPENAI_MODEL,
        ],
        'system_prompt' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_DISCOUNT_MANAGEMENT_SYSTEM_PROMPT,
    ],
    AiCommerceConstants::AI_CONFIGURATION_DISCOUNT_MANAGEMENT_AWS => [
        'provider_name' => AiFoundationConstants::PROVIDER_BEDROCK,
        'provider_config' => [
            'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_AWS_MODEL,
            'bedrockRuntimeClient' => [
                'region' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_AWS_REGION,
                'token' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_AWS_API_TOKEN,
            ],
        ],
        'system_prompt' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_DISCOUNT_MANAGEMENT_SYSTEM_PROMPT,
    ],
    AiCommerceConstants::AI_CONFIGURATION_DISCOUNT_MANAGEMENT_ANTHROPIC => [
        'provider_name' => AiFoundationConstants::PROVIDER_ANTHROPIC,
        'provider_config' => [
            'key' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_ANTHROPIC_API_TOKEN,
            'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_ANTHROPIC_MODEL,
        ],
        'system_prompt' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_DISCOUNT_MANAGEMENT_SYSTEM_PROMPT,
    ],
    AiCommerceConstants::AI_CONFIGURATION_FORM_FILL_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_BACKOFFICE_ASSISTANT_OPENAI_MODEL,
        ],
        'system_prompt' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_FORM_FILL_SYSTEM_PROMPT,
    ],
    AiCommerceConstants::AI_CONFIGURATION_FORM_FILL_AWS => [
        'provider_name' => AiFoundationConstants::PROVIDER_BEDROCK,
        'provider_config' => [
            'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_AWS_MODEL,
            'bedrockRuntimeClient' => [
                'region' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_AWS_REGION,
                'token' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_AWS_API_TOKEN,
            ],
        ],
        'system_prompt' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_FORM_FILL_SYSTEM_PROMPT,
    ],
    AiCommerceConstants::AI_CONFIGURATION_FORM_FILL_ANTHROPIC => [
        'provider_name' => AiFoundationConstants::PROVIDER_ANTHROPIC,
        'provider_config' => [
            'key' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_ANTHROPIC_API_TOKEN,
            'model' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_ANTHROPIC_MODEL,
        ],
        'system_prompt' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . AiCommerceConstants::CONFIGURATION_KEY_FORM_FILL_SYSTEM_PROMPT,
    ],
];

The configuration values that use CONFIGURATION_REFERENCE_PREFIX are resolved at runtime from the Back Office configuration database. This means model names and API tokens are managed in the Back Office rather than hardcoded in config files.

2) Sync the AI vendor configuration

The AI vendor credentials (API tokens, AWS region) are managed through the Back Office configuration system. Sync the vendor configuration schema to the database:

console configuration:sync

3) Set credentials in the Back Office

In the Back Office, go to AI Vendor.
For each provider you want to use, open its tab (OpenAI, Anthropic, or AWS Bedrock) and enter the credentials:

PROVIDER	REQUIRED CREDENTIALS
OpenAI	API token
Anthropic	API key
AWS Bedrock	API token, AWS region

Click Save.

Environment variable alternative

You can also supply the OpenAI API token via the OPEN_AI_API_TOKEN environment variable. When set, it is used as the runtime default without storing the value in the database. For details, see Configuration Management: Environment Variable Defaults.

4) Select the active provider per feature

Each AI Commerce feature has an AI Configuration radio selector in the Back Office that controls which provider it uses.

In the Back Office, go to AI Commerce.
Open the tab for the feature you want to configure (for example, Smart PIM, Quick Order, Search by Image, or Back Office Assistant).
Under General, select the active provider: OpenAI, AWS Bedrock, or Anthropic.
Optionally, update the model name shown for the selected provider. Each provider shows its model field only when selected.
Click Save.

Default models per feature and provider:

FEATURE	OPENAI	AWS BEDROCK	ANTHROPIC
Smart PIM	`gpt-4o-mini`	`eu.anthropic.claude-haiku-4-5-20251001-v1:0`	`claude-haiku-4-5`
Quick Order Image-to-Cart	`gpt-4o-mini`	`eu.anthropic.claude-haiku-4-5-20251001-v1:0`	`claude-haiku-4-5`
Search by Image	`gpt-4o-mini`	`eu.anthropic.claude-haiku-4-5-20251001-v1:0`	`claude-haiku-4-5`
Back Office Assistant	`gpt-4.1`	`eu.anthropic.claude-sonnet-4-5-20250929-v1:0`	`claude-sonnet-4-5`

Model requirements

All AI Commerce features require a model that supports image input and structured output. Verify that the model you select meets these requirements for the provider you use.

Configuration reference

The following table maps each feature to its configuration constants and the Back Office setting key that controls the active provider.

FEATURE	ACTIVE PROVIDER SETTING KEY	OPENAI CONFIG CONSTANT	AWS CONFIG CONSTANT	ANTHROPIC CONFIG CONSTANT
Smart PIM	`ai_commerce:smart_pim:general:ai_configuration`	`AI_CONFIGURATION_SMART_PIM_OPENAI`	`AI_CONFIGURATION_SMART_PIM_AWS`	`AI_CONFIGURATION_SMART_PIM_ANTHROPIC`
Quick Order Image-to-Cart	`ai_commerce:quick_order:general:ai_configuration`	`AI_CONFIGURATION_QUICK_ORDER_IMAGE_TO_CART_OPENAI`	`AI_CONFIGURATION_QUICK_ORDER_IMAGE_TO_CART_AWS`	`AI_CONFIGURATION_QUICK_ORDER_IMAGE_TO_CART_ANTHROPIC`
Search by Image	`ai_commerce:search_by_image:general:ai_configuration`	`AI_CONFIGURATION_SEARCH_BY_IMAGE_OPENAI`	`AI_CONFIGURATION_SEARCH_BY_IMAGE_AWS`	`AI_CONFIGURATION_SEARCH_BY_IMAGE_ANTHROPIC`
Back Office Assistant	`ai_commerce:backoffice_assistant:general:ai_configuration`	`AI_CONFIGURATION_INTENT_ROUTER_OPENAI` (and `_GENERAL_AGENT_OPENAI`, `_ORDER_MANAGEMENT_OPENAI`, `_DISCOUNT_MANAGEMENT_OPENAI`, `_FORM_FILL_OPENAI`)	`AI_CONFIGURATION_INTENT_ROUTER_AWS` (and `_AWS` variants)	`AI_CONFIGURATION_INTENT_ROUTER_ANTHROPIC` (and `_ANTHROPIC` variants)

All constants are in SprykerFeature\Shared\AiCommerce\AiCommerceConstants.

Configuration Management feature

Wed, 13 May 2026 12:34:48 +0000

What It Does

Provides a centralized, schema-driven system for managing application settings across scopes (for example global, store, custom-scope). Settings are declared in YAML files, managed via the Back Office UI, to be consumed in different layers (Zed, Yves, Glue) through module Config classes.

Quick Start

1. Declare settings in a YAML schema

# /data/configuration/my-module.configuration.yml
features:
  - key: my_module
    name: My Module
    tabs:
      - key: general
        name: General
        groups:
          - key: display
            name: Display Settings
            scopes: [global, store]
            settings:
              - key: items_per_page
                name: Items Per Page
                type: integer
                default_value: 24
                scopes: [global, store]
                storefront: true
                constraints:
                  - type: required
                    message: Items per page is required
                  - type: min
                    message: Must be at least 1
                    options: { min: 1 }

2. Sync schemas

docker/sdk cli console configuration:sync

3. Consume in your module Config

namespace Spryker\Yves\MyModule;

use Spryker\Yves\Kernel\AbstractBundleConfig;

class MyModuleConfig extends AbstractBundleConfig
{
    protected const int DEFAULT_ITEMS_PER_PAGE = 24;

    protected const string CONFIGURATION_KEY_MY_MODULE_GENERAL_DISPLAY_ITEMS_PER_PAGE = 'my_module:general:display:items_per_page';

    public function getItemsPerPage(): int
    {
        return $this->getModuleConfig(static::CONFIGURATION_KEY_MY_MODULE_GENERAL_DISPLAY_ITEMS_PER_PAGE, static::DEFAULT_ITEMS_PER_PAGE);
    }
}

The getModuleConfig() method is available in Zed, Yves, Glue layers AbstractBundleConfig and is the preferred way to read configuration values.

Reading Configuration Values

The `getModuleConfig()` Method

Every AbstractBundleConfig in Zed, Yves, and Glue provides:

protected function getModuleConfig(
    string $key,
    mixed $default = null,
    array $configurationScopes = [],
): mixed

Parameter	Type	Description
`$key`	string	Compound setting key: `feature:tab:group:setting`
`$default`	mixed	Fallback when value is not found or Configuration module is not installed
`$configurationScopes`	`ConfigurationScopeTransfer[]`	Optional scope context transfers

Layer behavior:

Yves / Glue: Reads from key-value storage via ConfigurationClient (fast, cached)
Zed: Reads from database via ConfigurationFacade (supports secrets, full scope resolution)

Backward Compatible: If the Configuration module is not installed, getModuleConfig() silently returns $default.

Real-World Examples

AvailabilityWidget (Yves) – boolean setting with constant fallback:

class AvailabilityWidgetConfig extends AbstractBundleConfig
{
    protected const bool STOCK_DISPLAY_ENABLED = false;

    public const string STOCK_DISPLAY_MODE_INDICATOR_AND_QUANTITY = 'indicator_and_quantity';

    protected const string CONFIGURATION_KEY_CATALOG_INVENTORY_STOCK_OPTIONS_DISPLAY_STOCK_AVAILABILITY = 'catalog:inventory:stock_options:display_stock_availability';

    protected const string CONFIGURATION_KEY_CATALOG_INVENTORY_STOCK_OPTIONS_STOCK_INFO_OPTIONS = 'catalog:inventory:stock_options:stock_info_options';

    public function isStockDisplayEnabled(): bool
    {
        return $this->getModuleConfig(static::CONFIGURATION_KEY_CATALOG_INVENTORY_STOCK_OPTIONS_DISPLAY_STOCK_AVAILABILITY, static::STOCK_DISPLAY_ENABLED);
    }

    public function getStockDisplayMode(): string
    {
        return $this->getModuleConfig(static::CONFIGURATION_KEY_CATALOG_INVENTORY_STOCK_OPTIONS_STOCK_INFO_OPTIONS, static::STOCK_DISPLAY_MODE_INDICATOR_AND_QUANTITY);
    }
}

BuyBox (Yves) – string setting with enum fallback:

class BuyBoxConfig extends AbstractBundleConfig
{
    public const string SORT_BY_PRICE = 'price';

    protected const string CONFIGURATION_KEY_MARKETPLACE_PDP_BUY_BOX_OFFER_SORT_RULE = 'marketplace:pdp:buy_box:offer_sort_rule';

    public function getSortingStrategy(): string
    {
        return $this->getModuleConfig(static::CONFIGURATION_KEY_MARKETPLACE_PDP_BUY_BOX_OFFER_SORT_RULE, static::SORT_BY_PRICE);
    }
}

Scope-Specific Reads

Pass ConfigurationScopeTransfer objects as the third argument when you need a scope-specific value:

use Generated\Shared\Transfer\ConfigurationScopeTransfer;

public function getItemsPerPage(string $storeName): int
{
    protected const string CONFIGURATION_KEY_MY_MODULE_GENERAL_DISPLAY_ITEMS_PER_PAGE = 'my_module:general:display:items_per_page';

    return $this->getModuleConfig(
        static::CONFIGURATION_KEY_MY_MODULE_GENERAL_DISPLAY_ITEMS_PER_PAGE,
        static::DEFAULT_ITEMS_PER_PAGE,
        [
            (new ConfigurationScopeTransfer())
                ->setKey('store')
                ->setIdentifier($storeName),
        ],
    );
}

Integration Checklist

When integrating Configuration into an existing module:

Identify hardcoded values or constants that should be configurable
Declare them in a YAML schema in data/configuration/
Replace hardcoded access in the module’s Config class with getModuleConfig() calls
Keep the original constant as $default for backward compatibility
Run configuration:sync
Values are now manageable via the Back Office Configuration Management page

YAML Schema Declaration Reference

Schema Validation

YAML schema files support IDE autocompletion via JSON Schema. Add this header to your file:

# yaml-language-server: $schema=../../vendor/spryker/configuration/resources/configuration/configuration-schema-v1.json

The schema file is located at vendor/spryker/configuration/resources/configuration/configuration-schema-v1.json.

Hierarchy

features[]
  tabs[]
    groups[]
      settings[]

Each setting gets a compound key: {featureKey}:{tabKey}:{groupKey}:{settingKey} used for persistence and lookups.

Feature Level

features:
  - key: system                          # Required. Unique feature identifier.
    name: System Configuration           # Required. Display name in backoffice.
    description: Core system settings    # Optional. Feature description (shown as tooltip).
    order: 0                             # Optional. Sort order (lower = first).
    enabled: true                        # Optional. Default: true.
    status: beta                         # Optional. Status badge (beta, early_access).
    tabs: [...]                          # Required. At least one tab.

Property	Type	Required	Default	Constraints	Description
`key`	string	Yes	–	`^[a-z][a-z0-9_]*$`	Unique identifier. Part of compound setting key.
`name`	string	Yes	–	1-255 chars	Display name in backoffice sidebar.
`description`	string	No	`null`	max 1000 chars	Feature description text. Shown as tooltip in sidebar.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, feature and all children are hidden from the backoffice, search results, and settings map.
`status`	string	No	`null`	`beta`, `early_access`	Status badge displayed next to the feature name. Invalid values are silently ignored.
`tabs`	array	Yes	–	min 1 item	List of tab objects.

Tab Level

tabs:
  - key: general                         # Required. Unique within feature.
    name: General                        # Required. Tab display name.
    icon: settings                       # Optional. Icon class for backoffice tab.
    description: General system settings # Optional. Tab description (shown as tooltip).
    order: 0                             # Optional. Sort order (lower = first).
    enabled: true                        # Optional. Default: true.
    status: early_access                 # Optional. Status badge.
    groups: [...]                        # Required. At least one group.

Property	Type	Required	Default	Constraints	Description
`key`	string	Yes	–	`^[a-z][a-z0-9_]*$`	Unique within feature. Part of compound setting key.
`name`	string	Yes	–	1-255 chars	Tab label in backoffice.
`icon`	string	No	`null`	max 100 chars	Material Symbols icon name (for example `settings`, `cable`, `trending_up`).
`description`	string	No	`null`	max 1000 chars	Tab description text. Shown as tooltip in sidebar.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, tab and all children are hidden from the backoffice, search results, and settings map.
`status`	string	No	`null`	`beta`, `early_access`	Status badge displayed next to the tab name.
`groups`	array	Yes	–	min 1 item	List of group objects.

Group Level

groups:
  - key: basic                           # Required. Unique within tab.
    name: Basic Settings                 # Required. Group display name.
    description: Basic system config     # Optional. Group description.
    scopes: [global, store]              # Required. Scopes this group is visible for.
    order: 0                             # Optional. Sort order (lower = first).
    enabled: true                        # Optional. Default: true.
    status: beta                         # Optional. Status badge.
    settings: [...]                      # Required. At least one setting.

Property	Type	Required	Default	Constraints	Description
`key`	string	Yes	–	`^[a-z][a-z0-9_]*$`	Unique within tab.
`name`	string	Yes	–	1-255 chars	Group heading in backoffice.
`description`	string	No	`null`	max 1000 chars	Group description text.
`scopes`	string[]	Yes	`['global']`	min 1 item	Scopes where this group is displayed in backoffice. Setting scopes are constrained to their parent group scopes.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, group and all settings are hidden from the backoffice, search results, and settings map.
`status`	string	No	`null`	`beta`, `early_access`	Status badge displayed next to the group heading.
`settings`	array	Yes	–	min 1 item	List of setting objects.

Setting Level

settings:
  - key: site_name                       # Required. Unique within group.
    name: Site Name                      # Required. Setting label.
    description: The name of the site    # Optional. Displayed below the input.
    note: Changes require cache clear    # Optional. Additional note below description.
    placeholder: Enter your store name   # Optional. Input placeholder text.
    help_text: Appears in page titles    # Optional. Tooltip or help area text.
    template: '@MyModule/Configuration/custom-input.twig'  # Optional. Custom Twig template.
    type: string                         # Required. Data type.
    default_value: My Store              # Optional. Fallback value.
    default_value_env_var: MY_ENV_VAR    # Optional. Env var override for default value.
    options:                             # Optional. For select/multiselect/radio types.
      - value: option_a
        label: Option A
    scopes: [global, store]              # Optional. Default: ['global'].
    order: 0                             # Optional. Sort order (lower = first).
    enabled: true                        # Optional. Default: true.
    status: early_access                 # Optional. Status badge.
    secret: false                        # Optional. Default: false.
    storefront: true                     # Optional. Default: false.
    constraints: [...]                   # Optional. Validation constraints.
    dependencies: [...]                  # Optional. Conditional visibility rules.
    sanitize_xss: {...}                  # Optional. XSS sanitization rules.
    data_object: \My\DataProvider        # Optional. Data provider plugin class.

Property	Type	Required	Default	Constraints	Description
`key`	string	Yes	–	`^[a-z][a-z0-9_]*$`	Unique within group. Part of compound key.
`name`	string	Yes	–	1-255 chars	Input label in backoffice.
`description`	string	No	`null`	max 1000 chars	Help text displayed below the input field.
`note`	string	No	`null`	max 1000 chars	Additional note displayed below the description in italic.
`placeholder`	string	No	`null`	max 255 chars	Placeholder text inside the input field.
`help_text`	string	No	`null`	max 500 chars	Extended help in tooltip or expandable area.
`template`	string	No	`null`	max 255 chars	Custom Twig template. Overrides type-based widget.
`type`	string	Yes	–	See types table	Value data type. Determines backoffice input widget.
`default_value`	mixed	No	`null`	Must match `type`	Fallback when no value is saved at any scope.
`default_value_env_var`	string	No	`null`	`^[A-Z][A-Z0-9_]*$`	Name of an environment variable. When set and the variable is defined in the process environment, its value is used as the effective default at runtime, taking precedence over `default_value`. Intended primarily for secrets — the resolved value is never persisted to the database.
`options`	option[]	No	`[]`	For select/multi/radio	Available choices. See Options.
`scopes`	string[]	No	`['global']`	min 1 item	Scopes where this setting can be configured. Constrained to parent group scopes.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, setting is hidden from the backoffice, search results, and settings map.
`status`	string	No	`null`	`beta`, `early_access`	Status badge displayed next to the setting label.
`secret`	boolean	No	`false`	–	When `true`, value is encrypted in database. Never published to storage.
`storefront`	boolean	No	`false`	–	When `true`, value is published to key-value storage for Yves/Glue.
`constraints`	array	No	`[]`	–	Validation rules. See Constraints.
`dependencies`	array	No	`[]`	–	Conditional rules. See Dependencies.
`file_upload`	object	No	`null`	Required when `type: file`	File upload configuration. See File upload fields.
`sanitize_xss`	object	No	`{}`	–	XSS sanitization configuration. See XSS Sanitization.
`data_object`	string	No	`null`	Fully qualified class name	Plugin class implementing `ConfigurationSettingDataProviderPluginInterface`. Provides dynamic data to the setting at render time.

Setting Types

Type	Description	Backoffice Input	Requires `options`
`string`	Single-line text	Text input	No
`integer`	Whole number	Number input	No
`float`	Decimal number	Number input	No
`boolean`	True/false toggle	Checkbox/switch	No
`text`	Multi-line text or structured data	Textarea	No
`color`	Color hex value	Color picker	No
`json`	JSON structure	Code editor	No
`select`	Single choice from list	Dropdown	Yes
`multiselect`	Multiple choices from list	Multi-select	Yes
`radio`	Single choice from list	Radio buttons	Yes
`file`	File upload (stored as public URL)	File upload widget	No, but requires `file_upload` block

File upload fields

Use type: file for settings that accept a file upload (for example, logo images). The Back Office renders a file upload widget. After a successful upload, the public URL of the uploaded file is stored as the setting value. All file validation and storage are handled server-side using a configured Flysystem filesystem service.

When type: file is used, a file_upload block must be present on the setting. It configures the Flysystem service, allowed file types, size limit, and recommended display dimensions.

- key: bo_logo_url
  name: Back Office Logo
  type: file
  file_upload:
    storage_name: 'backoffice-media'
    allowed_mime_types:
      - 'image/png'
      - 'image/jpeg'
      - 'image/gif'
      - 'image/webp'
      - 'image/svg+xml'
    allowed_extensions:
      - '.png'
      - '.jpg'
      - '.jpeg'
      - '.gif'
      - '.webp'
      - '.svg'
    max_file_size: '10M'
    recommended_width_px: 290
    recommended_height_px: 77
  default_value: ''
  scopes: [global, store]
  enabled: true
  secret: false
  storefront: false

`file_upload` properties

Property	Type	Required	Description
`storage_name`	string	Yes	Flysystem filesystem service name. Must be configured in `FileSystemConstants::FILESYSTEM_SERVICE`.
`allowed_mime_types`	string[]	No	List of permitted MIME types. Upload is rejected if the file MIME type is not in the list.
`allowed_extensions`	string[]	No	List of permitted file extensions including the leading dot (for example `.png`).
`max_file_size`	string	No	Maximum allowed file size (for example `10M`, `2048K`). Rejected if exceeded.
`recommended_width_px`	integer	No	Recommended display width in pixels. Shown as a hint in the Back Office UI.
`recommended_height_px`	integer	No	Recommended display height in pixels. Shown as a hint in the Back Office UI.

The stored value is always a public URL returned by the Flysystem service after upload. To render the image in a Twig template, read it with configurationValue() and use it as an src attribute:

{% set logoUrl = configurationValue('theme:logos:logos:yves_logo_url', '') %}
{% if logoUrl is not empty %}
    <img src="{{ logoUrl | e('html_attr') }}" alt="Logo" />
{% endif %}

For Flysystem service setup (S3 in production, local fallback in development and CI), see Install the Basic Shop Theme feature.

Options

Required for select, multiselect, and radio types. Defines available choices.

options:
  - value: indicator_only
    label: Indicator Only
    description: Show only in-stock/out-of-stock indicator
  - value: indicator_and_quantity
    label: Indicator and Quantity
    description: Show indicator and exact stock count

Property	Type	Required	Constraints	Description
`value`	string	Yes	min 1 char	Internal value stored when selected.
`label`	string	Yes	1-255 chars	Display label shown in backoffice.
`description`	string	No	max 500 chars	Additional explanation (for radio buttons).

Environment Variable Defaults

Use default_value_env_var to source the effective default for a setting from a process environment variable at runtime. This is intended primarily for secrets such as API tokens, where you want the default resolved from a CI or deployment environment variable rather than hardcoded in the YAML file or stored in the database.

settings:
  - key: api_token
    name: API Token
    type: string
    default_value: ''
    default_value_env_var: OPEN_AI_API_TOKEN
    secret: true
    storefront: false

Behavior:

When the named environment variable is set in the process environment, its value is used as the runtime default instead of default_value.
When the variable is not set, default_value is used as normal.
default_value_env_var takes precedence over default_value but has lower precedence than a value explicitly saved in the database via the Back Office.
The resolved env var value is never persisted to the database.
The env var name must match the pattern ^[A-Z][A-Z0-9_]*$ (uppercase letters, digits, underscores; must start with a letter).

Secret vs Storefront Behavior

`secret`	`storefront`	Behavior
`false`	`false`	Plain text in database. Accessible only via Zed (`getModuleConfig()` in Zed Config).
`false`	`true`	Plain text. Published to key-value storage. Accessible in all layers via `getModuleConfig()`.
`true`	`false`	Encrypted in database. Decrypted on read in Zed only. Never published to storage.
`true`	`true`	Invalid combination. Secrets are always excluded from storage.

Available Scopes

Built-in scopes (enabled out of the box):

Scope	Description	Requires Identifier
`global`	Application-wide default	No
`store`	Store-specific override (for example DE, AT)	Yes

Default hierarchy: store -> global -> default_value. Values resolve from most specific to least specific.

For adding custom scopes, see Adding Custom Scopes.

Constraints

Validated server-side when saving values through the Back Office.

constraints:
  - type: required
    message: Site name is required
  - type: min
    message: Must be at least 1
    options:
      min: 1
  - type: max
    message: Cannot exceed 100
    options:
      max: 100

Property	Type	Required	Constraints	Description
`type`	string	Yes	See table	Constraint type identifier.
`message`	string	Yes	1-500 chars	Error message shown when validation fails.
`options`	object	No	Depends on type	Constraint-specific parameters.

Built-in Constraint Types

Type	Description	Required Options	Example
`required`	Value must not be blank	–	Mandatory fields
`min`	Minimum numeric value	`min` (number)	`options: { min: 1 }`
`max`	Maximum numeric value	`max` (number)	`options: { max: 100 }`
`range`	Value within numeric range	`min`, `max` (number)	`options: { min: 0, max: 100 }`
`length`	String length limits	`min` and/or `max`	`options: { min: 6, max: 128 }`
`email`	Email format validation	–	Email input fields
`url`	URL format validation	–	URL input fields
`regex`	Pattern matching	`pattern` (string)	`options: { pattern: '^G-[A-Z0-9]{10}$' }`
`choice`	Value from allowed list	`choices` (string[])	`options: { choices: ['a', 'b'] }`

Dependencies

Control conditional visibility of settings in the Back Office UI. A setting with dependencies is only shown when at least one dependency rule matches (OR logic between rules). Each rule uses a when clause with any (OR) or all (AND) condition grouping.

settings:
  - key: stock_info_options
    name: Stock Info Options
    type: radio
    dependencies:
      - when:
          any:
            - setting: catalog:inventory:stock_options:display_stock_availability
              operator: equals
              value: "true"

Multiple conditions with all (AND logic):

    dependencies:
      - when:
          all:
            - setting: system:general:basic:feature_enabled
              operator: equals
              value: "true"
            - setting: system:general:basic:mode
              operator: not_equals
              value: maintenance

Dependency Rule

Property	Type	Required	Description
`when`	object	Yes	Contains `any` or `all` array of conditions.

When Clause

Property	Type	Required	Description
`any`	condition[]	No	Setting is shown if any condition matches (OR).
`all`	condition[]	No	Setting is shown if all conditions match (AND).

One of any or all must be provided.

Condition

Property	Type	Required	Description
`setting`	string	Yes	Compound key of the setting this depends on.
`operator`	string	Yes	Comparison operator.
`value`	string	Yes	Value to compare against.

Dependency Operators

Operator	Description
`equals`	Setting value must equal the given value.
`not_equals`	Setting value must not equal the given value.
`greater_than`	Numeric: value must be greater than expected.
`less_than`	Numeric: value must be less than expected.
`contains`	String: value must contain the expected text.
`in`	Value must be in the given list.

XSS Sanitization

Settings with type: text or type: string can have XSS sanitization applied on save. The sanitize_xss block configures how HTML content is cleaned using the W3C HTML Sanitizer API via spryker/util-sanitize-xss.

settings:
  - key: custom_html_block
    name: Custom HTML Block
    type: text
    sanitize_xss:
      allow_safe_elements: true
      allow_static_elements: false
      force_https_urls: true
      allow_relative_links: false
      allowed_link_schemes:
        - https
        - mailto
      allowed_link_hosts:
        - example.com
      allow_elements:
        a: [href, class]
        strong: []
      allow_attributes:
        data-custom: ['*']

Property	Type	Default	Description
`allow_safe_elements`	boolean	`false`	Allow W3C safe baseline elements.
`allow_static_elements`	boolean	`false`	Allow W3C static baseline elements.
`force_https_urls`	boolean	`false`	Rewrite `http://` URLs to `https://`.
`allow_relative_links`	boolean	`false`	Allow relative link URLs.
`allowed_link_schemes`	string[]	`[]`	Allowed URL schemes (for example `https`, `mailto`).
`allowed_link_hosts`	string[]	`[]`	Allowed link hostnames.
`allow_elements`	object	`{}`	Map of element name to allowed attribute names.
`allow_attributes`	object	`{}`	Map of attribute name to allowed element names (`*` for all).

Status Badges

Features, tabs, groups, and settings can display a status badge in the Back Office UI to indicate lifecycle stage. Badges are informational only and do not affect behavior.

Valid values: beta, early_access. Invalid values are silently ignored during schema normalization.

features:
  - key: ai_recommendations
    status: beta
    tabs:
      - key: model
        status: early_access

Badges render as colored pills next to item names in both the sidebar navigation and content area.

Schema File Locations

Location	Purpose	Loaded By
`{Module Folder}/resources/configuration/`	Core module schemas	`configuration:sync`
`data/configuration/`	Project-level schema overrides	`configuration:sync`

Project schemas override core schemas at the setting level. Settings with the same compound key are completely replaced.

Merged output: data/configuration/merged-schema.php

Backoffice Management

Settings are managed at The Back office > Configuration. The page provides:

Feature sidebar navigation with collapsible feature groups
Tabbed layout per feature
Scope switcher (global, store with identifier)
Input widgets matching setting types (including JSON editor with syntax highlighting)
Status badges on features, tabs, groups, and settings
Inline validation with constraint error messages
“Revert to default” to delete scope-specific overrides
Batch save with per-field error reporting
Global search across all settings (debounced AJAX, filters sidebar navigation)
Override detection: settings overridden by project-level Config classes are shown as read-only with an explanation notice
Dependent settings: conditional visibility with automatic change tracking
Audit logging: all save operations (successful and failed) are logged to the security audit channel

Search

The search input in the top bar filters the sidebar navigation as you type. Search matches against translated names and descriptions at all schema levels (feature, tab, group, setting), as well as setting compound keys. Results are scoped to the currently selected scope.

The search uses a debounced AJAX call to GET /configuration/manage/search?term={term}&scope={scope} which returns matching feature-to-tab mappings. Non-matching features and tabs are hidden in the sidebar.

Override Detection

During configuration:sync, the system scans core Config classes across Yves, Zed, Glue, and Client layers for methods that use getModuleConfig(). If a project-level Config class overrides such a method without calling getModuleConfig(), the setting is flagged as overridden.

Overridden settings in the Back Office:

Input is disabled (read-only)
“Use Default” link is hidden
A notice displays the project class and method responsible for the override

Override warnings are also printed to the console during configuration:sync:

[WARNING] Configuration bypass: catalog:inventory:stock_options:display_stock_availability
  Core:    SprykerShop\Yves\AvailabilityWidget\AvailabilityWidgetConfig::isStockDisplayEnabled
  Project: Pyz\Yves\AvailabilityWidget\AvailabilityWidgetConfig::isStockDisplayEnabled

Twig Integration

The Configuration module exposes three Twig functions that let templates read configuration values directly without going through a PHP Config class. They are available through the following existing plugins — no additional registration is required:

Context	Plugin
Storefront (Yves)	`ShopUiTwigExtension`
Back Office and Merchant Portal (Zed)	`\Spryker\Zed\Twig\Communication\Plugin\Application\TwigApplicationPlugin`

Function	Description
`configurationValue(key, default)`	Returns a single configuration value by compound key.
`configurationValues(keys)`	Returns an associative array of values for a list of compound keys.

`configurationValue`

Returns a single value for the given compound key. Falls back to default if the key has no saved value.

{{ configurationValue('theme:backoffice:colors:bo_main_color', '#1ebea0') }}

<style>
    :root {
        --bo-main-color: {{ configurationValue('theme:backoffice:colors:bo_main_color', '#1ebea0') | e('css') }};
    }
</style>

`configurationValues`

Returns an associative array keyed by compound key. Useful when a template needs several values at once.

{% set colors = configurationValues([
    'theme:backoffice:colors:bo_main_color',
    'theme:logos:logos:backoffice_logo_url',
]) %}
<style>:root { --bo-main-color: {{ colors['theme:backoffice:colors:bo_main_color'] | e('css') }}; }</style>

Scope context

Twig functions read values in the current request’s scope context. Store-specific values are resolved automatically when a store scope is active.

Data Import

Configuration values can be bulk-imported from CSV files using the Spryker DataImport framework.

CSV format

>setting_key,scope,scope_identifier,value
catalog:general:display:items_per_page,global,,24
catalog:general:display:items_per_page,store,DE,48

Column	Required	Description
`setting_key`	Yes	Compound key. Must exist in merged YAML schema.
`scope`	Yes	Must be in `ConfigurationConfig::getAvailableScopes()`.
`scope_identifier`	Conditional	Empty for `global`, required for other scopes.
`value`	Yes	Validated against schema constraints.

Running the import

docker/sdk cli console data:import configuration-value
docker/sdk cli console data:import configuration-value -f path/to/custom.csv

The default CSV file is located at data/import/configuration_value.csv at the project level. A module-level template is also provided.

Behavior

Values are validated with the same constraints as Back Office saves.
Secret settings are skipped with a warning — secrets should only be set via the UI.
Duplicate rows overwrite (upsert behavior).
Audit logging and Publish & Synchronize are triggered per value.
Import runs inside the existing ConfigurationValueWriter transaction, so all validation passes before any persistence.

For setup instructions, see Install the Configuration Management feature.

Console Commands

Command	Description
`configuration:sync`	Merges YAML schemas, generates the settings map, and detects project-level overrides. Run after any schema change.
`data:import configuration-value`	Bulk-imports configuration values from CSV.

Common Issues

Symptom	Cause	Solution
`getModuleConfig()` always returns default	Setting `storefront: false`	Yves/Glue can only read storefront-enabled settings. Set `storefront: true` or use Zed Config.
`getModuleConfig()` always returns default	Configuration module not installed	Expected behavior. Method gracefully falls back to `$default`.
Value returns `null` despite being saved	Key mismatch	Compound key format is `feature:tab:group:setting`. Verify all four segments match the YAML schema.
Secret value empty in Yves	Expected behavior	Secrets are never published to storage. Access only via Zed.
Changes not visible after YAML edit	Schema not synced	Run `configuration:sync` after YAML changes.
Store-specific value not applied	Missing scope context	Pass `ConfigurationScopeTransfer` in third argument or register request expander plugins. See Adding Custom Scopes.
Setting visible despite `enabled: false`	Schema not synced	Run `configuration:sync`. The `enabled` flag is evaluated during sync and filtering.
Override notice on a setting	Project Config class bypasses `getModuleConfig()`	The project-level Config method overrides the core method without calling `getModuleConfig()`. Refactor the method to use `getModuleConfig()` or accept the override.

Optimizing Jenkins execution with the resource-aware queue worker

Wed, 13 May 2026 07:15:50 +0000

Spryker ships a **resource-aware queue worker** (`ResourceAwareQueueWorker`) that replaces the default queue worker with a production-grade implementation focused on system stability and efficient resource utilization. It is available starting from the `202512.0` release. This document explains the problem it solves, how to enable and configure it, how it works internally, and how to back-port the concept to older Spryker versions. ## Problem The default Spryker system requires a `queue:worker:start` command to be continuously running for each store to process queues. In multi-store setups, this creates several challenges: - **Jenkins executor exhaustion**: By default, Jenkins has two executors. With multiple stores, workers compete for executor slots, causing delays in content publishing. - **Unpredictable memory consumption**: Multiple workers processing heavy messages simultaneously can spike memory usage, causing crashes or out-of-memory (OOM) conditions. - **No resource awareness**: The default worker spawns child processes based on message presence, without considering available system resources. - **Per-store overhead**: Even stores with empty queues occupy an executor slot for scanning. ## Solution overview The resource-aware queue worker replaces per-store workers with a single worker that manages a fixed-size process pool and monitors system resources before spawning child processes. ![Resource-aware queue worker diagram](https://spryker.s3.eu-central-1.amazonaws.com/docs/scos/dev/tutorials-and-howtos/howtos/howto-reduce-jenkins-execution-cost-without-refactoring/OneWorker-diagram.png) Key features: - **Process pool**: A fixed-size array (default 5) of concurrent processes shared across all queues and stores, providing predictable resource consumption. - **Memory monitoring**: Checks available system memory before spawning each child process, preventing OOM conditions. - **Memory leak detection**: Tracks its own memory growth and exits gracefully when a leak is detected, allowing Jenkins to restart it cleanly. - **Dynamic queue prioritization**: Intelligent strategy that prioritizes queues based on message volume and configurable modes (publish-first, sync-first, biggest-first). - **Comprehensive statistics**: Tracks cycles, process counts, error rates, and queue-level metrics for operational visibility. - **Graceful shutdown**: Handles Unix signals for clean termination and waits for child processes to complete. ## Enabling the resource-aware queue worker ### Prerequisites - `spryker/queue` >= 1.22.0 - `spryker/rabbit-mq` >= 2.21.1 - `spryker/queue-extension` >= 1.1.0 - RabbitMQ as the queue adapter. To verify this, check the following two configuration points in your project: 1. In `config/Shared/config_default.php`, the default queue adapter must be set to `RabbitMqAdapter`: ```php use Spryker\Client\RabbitMq\Model\RabbitMqAdapter; use Spryker\Shared\Queue\QueueConfig; use Spryker\Shared\Queue\QueueConstants; $config[QueueConstants::QUEUE_ADAPTER_CONFIGURATION_DEFAULT] = [ QueueConfig::CONFIG_QUEUE_ADAPTER => RabbitMqAdapter::class, QueueConfig::CONFIG_MAX_WORKER_NUMBER => 1, ]; ``` 2. In `src/Pyz/Client/Queue/QueueDependencyProvider.php`, the `createQueueAdapters()` method must return the RabbitMQ adapter: ```php protected function createQueueAdapters(Container $container): array { return [ $container->getLocator()->rabbitMq()->client()->createQueueAdapter(), ]; } ``` To verify the installed versions: ```bash composer show spryker/queue spryker/rabbit-mq spryker/queue-extension ``` ### Step 1: Register the metrics plugin Register the `RabbitMqQueueMetricsReaderPlugin` in your `QueueDependencyProvider` to supply queue metrics (message counts, batch sizes) to the worker: **src/Pyz/Zed/Queue/QueueDependencyProvider.php** ```php use Spryker\Zed\RabbitMq\Communication\Plugin\Queue\RabbitMqQueueMetricsReaderPlugin; class QueueDependencyProvider extends SprykerQueueDependencyProvider { /** * @return array<\Spryker\Zed\QueueExtension\Dependency\Plugin\QueueMetricsReaderPluginInterface> */ protected function getQueueMetricsReaderPlugins(): array { return [ new RabbitMqQueueMetricsReaderPlugin(), ]; } } ``` Also in `QueueDependencyProvider`, replace `EventRetryQueueMessageProcessorPlugin` with `EventQueueMessageProcessorPlugin` for the event retry queue. This is recommended since `spryker/event:^2.17.0`. Both plugins define how the event retry queue behaves when a message fails. `EventQueueMessageProcessorPlugin` processes failed messages directly in the retry queue, leaving the main queue unaffected. `EventRetryQueueMessageProcessorPlugin` routes failed messages back to the main queue (without the `.retry` postfix), which can slow down new message processing under high load: ```php use Spryker\Zed\Event\Communication\Plugin\Queue\EventQueueMessageProcessorPlugin; use Spryker\Shared\Event\EventConstants; // ... protected function getProcessorMessagePlugins(Container $container): array { return [ EventConstants::EVENT_QUEUE_RETRY => new EventQueueMessageProcessorPlugin(), ]; } ``` ### Step 2: Enable via configuration Add the following to `config/Shared/config_default.php`: ```php use Spryker\Shared\Queue\QueueConstants; // Enable the resource-aware worker $config[QueueConstants::RESOURCE_AWARE_QUEUE_WORKER_ENABLED] = (bool)getenv('RESOURCE_AWARE_QUEUE_WORKER_ENABLED') ?: true; ``` You can also enable it per environment using the `RESOURCE_AWARE_QUEUE_WORKER_ENABLED` environment variable. ### Step 3: Configure a single Jenkins job Replace per-store `queue:worker:start` jobs with a single job: ```php // config/Zed/cronjobs/jenkins.php $jobs[] = [ 'name' => 'queue-worker', 'command' => '$PHP_BIN vendor/bin/console queue:worker:start', 'schedule' => '* * * * *', 'enable' => true, 'stores' => ['DE'], // Use any one store/region as the entry point ]; ``` The resource-aware worker automatically processes queues for all stores and regions. ## Configuration reference All configuration constants are defined in `Spryker\Shared\Queue\QueueConstants`. They can be set in `config/Shared/config_default.php` and overridden with environment variables where supported. ### Core settings | Constant | Environment variable | Type | Default | Description | |:--------------------------------------|:--------------------------------------|:-----------------------|:--------|:----------------------------------------------------------------------------------------------------------------------------------| | `RESOURCE_AWARE_QUEUE_WORKER_ENABLED` | `RESOURCE_AWARE_QUEUE_WORKER_ENABLED` | boolean | `false` | Enables the resource-aware worker. When turned off, the default worker is used. | | `QUEUE_WORKER_WAIT_LIMIT_ENABLED` | - | boolean | `false` | When enabled, stops the queue worker once execution time exceeds `QUEUE_WORKER_MAX_THRESHOLD_SECONDS`. Use `QUEUE_WORKER_MAX_WAITING_SECONDS` (default: 30 seconds) to control how long the system waits for running subprocesses to complete after the threshold is reached. Prevents a single stuck subprocess from blocking the entire worker. | | `QUEUE_WORKER_MAX_THRESHOLD_SECONDS` | `QUEUE_WORKER_MAX_THRESHOLD_SECONDS` | integer (seconds) | `59` | Maximum runtime per worker invocation. Set to slightly under one minute so Jenkins can restart the worker on the next cron cycle. | | `QUEUE_WORKER_INTERVAL_MILLISECONDS` | `QUEUE_WORKER_INTERVAL_MILLISECONDS` | integer (milliseconds) | `1000` | Minimum delay between spawning consecutive child processes. Lower values (100-500) increase throughput at the cost of CPU. | ### Process pool settings | Constant | Environment variable | Type | Default | Description | |:--------------------------------------------------------------|:-----------------------------|:-----------------------|:--------|:----------------------------------------------------------------------------------------| | `QUEUE_WORKER_MAX_PROCESSES` | `QUEUE_WORKER_MAX_PROCESSES` | integer | `5` | Maximum number of concurrent child processes across all queues and stores. Range: 5-10. | | `QUEUE_WORKER_PROCESSES_COMPLETE_TIMEOUT` | - | integer (seconds) | `300` | Maximum time to wait for child processes to complete after the main loop ends. | | `QUEUE_WORKER_CHECK_PROCESSES_COMPLETE_INTERVAL_MILLISECONDS` | - | integer (milliseconds) | `1000` | Interval for checking whether child processes have completed during the shutdown wait. | ### Memory management settings | Constant | Environment variable | Type | Default | Description | |:-------------------------------------------|:-------------------------------------------|:---------------------|:--------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `QUEUE_WORKER_FREE_MEMORY_BUFFER` | `QUEUE_WORKER_FREE_MEMORY_BUFFER` | integer (megabytes) | `750` | Minimum free system memory required before spawning a new child process. | | `QUEUE_WORKER_MEMORY_READ_PROCESS_TIMEOUT` | `QUEUE_WORKER_MEMORY_READ_PROCESS_TIMEOUT` | integer (seconds) | `5` | Timeout for reading system memory information from `/proc/meminfo`. | | `QUEUE_WORKER_IGNORE_MEMORY_READ_FAILURE` | - | boolean | `false` | When `true`, treats unreadable memory as "enough memory" instead of throwing an exception. | | `QUEUE_WORKER_MEMORY_MAX_GROWTH_FACTOR` | - | integer (percentage) | `50` | Maximum allowed worker memory growth before the worker exits to prevent memory leaks. For example, `50` means the worker exits if its own memory consumption grows by more than 50% from the initial baseline. | ### Queue prioritization settings | Constant | Type | Default | Description | |:------------------------------------------------------|:------------------|:--------|:------------------------------------------------------------------------------------------------------------------------------------------| | `QUEUE_PROCESSING_WORKER_DYNAMIC_MODE` | integer (bitmask) | `0` | Controls queue prioritization modes. Modes can be combined using bitwise OR. See [Queue processing strategy](#queue-processing-strategy). | | `QUEUE_PROCESSING_BIG_QUEUE_THRESHOLD_BATCHES_AMOUNT` | integer | `100` | Number of batches that defines the threshold for a queue to be considered "big" for prioritization purposes. | | `QUEUE_PROCESSING_LIMIT_OF_PROCESSES_PER_QUEUE` | integer | `10` | Maximum number of concurrent processes per individual queue. | ### Example configuration **config/Shared/config_default.php** ```php use Spryker\Shared\Queue\QueueConstants; // Enable the resource-aware worker $config[QueueConstants::RESOURCE_AWARE_QUEUE_WORKER_ENABLED] = (bool)getenv('RESOURCE_AWARE_QUEUE_WORKER_ENABLED') ?: true; // Stop worker when execution time is exceeded; wait up to QUEUE_WORKER_MAX_WAITING_SECONDS for subprocesses $config[QueueConstants::QUEUE_WORKER_WAIT_LIMIT_ENABLED] = true; // Process pool $config[QueueConstants::QUEUE_WORKER_MAX_PROCESSES] = 10; // Memory management $config[QueueConstants::QUEUE_WORKER_FREE_MEMORY_BUFFER] = (int)getenv('QUEUE_WORKER_FREE_MEMORY_BUFFER') ?: 750; $config[QueueConstants::QUEUE_WORKER_MEMORY_READ_PROCESS_TIMEOUT] = (int)getenv('QUEUE_WORKER_MEMORY_READ_PROCESS_TIMEOUT') ?: 5; // Timing $config[QueueConstants::QUEUE_WORKER_MAX_THRESHOLD_SECONDS] = 59; $config[QueueConstants::QUEUE_WORKER_INTERVAL_MILLISECONDS] = 1000; // Process completion $config[QueueConstants::QUEUE_WORKER_PROCESSES_COMPLETE_TIMEOUT] = 600; ``` ## How it works ### Main execution loop When `queue:worker:start` is executed with the resource-aware worker enabled, the following flow runs for the configured threshold duration (default 59 seconds): ![Resource-aware worker flow](https://spryker.s3.eu-central-1.amazonaws.com/docs/scos/dev/tutorials-and-howtos/howtos/howto-reduce-jenkins-execution-cost-without-refactoring/NewWorker+Flow.png) 1. **Cycle start**: The worker increments cycle counter. 2. **Process scan**: Iterates through the process pool to detect completed processes, free slots, and log errors from failed processes. 3. **Memory check**: Reads free system memory from `/proc/meminfo`. If free memory is below the configured buffer, the cycle is skipped. 4. **Slot check**: If no free process slot is available, the cycle is skipped. 5. **Cooldown check**: If the minimum delay between spawns has not elapsed, the cycle is skipped. 6. **Process spawn**: The queue processing strategy selects the next queue. A child process (`queue:task:start `) is spawned and placed into the free slot. 7. **Memory leak check**: The worker compares its own current memory usage against the initial baseline. If growth exceeds the configured threshold, the worker exits gracefully. 8. **Shutdown**: After the main loop, the worker waits for all remaining child processes to complete (up to the configured timeout), then logs statistics. ### Process pool The process pool is a fixed-size array (`SplFixedArray`) where each slot holds a reference to a running child process. This design provides: - **Predictable concurrency**: At most N processes run simultaneously, regardless of the number of stores or queues. - **Predictable memory consumption**: Since the pool size is fixed, you can estimate maximum memory usage as `pool_size * max_memory_per_task + worker_overhead`. - **Efficient slot reuse**: Completed processes free their slots immediately for new work. ### System resource monitoring The `SystemResourcesManager` provides two key capabilities: **Free memory detection** reads `/proc/meminfo` (with a fallback to `cat /proc/meminfo` via subprocess) and returns the maximum of `MemFree` and `MemAvailable` in megabytes. Before every process spawn, the worker checks whether free memory exceeds the configured buffer. **Worker memory growth tracking** captures the initial `memory_get_peak_usage()` on first invocation and calculates the percentage growth on each subsequent check. If growth exceeds the configured factor (default 50%), the worker exits gracefully. Since Jenkins restarts it on the next cron cycle, this effectively prevents indefinite memory leaks. ### Queue processing strategy The `DynamicOrderQueueProcessingStrategy` combines multiple prioritization modes to determine which queue to process next. It scans all queues for all stores, calculates a priority score for each, and returns them in priority order. **Available modes** (combinable via bitwise OR): | Mode | Value | Behavior | |:---------------------|:------|:-----------------------------------------------------------------| | Default order | `0` | Processes queues in definition order | | Prefer publish | `2` | Prioritizes publish queues | | Prefer sync | `4` | Prioritizes sync queues | | Prefer big | `8` | Prioritizes queues with more than the configured batch threshold | | Prefer small | `16` | Prioritizes queues below the batch threshold | | Prefer default store | `32` | Prioritizes the default store's queues | | Prefer fast | `64` | Prioritizes fast-processing queues | | Prefer slow | `128` | Prioritizes slow-processing queues | | Only preferred | `256` | Restricts processing to only preferred queues | **Queues with fewer messages than one batch size receive the lowest priority** to avoid wasting process slots on near-empty queues. **Per-queue process limits** prevent any single queue from monopolizing the entire pool. The `QUEUE_PROCESSING_LIMIT_OF_PROCESSES_PER_QUEUE` constant caps how many concurrent processes target the same queue. The strategy also supports **runtime dynamic settings updates** through `DynamicSettingsUpdaterPluginInterface` plugins, allowing modes and thresholds to be adjusted during execution based on external signals. ## Worker statistics and logs The resource-aware worker collects comprehensive statistics during each invocation and prints a summary at the end. ![Worker statistics log](https://spryker.s3.eu-central-1.amazonaws.com/docs/scos/dev/tutorials-and-howtos/howtos/howto-reduce-jenkins-execution-cost-without-refactoring/stats-log.png) **Cycle metrics**: - Total cycles executed - Skip cycles (throttled due to resource constraints) - Empty cycles (no messages in any queue) - No-slot cycles (all process pool slots are busy) - No-memory cycles (insufficient free system memory) - Cooldown cycles (minimum spawn interval not yet elapsed) **Process metrics**: - Total processes spawned - Failed processes (non-zero exit code) - Maximum concurrent processes observed **Queue metrics**: - Per-queue task counts - Per-store or per-region task counts - Error distribution by exit code **Success rate** is calculated as `(spawned - failed) / spawned * 100%`. ![Worker statistics summary](https://spryker.s3.eu-central-1.amazonaws.com/docs/scos/dev/tutorials-and-howtos/howtos/howto-reduce-jenkins-execution-cost-without-refactoring/stats-summary.png) ### Error logging Output from failed child processes is captured in the main worker's standard output, including the command line, standard output, and error output. This simplifies troubleshooting by providing all relevant information in one log stream. ![Error logging](https://spryker.s3.eu-central-1.amazonaws.com/docs/scos/dev/tutorials-and-howtos/howtos/howto-reduce-jenkins-execution-cost-without-refactoring/stats-error-log.png) Use the `-vvv` flag when running `queue:worker:start` to see detailed debug-level output, including per-cycle memory and timing information. ## Tuning recommendations ### Process pool size Start with the default of 5 and adjust based on observation: - **Increase** if statistics show frequent no-slot cycles and your system has available memory and CPU. - **Decrease** if you observe memory pressure, OOM conditions, or high CPU contention. - A good starting point is 1-2 processes per available CPU core. ### Free memory buffer The default 750 MB works for most environments. Adjust based on your host's total RAM and per-task memory consumption: - **Small hosts (4 GB RAM)**: Use 512-750 MB. - **Large hosts (8+ GB RAM)**: You can increase the pool size while keeping the buffer at 750 MB. - The buffer must accommodate: the memory needed by the next spawned process, plus headroom for memory spikes in already running processes. ### Spawn interval The default 1000 ms (1 second) is conservative. For latency-sensitive environments: - Lower to 100-500 ms for faster throughput. - Higher values reduce CPU overhead from the worker's main loop. ### Monitoring Use the worker statistics to identify bottlenecks: - **High no-memory cycles**: Reduce pool size or increase instance memory. - **High no-slot cycles**: Increase pool size if resources allow. - **High empty cycles**: Queues are mostly idle; the worker is working as expected. - **Failed processes**: Investigate the error output for root causes (memory limits, database connection issues). {% info_block warningBox "Performance monitoring" %} Instance performance also depends on other jobs running on Jenkins, such as data import and custom plugins. These can affect the overall performance and runtime of your Publish and Synchronize processes. Always analyze them with [Application Performance Monitoring](/docs/dg/dev/integrate-and-configure/configure-services.html#new-relic) or [local profiling](/docs/scos/dev/tutorials-and-howtos/howtos/howto-setup-xdebug-profiling.html). {% endinfo_block %} ## Backporting to older Spryker versions If you are on a Spryker version prior to `202512.0` and cannot upgrade, you can implement the resource-aware worker concept at the project level. This section provides a high-level guide for the approach. {% info_block warningBox "Unsupported customization" %} The following is a project-level customization and is not officially supported by Spryker. The built-in `ResourceAwareQueueWorker` in `202512.0` supersedes this approach. Upgrade when possible. {% endinfo_block %} ### Required components 1. **Custom Worker class**: Implement `WorkerInterface` with a fixed-size process pool (`SplFixedArray`), a main loop bounded by a time threshold, and free memory checks before each process spawn. The worker should iterate through its pool to detect completed processes and reuse freed slots. 2. **System resources manager**: Create a class that reads `/proc/meminfo` to determine free system memory and tracks the worker's own memory growth using `memory_get_peak_usage(true)`. 3. **Queue scanner**: Build a component that queries RabbitMQ for message counts per queue per store. Implement a cooldown period (for example, 5 seconds) to avoid repeatedly scanning empty queues. 4. **Queue processing strategy**: Implement a strategy interface with a `getNextQueue()` method. A simple ordered strategy iterates through queues; a more advanced strategy can prioritize based on message volume. 5. **Process manager extension**: Extend the Spryker `ProcessManager` to prefix queue names with store codes, enabling a single worker to distinguish processes across stores. 6. **RabbitMQ metrics exposure**: Expose the RabbitMQ `queue_declare` passive method to the business layer, allowing the scanner to read queue statistics without modifying queue state. ### Integration Wire the components through a custom `QueueBusinessFactory`: - Override `createWorker()` to return your custom worker based on a config flag. - Register the custom factory in the project-level `QueueDependencyProvider`. - Configure a single Jenkins job instead of per-store jobs. ### Configuration Define project-level constants for pool size, memory buffer, memory read timeout, and memory growth threshold, mirroring the constants described in [Configuration reference](#configuration-reference). ## Stable workers For Spryker PaaS environments, **Stable Workers** provide an alternative approach to background job optimization. Both the resource-aware queue worker and Stable Workers address the same core problems (memory management, process isolation, and stability), but they differ in scope: - **Resource-aware queue worker**: Runs within Jenkins or any scheduler. Manages its own process pool and memory monitoring. Suitable for self-hosted, isolated, or non-Jenkins setups. - **Stable Workers**: A PaaS-managed service using Amazon ECS with configurable capacity providers and Auto Scaling Groups. Provides infrastructure-level isolation and scaling. Both solutions can coexist. Stable Workers handle P&S workloads while the resource-aware queue worker can manage other queue-based jobs on Jenkins. For more details, see [Stable Workers](/docs/dg/dev/backend-development/cronjobs/stable-workers.html).

Keeping dependencies updated for performance

Wed, 13 May 2026 07:15:50 +0000

Keeping your project's Spryker module dependencies up to date is critical for maintaining optimal performance, security, and reducing long-term upgrade efforts. ## Why keep dependencies updated Updating dependencies regularly provides several practical benefits: 1. **Risk of security vulnerabilities**: Most recent versions contain necessary fixes to all known vulnerabilities. 2. **Performance and resource consumption optimizations**: Spryker continuously releases performance improvements based on real-life experiences and scenarios. 3. **Decreasing upgrade efforts**: Distributing upgrades across many smaller steps is much easier than doing one massive upgrade later. ## Key resources The following resources provide information about performance-related module releases: - [Security release notes 202512.0](https://docs.spryker.com/docs/about/all/releases/security-releases/security-release-notes-202512.0.html) - [Release notes 202410.0](https://docs.spryker.com/docs/scos/user/intro-to-spryker/releases/release-notes/release-notes-202410.0/release-notes-202410.0.html) - [Release notes 202507.0](https://docs.spryker.com/docs/scos/user/intro-to-spryker/releases/release-notes/release-notes-202507.0/release-notes-202507.0.html) - [General performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/general-performance-guidelines.html) - contains the list of recent module versions with known performance optimizations - [Cart page performance configuration](https://docs.spryker.com/docs/pbc/all/cart-and-checkout/latest/cart-page-performance-configuration.html) ## Critical module updates The following sections list important module updates that include performance improvements. It's recommended that each Spryker project evaluates and applies these updates. ### Product search performance **spryker/product-page-search** - Recent versions (for example, `3.38.0` - `3.40.0`) include improvements such as: - Caching logic adjustments for product images - Potential bulk operation support to make search document writes more efficient - Avoiding duplicate locale events ### Session management **spryker/session** - at least `^4.17.0` - Provides configurable session locking mechanism - See [Redis session lock](/docs/dg/dev/troubleshooting/troubleshooting-performance-issues/redis-session-lock.html) for configuration details **spryker/session-redis** - at least `^1.11.2` - Includes configurable session locker - See [Redis session lock](/docs/dg/dev/troubleshooting/troubleshooting-performance-issues/redis-session-lock.html) for setup instructions ### Merchant Portal and Back Office performance with ACL rules - [spryker/acl:^3.26.0](https://github.com/spryker/acl/releases/tag/3.26.0) - [spryker/acl-entity:^1.16.0](https://github.com/spryker/acl-entity/releases/tag/1.16.0) - [spryker/gui:^4.11.0](https://github.com/spryker/gui/releases/tag/4.11.0) - [spryker/merchant-profile:^1.9.0](https://github.com/spryker/merchant-profile/releases/tag/1.9.0) - [spryker/merchant-user:^1.9.0](https://github.com/spryker/merchant-user/releases/tag/1.9.0) - [spryker/multi-factor-auth-merchant-portal:^2.1.0](https://github.com/spryker/multi-factor-auth-merchant-portal/releases/tag/2.1.0) - [spryker/product-attribute:^1.18.0](https://github.com/spryker/product-attribute/releases/tag/1.18.0) - [spryker/zed-navigation:^1.15.0](https://github.com/spryker/zed-navigation/releases/tag/1.15.0) ### Back Office performance on category list page - [spryker/product-category:"^4.32.0"](https://github.com/spryker/zed-navigation/releases/tag/4.32.0) ### Order placement performance - [spryker/calculation:^4.14.0](https://github.com/spryker/calculation/releases/tag/4.14.0) - [spryker/discount-calculation-connector:^5.4.0](https://github.com/spryker/discount-calculation-connector/releases/tag/5.4.0) - [spryker/merchant:^3.15.0](https://github.com/spryker/merchant/releases/tag/3.15.0) - [spryker/sales:^11.60.0](https://github.com/spryker/sales/releases/tag/11.60.0) - [spryker/product:^6.49.0](https://github.com/spryker/product/releases/tag/6.49.0) - [spryker/discount:^9.43.0](https://github.com/spryker/discount/releases/tag/9.43.0) - [spryker/product-cart-connector:^4.13.0](https://github.com/spryker/product-cart-connector/releases/tag/4.13.0) - [spryker/company-role:^1.9.1](https://github.com/spryker/company-role/releases/tag/1.9.1) - [spryker/propel:^3.43.0](https://github.com/spryker/propel/releases/tag/3.43.0) - [spryker/sales:^11.63.0](https://github.com/spryker/sales/releases/tag/11.63.0) - [spryker/sales-product-connector:^1.11.1](https://github.com/spryker/sales-product-connector/releases/tag/1.11.1) - [spryker/shipment:^8.24.0](https://github.com/spryker/shipment/releases/tag/8.24.0) ### OMS availability check and order item reservation - [spryker/availability:^9.27.0](https://github.com/spryker/availability/releases/tag/9.27.0) - [spryker/stock:^8.10.1](https://github.com/spryker/stock/releases/tag/8.10.1) - [spryker/oms:^11.45.1](https://github.com/spryker/oms/releases/tag/11.45.1) - [spryker/propel:^3.43.0](https://github.com/spryker/propel/releases/tag/3.43.0) - [spryker/sales:^11.63.0](https://github.com/spryker/sales/releases/tag/11.63.0) ### Publish and synchronization (merchant-related) - [spryker/merchant-product-offer-storage:^2.6.0](https://github.com/spryker/merchant-product-offer-storage/releases/tag/2.6.0) - [spryker/product-offer-storage:^1.8.0](https://github.com/spryker/product-offer-storage/releases/tag/1.8.0) - [spryker/propel:^3.45.0](https://github.com/spryker/propel/releases/tag/3.45.0) ### Publish and synchronization (product-related) - [spryker/price-product:^4.48.0](https://github.com/spryker/price-product/releases/tag/4.48.0) - [spryker/product-page-search:^3.40.0](https://github.com/spryker/product-page-search/releases/tag/3.40.0) - [spryker/product-search:^5.24.1](https://github.com/spryker/product-search/releases/tag/5.24.1) - [spryker/product-storage:^1.47.0](https://github.com/spryker/product-storage/releases/tag/1.47.0) - [spryker/product-offer-storage:^1.10.0](https://github.com/spryker/product-offer-storage/releases/tag/1.10.0) - [spryker/price-product-offer:^1.7.1](https://github.com/spryker/price-product-offer/releases/tag/1.7.1) - [spryker/price-product-offer-storage:^1.5.1](https://github.com/spryker/price-product-offer-storage/releases/tag/1.5.1) - [spryker/price-product-storage:^4.13.0](https://github.com/spryker/price-product-storage/releases/tag/4.13.0) - [spryker/product-image:^3.20.1](https://github.com/spryker/product-image/releases/tag/3.20.1) - [spryker/product-category-storage:^2.11.0](https://github.com/spryker/product-category-storage/releases/tag/2.11.0) - [spryker/product-category-search:^1.2.1](https://github.com/spryker/product-category-search/releases/tag/1.2.1) - [spryker/propel:^3.47.0](https://github.com/spryker/propel/releases/tag/3.47.0) - Note: If you still use destructive deployments, update the `config/install/destructive.yml` file. You can copy it from any demo shop. - [spryker/event-behavior:^1.32.0](https://github.com/spryker/event-behavior/releases/tag/1.32.0) - [spryker/synchronization-behavior:^1.13.0](https://github.com/spryker/synchronization-behavior/releases/tag/1.13.0) ### Publish and synchronization (Category tree build logic) - [spryker/category:"^5.23.0"](https://github.com/spryker/category/releases/tag/5.23.0) - [spryker/category-storage:"^2.12.0"](https://github.com/spryker/category-storage/releases/tag/2.12.0) - [spryker/propel-orm:"^1.22.0"](https://github.com/spryker/propel-orm/releases/tag/1.22.0) - [spryker/util-sanitize:"^2.3.1"](https://github.com/spryker/util-sanitize/releases/tag/2.3.1) ### Publish and synchronization (queue and event performance) To update all required modules at once: ```bash composer update spryker/rabbit-mq:"^2.25.0" spryker/availability-storage:"^2.11.0" spryker/event:"^2.17.0" spryker/glossary-storage:"^1.14.0" spryker/merchant-product:"^1.12.0" spryker/merchant-product-offer:"^1.12.0" spryker/merchant-product-offer-search:"^1.9.0" spryker/merchant-product-search:"^1.6.0" spryker/merchant-product-storage:"^1.7.0" spryker/price-product:"^4.51.0" spryker/price-product-merchant-relationship-storage:"^1.21.0" spryker/price-product-offer-storage:"^1.8.0" spryker/price-product-storage:"^4.16.0" spryker/product:"^6.54.0" spryker/product-category-search:"^1.3.0" spryker/product-category-storage:"^2.13.0" spryker/product-group-storage:"^1.9.0" spryker/product-image:"^3.21.0" spryker/product-image-storage:"^1.21.0" spryker/product-list:"^1.10.0" spryker/product-list-search:"^2.11.0" spryker/product-list-storage:"^1.21.0" spryker/product-offer:"^1.17.0" spryker/product-offer-availability-storage:"^1.6.0" spryker/product-offer-stock:"^1.7.0" spryker/product-page-search:"^3.47.0" spryker/product-page-search-extension:"^1.7.0" spryker/propel:"^3.50.0" spryker/queue:"^1.26.0" spryker/symfony-messenger:"^1.6.0" spryker/tax-product-storage:"^1.8.0" spryker/url-storage:"^1.23.0" spryker/synchronization-behavior:"^1.14.0" ``` - [spryker/rabbit-mq:^2.25.0](https://github.com/spryker/rabbit-mq/releases/tag/2.25.0) - [spryker/availability-storage:^2.11.0](https://github.com/spryker/availability-storage/releases/tag/2.11.0) - [spryker/event:^2.17.0](https://github.com/spryker/event/releases/tag/2.17.0) - [spryker/event-behavior:^1.35.0](https://github.com/spryker/event-behavior/releases/tag/1.35.0) - [spryker/glossary-storage:^1.14.0](https://github.com/spryker/glossary-storage/releases/tag/1.14.0) - [spryker/merchant-product:^1.12.0](https://github.com/spryker/merchant-product/releases/tag/1.12.0) - [spryker/merchant-product-offer:^1.12.0](https://github.com/spryker/merchant-product-offer/releases/tag/1.12.0) - [spryker/merchant-product-offer-search:^1.9.0](https://github.com/spryker/merchant-product-offer-search/releases/tag/1.9.0) - [spryker/merchant-product-search:^1.6.0](https://github.com/spryker/merchant-product-search/releases/tag/1.6.0) - [spryker/merchant-product-storage:^1.7.0](https://github.com/spryker/merchant-product-storage/releases/tag/1.7.0) - [spryker/price-product:^4.51.0](https://github.com/spryker/price-product/releases/tag/4.51.0) - [spryker/price-product-merchant-relationship-storage:^1.21.0](https://github.com/spryker/price-product-merchant-relationship-storage/releases/tag/1.21.0) - [spryker/price-product-offer-storage:^1.8.0](https://github.com/spryker/price-product-offer-storage/releases/tag/1.8.0) - [spryker/price-product-storage:^4.16.0](https://github.com/spryker/price-product-storage/releases/tag/4.16.0) - [spryker/product:^6.54.0](https://github.com/spryker/product/releases/tag/6.54.0) - [spryker/product-category-search:^1.3.0](https://github.com/spryker/product-category-search/releases/tag/1.3.0) - [spryker/product-category-storage:^2.13.0](https://github.com/spryker/product-category-storage/releases/tag/2.13.0) - [spryker/product-group-storage:^1.9.0](https://github.com/spryker/product-group-storage/releases/tag/1.9.0) - [spryker/product-image:^3.21.0](https://github.com/spryker/product-image/releases/tag/3.21.0) - [spryker/product-image-storage:^1.21.0](https://github.com/spryker/product-image-storage/releases/tag/1.21.0) - [spryker/product-list:^1.10.0](https://github.com/spryker/product-list/releases/tag/1.10.0) - [spryker/product-list-search:^2.11.0](https://github.com/spryker/product-list-search/releases/tag/2.11.0) - [spryker/product-list-storage:^1.21.0](https://github.com/spryker/product-list-storage/releases/tag/1.21.0) - [spryker/product-offer:^1.17.0](https://github.com/spryker/product-offer/releases/tag/1.17.0) - [spryker/product-offer-availability-storage:^1.6.0](https://github.com/spryker/product-offer-availability-storage/releases/tag/1.6.0) - [spryker/product-offer-stock:^1.7.0](https://github.com/spryker/product-offer-stock/releases/tag/1.7.0) - [spryker/product-page-search:^3.47.0](https://github.com/spryker/product-page-search/releases/tag/3.47.0) - [spryker/product-page-search-extension:^1.7.0](https://github.com/spryker/product-page-search-extension/releases/tag/1.7.0) - [spryker/propel:^3.50.0](https://github.com/spryker/propel/releases/tag/3.50.0) - [spryker/queue:^1.26.0](https://github.com/spryker/queue/releases/tag/1.26.0) - [spryker/symfony-messenger:^1.6.0](https://github.com/spryker/symfony-messenger/releases/tag/1.6.0) - [spryker/tax-product-storage:^1.8.0](https://github.com/spryker/tax-product-storage/releases/tag/1.8.0) - [spryker/url-storage:^1.23.0](https://github.com/spryker/url-storage/releases/tag/1.23.0) - [spryker/synchronization-behavior:^1.14.0](https://github.com/spryker/synchronization-behavior/releases/tag/1.14.0) ### Data import (memory usage) - [spryker/acl-entity:"^1.17.0"](https://github.com/spryker/acl-entity/releases/tag/1.17.0) - [spryker/data-import:"^1.33.0"](https://github.com/spryker/data-import/releases/tag/1.33.0) - [spryker/merchant-relationship-product-list-data-import:"^0.1.3"](https://github.com/spryker/merchant-relationship-product-list-data-import/releases/tag/0.1.3) - [spryker/price-product-merchant-relationship-data-import:"^0.2.5"](https://github.com/spryker/price-product-merchant-relationship-data-import/releases/tag/0.2.5) ### Cart page and checkout for large carts (100+ items) For comprehensive guidance on optimizing cart performance, see [Cart page performance configuration](https://docs.spryker.com/docs/pbc/all/cart-and-checkout/latest/cart-page-performance-configuration.html). - [spryker-shop/checkout-page:^3.41.0](https://github.com/spryker-shop/checkout-page/releases/tag/3.41.0) - [spryker-shop/session-customer-validation-page:^1.4.0](https://github.com/spryker-shop/session-customer-validation-page/releases/tag/1.4.0) ## Update strategy To effectively manage dependency updates: 1. **Monitor release notes**: Regularly check Spryker release notes for performance-related updates. 2. **Test in staging**: Always test module updates in a staging environment before production deployment. 3. **Prioritize performance modules**: Focus on modules that directly impact your application's performance bottlenecks. 4. **Use semantic versioning**: Understand the impact of major, minor, and patch updates. 5. **Batch related updates**: Group related module updates together for testing efficiency. ## Compatibility considerations When updating modules: - Check module compatibility with your current Spryker version - Review breaking changes in major version updates - Test all affected functionality after updates - Monitor application performance metrics before and after updates - Consider using Spryker's [Composer Dependency Manager](https://docs.spryker.com/docs/scos/dev/setup/managing-scos-dependencies-with-composer.html)

General performance guidelines

Wed, 13 May 2026 07:15:50 +0000

Spryker is a fast application by design. These guidelines explain how to optimize the server-side execution time. ## Hosting recommendations - *CPU*: Spryker's execution time depends on the CPU of the server. In general, more CPU capacity supports faster response times and allows a higher load. - *Memory (Databases)*: Databases (key-value storage (Redis or Valkey), Elasticsearch, and PostgreSQL) mainly consume RAM. When there is not enough RAM, you can face performance issues. The best amount of RAM depends on the amount of data that you have and needs to be measured from time to time. - *Memory (PHP)*: The amount of memory does not impact on the execution time of PHP, but to squeeze everything out of your server, you need to define the `pm.max_children` configuration value of PHP-FPM. The max amount of parallel processes must not be higher than the available memory divided by the maximum consumption per process. - *Latency*: You can see the highest speed of Spryker when key-value storage (Redis or Valkey) is installed on the same machine as the application, which helps to avoid latency. Key-value storage (Redis or Valkey) has a blazing fast response time of 0.1 ms, but in cloud environments, you can often get additional 1-3ms of latency per `get()`. A caching mechanism that uses Spryker is described in the following sections of this document. ## Disable Xdebug Xdebug slows down the application and is not necessary for a non-development environment. ## Use the newest version of PHP For performance reasons, always use the newest stable version of PHP, as every new version ships with several improvements. ## Opcache activation Make sure that Opcache is activated and properly configured: | CONFIGURATION | PURPOSE | PRODUCTION | DEVELOPMENT | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------- | | `opcache.enable` | Activates Opcache for web requests. Most developers disable this on development environments to avoid outdated code in caches. However, you can also activate it and check for changed files via `validate_timestamps` and `revalidate_freq` configurations. | 1 | 0 | | `opcache.enable_cli` | Activates Opcache for console commands. | 1 | 0 | | `opcache.max_accelerated_files` | Spryker and all the used open-source libraries contain a lot of PHP classes, so this value should be high (max is 100k). | ? | 8192 | | `opcache.memory_consumption` | To avoid an automatic reset of the Opcache, these values must be high enough. You can look into the PHP info (for exaample, in Zed, browse to `/maintenance/php-info`) to see the current usage. You can count the number of classes in your codebase to get an idea of a good value. | ? | | | `opcache.validate_timestamps` | Boolean values that activate the check for the updated code. This check is time-consuming and must be disabled in production environments. However, you need to flush the cache during deployments—for example, by restarting PHP. | 0 | 1 | | `opcache.revalidate_freq` | Configures the frequency of checks if enabled by the `validate_timestamps` configuration. *0* means *on every request*, which is recommended for development environments if you want to program with activated Opcache. 0 0 | 0 | 0 | ```php zend_extension=opcache.so opcache.enable=1 opcache.enable_cli=1 opcache.max_accelerated_files=8192 opcache.memory_consumption=256 ; Check if file updated on each request - for development opcache.validate_timestamps=0 opcache.revalidate_freq=0 ``` ## Optimized Composer autoloader A typical request in Yves requires up to 1000 PHP classes. Much time is needed to translate the class name to a file name. Composer is shipped with an autoloader that checks several paths to find a specific class. Composer also offers an optimized autoloader, which creates a map with all classes and their locations in the `vendor/composer/` directory. This map speeds up the autoloading by ~50%, and we recommend running it during every deployment: ```php php composer dumpautoload -o ``` You can also optimize the autoloader by enabling some options in `composer.json`: ```json "optimize-autoloader": true, "classmap-authoritative": true ``` For more details about composer autoloader optimization, see the [autoloader documentation](https://getcomposer.org/doc/articles/autoloader-optimization.md). ## Deactivate all debug functions and the Symfony toolbar The `config_default-production.php` file can disable all debuggers and the Symfony toolbar: ```php $config[\Spryker\Shared\Application\ApplicationConstants::ENABLE_APPLICATION_DEBUG] = false; $config[\SprykerShop\Shared\ShopApplication\ShopApplicationConstants::ENABLE_APPLICATION_DEBUG] = false; $config[\Spryker\Shared\Application\ApplicationConstants::ENABLE_WEB_PROFILER] = false; $config[\Spryker\Shared\Propel\PropelConstants::PROPEL_DEBUG] = false; $config[\Spryker\Shared\WebProfiler\WebProfilerConstants::ENABLE_WEB_PROFILER] = false; $config[\Spryker\Shared\Config\ConfigConstants::ENABLE_WEB_PROFILER] = false; ``` ## Disable automatic queue creation During the synchronization part of Publish & Sync, each time the `queue:task:start QUEUE-NAME` command is started, the RabbitMQ client tries to create all the configured queues and exchanges: `\Spryker\Client\RabbitMq\Model\Connection\Connection::__construct`. It takes up to 25% of CPU time per run. The effect becomes more significant for multi-store setups with each additional store. For backward compatibility reasons, `RabbitMqEnv::RABBITMQ_ENABLE_RUNTIME_SETTING_UP` is enabled by default in the module configuration class: `\Spryker\Client\RabbitMq\RabbitMqConfig::isRuntimeSettingUpEnabled`. For production environments, we recommend disabling it by setting it to `false` in `config_default.php` or another config file. Side effects: - The application doesn't try to recreate queues and exchanges "on the fly" while interacting with RabbitMQ. If a queue is deleted, and the application attempts to access it, there will be an exception. - The only way to create queues and exchanges to configure RabbitMQ is to run the `console queue:setup` CLI command defined in `\Spryker\Zed\RabbitMq\Communication\Console\QueueSetupConsole`. Make sure to *adjust your deploy scripts* accordingly. ## Disable INFO event logs Publish & Sync process can work slower and generate hundreds of megabytes of `INFO`-level logs, which is good for troubleshooting and debugging, but not appropriate for production environments. By default `INFO` logs are enabled and generate about 60-100 MB per `queue:task:run ...` execution with 80-90% of CPU time only to write logs. There are a few options to avoid this in production environments: - Disable event logs using one of the following: - Set `EventConstants::LOG_FILE_PATH` to `null`. - Set `EventConstants::LOGGER_ACTIVE` to `false` in the appropriate config files, like `config_default.php`. - Change the events log level in any config file, by setting `EventConstants::EVENT_LOGGER_LEVEL` to, for example, `\Monolog\Logger::WARNING` in newer (> 2.9.2) versions of `spryker/event`. - For versions up to `spryker/event:2.9.2`: Override `LoggerConfig::createStreamHandler` to change the [event logger level](https://github.com/spryker/event/blob/master/src/Spryker/Zed/Event/Business/Logger/LoggerConfig.php). ## Enable queue worker wait limit To prevent a stuck subprocess from blocking the queue worker indefinitely, enable the wait limit in `config/Shared/config_default.php`: ```php $config[QueueConstants::QUEUE_WORKER_WAIT_LIMIT_ENABLED] = true; ``` When enabled: - The queue worker stops when execution time exceeds `QueueConstants::QUEUE_WORKER_MAX_THRESHOLD_SECONDS` (default: 60 seconds). - `QueueConstants::QUEUE_WORKER_MAX_WAITING_SECONDS` (default: 30 seconds) controls how long the system waits for running subprocesses to complete before forcing a shutdown. This prevents situations where a single stuck subprocess causes the entire queue worker to hang indefinitely. ## Use EventQueueMessageProcessorPlugin for event queues Available since `spryker/event:^2.17.0`, `EventQueueMessageProcessorPlugin` is the recommended plugin for the event retry queue in `src/Pyz/Zed/Queue/QueueDependencyProvider.php`. Both plugins define how the event retry queue behaves when a message fails. The difference is what happens to that failed message: - `EventQueueMessageProcessorPlugin` — processes messages directly in the retry queue. Failed messages remain in the retry queue and are handled independently, so the main event queue is not affected. - `EventRetryQueueMessageProcessorPlugin` — routes failed messages from the retry queue back to the main queue (the queue without the `.retry` postfix). Under high load, these messages re-entering the main queue can slow down the processing of new messages. For projects running `spryker/event:^2.17.0` or later, use `EventQueueMessageProcessorPlugin` for the retry queue to keep the main queue free from re-queued failures. ## Twig performance optimizations For comprehensive Twig-specific performance optimizations, including compiler activation, path cache configuration, template warmup, SVG icons handling, caching strategies, and other best practices, see [Twig performance best practices](/docs/dg/dev/guidelines/performance-guidelines/twig-performance-best-practices.html). ## Activate Zed navigation cache The navigation of Zed is defined in XML files that need to be parsed and merged. As it does not happen quite often, it's recommended to keep the cache activated at all times (even during development) and to run `vendor/bin/console navigation:build-cache` only when something has changed. Zed navigation cache is activated by default: ```php $config[\Spryker\Shared\ZedNavigation\ZedNavigationConstants::ZED_NAVIGATION_CACHE_ENABLED] = true; ``` ## Enable Zed and Merchant Portal router caching Routing for ZED and the Merchant Portal can either be cached or generated on each request. For optimal performance, we recommend building routing cache once during deployment. To configure this, update the configuration in `src/Pyz/Zed/Router/RouterConfig.php`: ```php public function isRoutingCacheEnabled(): bool { return true; } ``` ## Redis Mget cache Yves performs a high number of `get()` calls to Redis. If Redis is installed on the same machine, the expected time per `get()` is below 0.1 ms. However, if you run Spryker in a cloud environment, there is latency for each `get()` call to Redis. It can sum up to a few hundred milliseconds per request. To avoid this performance bottleneck, Spryker remembers all used `get()` calls per URL and performs a single `mget()` to retrieve all needed data in one call. This behavior is enabled by default. If you see a high number of `get()` calls in your monitoring, make sure that `StorageCacheEventDispatcherPlugin` is registered in `Pyz\Yves\EventDispatcher\EventDispatcherDependencyProvider`. This plugin is responsible for the persistence of the cache data in Redis. For more information about the Redis Mget cache, see [Use Redis or Valkey as a KV Storage](/docs/dg/dev/backend-development/client/use-and-configure-redis-or-valkey-as-a-key-value-store.html#use-and-configure-key-value-storage-cache). ## ClassResolver optimizations Spryker often uses the so-called class resolvers. Those resolvers are responsible for finding class names for certain overridable class names. For example, resolvers are `ModuleFactory`, `ModuleConfig`, `ModuleClient`. The process of resolving the right class name is done by building class name candidates. These candidates list contains a Store class name, for example, `\Pyz\Application\ModuleSTORE\ModuleFactory`, a project class name, for example, `\Pyz\Application\Module\ModuleFactory`, and a core class name, for example,`\Spryker\Application\Module\ModuleFactory`. Depending on the found class, the resolver returns the class instance, which is then used. To speed up the overall page load, there are two features: resolvable class names cache and resolvable Instance cache. ### Activate resolvable class names cache The resolvable class names cache is disabled by default. To activate it, by add the following configuration to your `config_*` files: ```php $config[KernelConstants::RESOLVABLE_CLASS_NAMES_CACHE_ENABLED] = true; ``` Additionally, you need to build the cache file during your deployment. Add `\Spryker\Zed\Kernel\Communication\Console\ResolvableClassCacheConsole` to your `ConsoleDependencyProvider` if you don't have it, and run the following: ```bash vendor/bin/console cache:class-resolver:build ``` This command builds a cache file, which is used by the `ClassResolver`. ### Activate resolved instance cache On top of the resolvable class names cache, you can turn on an instance cache for the resolved classes by adding the following configuration to your `config_*` files: ```php $config[KernelConstants::RESOLVED_INSTANCE_CACHE_ENABLED] = true; ``` This allows reusing an already resolved class instance during a request. {% info_block warningBox "Warning" %} Enabling this option can cause undesired behavior when the resolved class is stateful. {% endinfo_block %} ## Split ZED and Merchant Portal navigation Split navigation significantly enhances performance for both ZED and the Merchant Portal when a project has both. This feature is shipped by default but existing projects may need to install it using the following steps: For projects that began before this feature was introduced, the following steps should be taken: 1. Install or update the following modules: - `spryker/merchant-portal-application:^1.4.0` - `spryker/zed-ui: ^3.1.0` 2. Move merchant portal related navigation from `config/Zed/navigation.xml` to `config/Zed/navigation-main-merchant-portal.xml`. 3. Rename `config/Zed/navigation-secondary.xml` to `config/Zed/navigation-secondary-merchant-portal.xml`. 4. Extend `src/Pyz/Zed/Twig/TwigDependencyProvider.php` with `new MerchantNavigationTypeTwigPlugin()`. 5. Extend `src/Pyz/Zed/ZedNavigation/ZedNavigationConfig.php` with the the following:

src/Pyz/Zed/ZedNavigation/ZedNavigationConfig.php

```php /** * @uses \Spryker\Zed\MerchantPortalApplication\Communication\Plugin\Twig\MerchantNavigationTypeTwigPlugin::NAVIGATION_TYPE_MAIN_MERCHANT_PORTAL * * @var string */ protected const NAVIGATION_TYPE_MAIN_MERCHANT_PORTAL = 'main-merchant-portal'; /** * @uses \Spryker\Zed\MerchantPortalApplication\Communication\Plugin\Twig\MerchantNavigationTypeTwigPlugin::NAVIGATION_TYPE_SECONDARY_MERCHANT_PORTAL * * @var string */ protected const NAVIGATION_TYPE_SECONDARY_MERCHANT_PORTAL = 'secondary-merchant-portal'; /** * @return array */ public function getCacheFilePaths(): array { $cacheFilePaths = parent::getCacheFilePaths(); $cacheFilePaths[static::NAVIGATION_TYPE_MAIN_MERCHANT_PORTAL] = $this->getCacheDirName() . 'navigation-main-merchant-portal.cache'; $cacheFilePaths[static::NAVIGATION_TYPE_SECONDARY_MERCHANT_PORTAL] = $this->getCacheDirName() . 'navigation-secondary-merchant-portal.cache'; return $cacheFilePaths; } /** * @return array */ public function getRootNavigationSchemaPaths(): array { $rootNavigationSchemaPaths = parent::getRootNavigationSchemaPaths(); $rootNavigationSchemaPaths[static::NAVIGATION_TYPE_MAIN_MERCHANT_PORTAL] = $this->getRootNavigationSchemasDirName() . 'navigation-main-merchant-portal.xml'; $rootNavigationSchemaPaths[static::NAVIGATION_TYPE_SECONDARY_MERCHANT_PORTAL] = $this->getRootNavigationSchemasDirName() . 'navigation-secondary-merchant-portal.xml'; return $rootNavigationSchemaPaths; } /** * @return array */ public function getNavigationSchemaFileNamePatterns(): array { $navigationSchemaFileNamePatterns = parent::getNavigationSchemaFileNamePatterns(); $navigationSchemaFileNamePatterns[static::NAVIGATION_TYPE_MAIN_MERCHANT_PORTAL] = 'navigation-main-merchant-portal.xml'; $navigationSchemaFileNamePatterns[static::NAVIGATION_TYPE_SECONDARY_MERCHANT_PORTAL] = 'navigation-secondary-merchant-portal.xml'; return $navigationSchemaFileNamePatterns; } public function getDefaultNavigationType(): string { if (APPLICATION === 'MERCHANT_PORTAL') { return self::NAVIGATION_TYPE_MAIN_MERCHANT_PORTAL; } return static::NAVIGATION_TYPE_MAIN; } ```

## Gateway performance When using Gateway for Twig rendering–for example, for sending emails–you can improve its performance as follows: 1. Update `spryker/twig` to version `3.28.0` or higher. 2. In `src/Pyz/Zed/Application/ApplicationDependencyProvider.php:getBackendGatewayApplicationPlugins()` replace `TwigApplicationPlugin()` with `TwigGatewayApplicationPlugin()`. ## Order placement performance For carts with big numbers of items, you can configure order items to be placed in batches for better performance. Take the steps in the following sections to do it. ### Prerequisites 1. Update `spryker/sales` and its dependencies to version [spryker/sales:^11.63.0](https://github.com/spryker/sales/releases/tag/11.63.0). 2. Configure columns to be returned for each order item: **src/Pyz/Zed/Sales/SalesConfig.php** ```php */ protected function getProductViewBulkExpanderPlugins(): array { return [ new ProductReviewStorageProductViewExpanderPlugin(), ]; } } ``` ## Reduce functionality Check if you require all features you currently use and check all applied plugins if you need them. Some plugins can probably be removed. Specifically, check the following ones: - `CheckoutDependencyProvider` - `CalculationDependencyProvider` There might be other DependencyProvider, and you must check if you can remove default applied features. Not all of them are used in all projects. ### Remove unneeded Twig functions Check if you need the `can` method calls from Twig. For example, `{% raw %}{%{% endraw %} if can('SeePricePermissionPlugin') {% raw %}%}{% endraw %}`. Talking back from Twig to PHP is often slow, so try to avoid that by checking if you need all used Twig functions Spryker provides. ### Use the newest modules Try to update the Spryker modules where you can, as we constantly add performance optimizations. Ideally, always use the latest versions of the Spryker modules. For a comprehensive list of performance-related module updates organized by category (Merchant Portal, order placement, OMS, publish and synchronization, cart performance, and more), along with update strategies and compatibility considerations, see [Keeping dependencies updated](/docs/dg/dev/guidelines/performance-guidelines/keeping-dependencies-updated.html). ## Performance profiling We constantly check the performance of Spryker by using profiling tools and work on optimizations whenever we see the need for it. We fix the performance issues as soon as possible when we see them or get informed about them. Therefore, whenever you see a performance issue feel free to [contact us](https://support.spryker.com), ideally with a performance profile that can look at.

Configure event queues

Wed, 13 May 2026 07:15:50 +0000

This document describes how event queues are configured.

To configure the event queue, follow these steps:

Install spryker/queue version at least 1.*. and spryker/rabbit-mq
Create the configuration for RabbitMQ in \Pyz\Client\RabbitMq\RabbitMqDependencyProvider as follows:

<?php
namespace Pyz\Client\RabbitMq;

use ArrayObject;
use Generated\Shared\Transfer\RabbitMqOptionTransfer;
use Spryker\Client\RabbitMq\Model\Connection\Connection;
use Spryker\Client\RabbitMq\RabbitMqDependencyProvider as RabbitMqRabbitMqDependencyProvider;
use Spryker\Shared\Event\EventConstants;

class RabbitMqDependencyProvider extends RabbitMqRabbitMqDependencyProvider
{

    /**
     * @return \ArrayObject
     */
    protected function getQueueOptions()
    {
        $queueOptionCollection = new ArrayObject();
        $queueOptionCollection->append($this->createEventExchangeQueueOption());
        $queueOptionCollection->append($this->createEventErrorExchangeQueueOption());

        return $queueOptionCollection;
    }

    /**
     * @return \Generated\Shared\Transfer\RabbitMqOptionTransfer
     */
    protected function createEventExchangeQueueOption()
    {
        $rabbitMqOptionTransfer = new RabbitMqOptionTransfer();
        $rabbitMqOptionTransfer->setQueueName(EventConstants::EVENT_QUEUE);
        $rabbitMqOptionTransfer->setAutoDelete(false);
        $rabbitMqOptionTransfer->setDurable(true);
        $rabbitMqOptionTransfer->setPassive(false);
        $rabbitMqOptionTransfer->setType('direct');
        $rabbitMqOptionTransfer->setDeclarationType(Connection::RABBIT_MQ_EXCHANGE);
        $rabbitMqOptionTransfer->setBindingQueue($this->createEventQueueBinding());

        return $rabbitMqOptionTransfer;
    }

    /**
     * @return \Generated\Shared\Transfer\RabbitMqOptionTransfer
     */
    protected function createEventErrorExchangeQueueOption()
    {
        $rabbitMqOptionTransfer = new RabbitMqOptionTransfer();
        $rabbitMqOptionTransfer->setQueueName(EventConstants::EVENT_QUEUE);
        $rabbitMqOptionTransfer->setAutoDelete(false);
        $rabbitMqOptionTransfer->setDurable(true);
        $rabbitMqOptionTransfer->setPassive(false);
        $rabbitMqOptionTransfer->setType('direct');
        $rabbitMqOptionTransfer->setDeclarationType(Connection::RABBIT_MQ_EXCHANGE);
        $rabbitMqOptionTransfer->setBindingQueue($this->createEventErrorQueueBinding());

        return $rabbitMqOptionTransfer;
    }

    /**
     * @return \Generated\Shared\Transfer\RabbitMqOptionTransfer
     */
    protected function createEventErrorQueueBinding()
    {
        $rabbitMqOptionTransfer = new RabbitMqOptionTransfer();
        $rabbitMqOptionTransfer->setQueueName(EventConstants::EVENT_QUEUE . '.error');
        $rabbitMqOptionTransfer->setAutoDelete(false);
        $rabbitMqOptionTransfer->setDurable(true);
        $rabbitMqOptionTransfer->setExclusive(false);
        $rabbitMqOptionTransfer->setPassive(false);
        $rabbitMqOptionTransfer->setRoutingKey('error');

        return $rabbitMqOptionTransfer;
    }

    /**
     * @return \Generated\Shared\Transfer\RabbitMqOptionTransfer
     */
    protected function createEventQueueBinding()
    {
        $rabbitMqOptionTransfer = new RabbitMqOptionTransfer();
        $rabbitMqOptionTransfer->setQueueName(EventConstants::EVENT_QUEUE);
        $rabbitMqOptionTransfer->setAutoDelete(false);
        $rabbitMqOptionTransfer->setDurable(true);
        $rabbitMqOptionTransfer->setExclusive(false);
        $rabbitMqOptionTransfer->setPassive(false);

        return $rabbitMqOptionTransfer;
    }

}

In \Pyz\Client\Queue\QueueDependencyProvider, add the RabbitMQ adapter:

<?php
namespace Pyz\Client\Queue;

use Spryker\Client\Kernel\Container;
use Spryker\Client\Queue\QueueDependencyProvider as BaseQueueDependencyProvider;

class QueueDependencyProvider extends BaseQueueDependencyProvider
{

    /**
     * @param \Spryker\Client\Kernel\Container $container
     *
     * @return \Spryker\Client\Queue\Model\Adapter\AdapterInterface[]
     */
    protected function createQueueAdapters(Container $container)
    {
        return [
            $container->getLocator()->rabbitMq()->client()->createQueueAdapter(),
        ];
    }

}

In \Pyz\Zed\Queue\QueueConfig, add receiver options for the event queue:

<?php
namespace Pyz\Zed\Queue;

use Generated\Shared\Transfer\RabbitMqConsumerOptionTransfer;
use Spryker\Shared\Event\EventConstants;
use Spryker\Zed\Queue\QueueConfig as SprykerQueueConfig;

class QueueConfig extends SprykerQueueConfig
{

    /**
     * @return array
     */
    protected function getQueueReceiverOptions()
    {
        return [
            EventConstants::EVENT_QUEUE => [
                'rabbitmq' => $this->getRabbitMqQueueConsumerOptions(),
            ],
        ];
    }

    /**
     * @return \Generated\Shared\Transfer\RabbitMqConsumerOptionTransfer
     */
    protected function getRabbitMqQueueConsumerOptions()
    {
        $queueOptionTransfer = new RabbitMqConsumerOptionTransfer();
        $queueOptionTransfer->setQueueName(EventConstants::EVENT_QUEUE);
        $queueOptionTransfer->setConsumerTag('');
        $queueOptionTransfer->setNoLocal(false);
        $queueOptionTransfer->setNoAck(false);
        $queueOptionTransfer->setConsumerExclusive(false);
        $queueOptionTransfer->setNoWait(false);

        return $queueOptionTransfer;
    }

}

In \Pyz\Zed\Queue\QueueDependencyProvider, add a plugin (consumer) to process messages or events.

Use EventQueueMessageProcessorPlugin

Since spryker/event:^2.17.0, use EventQueueMessageProcessorPlugin instead of EventRetryQueueMessageProcessorPlugin for the event retry queue. Both plugins define how the retry queue behaves when a message fails:

EventQueueMessageProcessorPlugin — processes failed messages directly in the retry queue. They are handled independently and do not re-enter the main queue.
EventRetryQueueMessageProcessorPlugin — routes failed messages back to the main queue (the queue without the .retry postfix). Under high load, this can slow down the processing of new messages in the main queue.

<?php
namespace Pyz\Zed\Queue;

use Spryker\Shared\Event\EventConstants;
use Spryker\Zed\Event\Communication\Plugin\Queue\EventQueueMessageProcessorPlugin;
use Spryker\Zed\Kernel\Container;
use Spryker\Zed\Queue\QueueDependencyProvider as SprykerDependencyProvider;
use Spryker\Zed\RabbitMq\Communication\Plugin\Queue\RabbitMqQueueMetricsReaderPlugin;

class QueueDependencyProvider extends SprykerDependencyProvider
{

    /**
     * @param \Spryker\Zed\Kernel\Container $container
     *
     * @return \Spryker\Zed\Queue\Dependency\Plugin\QueueMessageProcessorPluginInterface[]
     */
    protected function getProcessorMessagePlugins(Container $container)
    {
        return [
            EventConstants::EVENT_QUEUE => new EventQueueMessageProcessorPlugin(),
        ];
    }
    
    /**
     * @return array<\Spryker\Zed\RabbitMq\Communication\Plugin\Queue\RabbitMqQueueMetricsReaderPlugin>
     */
    protected function getQueueMetricsExpanderPlugins(): array
    {
        return [
            new RabbitMqQueueMetricsReaderPlugin(), // Provides RabbitMQ-specific metrics for the resource-aware queue worker. Applicable only for RabbitMqAdapter.
        ];
    }
}

In your application’s configuration file ./config/Shared/config_default.php or environment specific, make sure you have this configuration:

<?php

$config[QueueConstants::QUEUE_SERVER_ID] = (gethostname()) ?: php_uname('n');
$config[QueueConstants::QUEUE_WORKER_INTERVAL_MILLISECONDS] = 1000; // default 1000
$config[QueueConstants::QUEUE_WORKER_MAX_THRESHOLD_SECONDS] = 60; // 1min
$config[QueueConstants::QUEUE_WORKER_WAIT_LIMIT_ENABLED] = true; // Stop worker on exceeded execution time; waits up to QUEUE_WORKER_MAX_WAITING_SECONDS (default: 30s) for subprocesses

$config[QueueConstants::QUEUE_ADAPTER_CONFIGURATION] = [
    EventConstants::EVENT_QUEUE => [
        QueueConfig::CONFIG_QUEUE_ADAPTER => \Spryker\Client\RabbitMq\Model\RabbitMqAdapter::class,
        QueueConfig::CONFIG_MAX_WORKER_NUMBER => 1, //Increase number of workers if higher concurrency needed.
    ],
];

// Enables processing of queues with resource aware queue worker.
$config[QueueConstants::RESOURCE_AWARE_QUEUE_WORKER_ENABLED] = (bool)getenv('RESOURCE_AWARE_QUEUE_WORKER_ENABLED') ?? false;
$config[QueueConstants::QUEUE_WORKER_FREE_MEMORY_BUFFER] = (int)getenv('QUEUE_WORKER_FREE_MEMORY_BUFFER') ?: 750;
$config[QueueConstants::QUEUE_WORKER_MEMORY_READ_PROCESS_TIMEOUT] = (int)getenv('QUEUE_WORKER_MEMORY_READ_PROCESS_TIMEOUT') ?: 5;
$config[QueueConstants::QUEUE_WORKER_MAX_PROCESSES] = 10; // concurrent, for all queues/stores, default 5
$config[QueueConstants::QUEUE_WORKER_PROCESSES_COMPLETE_TIMEOUT] = 600; // 10 min, default 5 min

Metrics and resource-aware worker configuration

Starting with 202512.0, Spryker ships a resource-aware queue worker that uses queue metrics and system resource monitoring to make intelligent decisions about process spawning. The configuration keys referenced above (RESOURCE_AWARE_QUEUE_WORKER_ENABLED, QUEUE_WORKER_FREE_MEMORY_BUFFER, QUEUE_WORKER_MEMORY_READ_PROCESS_TIMEOUT, QUEUE_WORKER_MAX_PROCESSES, QUEUE_WORKER_PROCESSES_COMPLETE_TIMEOUT) control this worker’s behavior.

RabbitMqQueueMetricsReaderPlugin

Register the RabbitMqQueueMetricsReaderPlugin in your QueueDependencyProvider to supply RabbitMQ queue metrics (message counts, batch sizes) to the resource-aware worker:

// src/Pyz/Zed/Queue/QueueDependencyProvider.php

use Spryker\Client\RabbitMq\Plugin\Queue\RabbitMqQueueMetricsReaderPlugin;

class QueueDependencyProvider extends SprykerQueueDependencyProvider
{
    /**
     * @return array<\Spryker\Client\QueueExtension\Dependency\Plugin\QueueMetricsReaderPluginInterface>
     */
    protected function getQueueMetricsReaderPlugins(): array
    {
        return [
            new RabbitMqQueueMetricsReaderPlugin(),
        ];
    }
}

For the full configuration reference, architecture details, tuning recommendations, and backporting guidance, see Optimizing Jenkins execution with the resource-aware queue worker.

Migration status - Glue API to API Platform

Mon, 11 May 2026 12:19:49 +0000

This document tracks Spryker's migration of API-providing modules to the **API Platform** (built on Symfony and the API Platform library). Use it to plan upgrades and check the current status of every module. {% info_block infoBox "Looking for the integration guide?" %} This page does **not** describe how to integrate API Platform into your project. For step-by-step integration instructions, see: - [Migrate to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform.html) - [Integrate API Platform](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html) - [Integrate API Platform security](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform-security.html) - [API Platform architecture](/docs/dg/dev/architecture/api-platform.html) {% endinfo_block %} ## Why Spryker is moving to API Platform API Platform replaces Spryker-specific patterns for routing, authentication, and resource definition with industry-standard Symfony conventions, automatic OpenAPI schema generation, and a clean separation between resource schema, provider, and validation. | Aspect | Previous infrastructure | API Platform | |---|---|---| | Bootstrap | Spryker-specific application bootstrap | Symfony Kernel-based routing | | Resource registration | Manual plugin registration in `GlueApplicationDependencyProvider` | Declarative YAML resource definitions (`*.resource.yml`) | | Authentication | Custom flows per module | Standard OAuth2 / Symfony Security | | Coupling | Tight coupling between resource and routing logic | Clean separation: provider + resource schema + validation | | Testability | Complex to test and extend | Symfony-native, testable with standard PHPUnit patterns | | OpenAPI | Manual / partial | Automatic OpenAPI schema generation | ## General migration workflow For any module marked **Migrated**, projects upgrade in three high-level steps. Detailed instructions are in the linked integration guides above. 1. **Update the module to the API Platform-enabled version** Pull the new module version that ships the `*.resource.yml` schema and Provider class: ```bash composer update spryker/ ``` 2. **Remove the previous resource plugins** In your project's `GlueApplicationDependencyProvider`, remove the previous plugin registrations for the migrated module - typically a `ResourceRoutePlugin` (and any related `ResourceRelationshipPlugin` / expander plugins) registered in `getResourceRoutePlugins()`. For **extension-only** modules, remove or replace the corresponding plugin wiring in the parent module's dependency provider as indicated in the module's release notes. 3. **Clear caches and verify** ```bash vendor/bin/glue cache:clear vendor/bin/glue api:generate ``` Confirm the endpoint is served by API Platform by hitting it against your local Glue host - the response is now produced by the new Symfony-based stack. {% info_block infoBox "Parallel operation" %} The previous API stack and API Platform run **side by side** during the transition. You can migrate modules incrementally; modules that have not been migrated continue to be served by the previous stack. {% endinfo_block %} ### Status legend | Status | Meaning | |---|---| | Migrated | Module is available on API Platform and production-ready. | | Planned | Module is scheduled or queued for migration to API Platform. | ## Storefront API modules All StorefrontAPI and Extension-only StorefrontAPI modules. Migrated modules are listed first. | Module | Category | Status | Key endpoints | |---|---|----------|---| | ContentProductAbstractListsRestApi | StorefrontAPI | Migrated | GET /content-product-abstract-lists/{id}
GET /content-product-abstract-lists/{id}/abstract-products | | MerchantOpeningHoursRestApi | StorefrontAPI | Migrated | GET /merchants/{id}/merchant-opening-hours | | MerchantCategoriesRestApi | Extension-only StorefrontAPI | Migrated | MerchantsRestApi | | MerchantProductOffersRestApi | StorefrontAPI | Migrated | GET /concrete-products/{id}/product-offers
GET /product-offers/{id} | | MerchantProductOfferServicePointAvailabilitiesRestApi | Extension-only StorefrontAPI | Migrated | (transfer-only) | | MerchantsRestApi | StorefrontAPI | Migrated | GET /merchants
GET /merchants/{id}
GET /merchants/{id}/merchant-addresses | | OrderPaymentsRestApi | StorefrontAPI | Migrated | POST /order-payments | | PaymentsRestApi | StorefrontAPI | Migrated | POST /payments
POST /payment-cancellations
POST /payment-customers | | ProductAvailabilitiesRestApi | StorefrontAPI | Migrated | GET /abstract-products/{id}/abstract-product-availabilities
GET /concrete-products/{id}/concrete-product-availabilities | | ProductOfferAvailabilitiesRestApi | StorefrontAPI | Migrated | GET /product-offers/{id}/product-offer-availabilities | | ProductOfferServicePointAvailabilitiesRestApi | StorefrontAPI | Migrated | POST /product-offer-service-point-availabilities | | ProductOfferPricesRestApi | StorefrontAPI | Migrated | GET /product-offers/{id}/product-offer-prices | | ProductPricesRestApi | StorefrontAPI | Migrated | GET /abstract-products/{id}/abstract-product-prices
GET /concrete-products/{id}/concrete-product-prices | | ProductTaxSetsRestApi | StorefrontAPI | Migrated | GET /abstract-products/{id}/product-tax-sets | | ProductsRestApi | StorefrontAPI | Migrated | GET /abstract-products/{id}
GET /concrete-products/{id} | | ShipmentTypeProductOfferServicePointAvailabilitiesRestApi | Extension-only StorefrontAPI | Migrated | ProductOfferServicePointAvailabilitiesRestApi | | StoresApi | StorefrontAPI | Migrated | GET /stores | | AgentAuthRestApi | StorefrontAPI | Migrated | POST /agent-access-tokens
POST /agent-customer-impersonation-access-tokens
GET /agent-customer-search | | AlternativeProductsRestApi | StorefrontAPI | Planned | GET /abstract-products/{id}/related-products
GET /concrete-products/{id}/abstract-alternative-products
GET /concrete-products/{id}/concrete-alternative-products | | AuthRestApi | StorefrontAPI | Migrated | POST /token
POST /access-tokens
POST /refresh-tokens
DELETE /refresh-tokens/{id} | | AvailabilityNotificationsRestApi | StorefrontAPI | Planned | POST /availability-notifications
DELETE /availability-notifications/{id}
GET /my-availability-notifications
GET /customers/{id}/availability-notifications | | CartCodesRestApi | StorefrontAPI | Migrated | POST /carts/{id}/cart-codes
DELETE /carts/{id}/cart-codes/{id}
POST /guest-carts/{id}/cart-codes
DELETE /guest-carts/{id}/cart-codes/{id} | | CartPermissionGroupsRestApi | StorefrontAPI | Planned | GET /cart-permission-groups
GET /cart-permission-groups/{id} | | CartReorderRestApi | StorefrontAPI | Migrated | POST /cart-reorder | | CartsRestApi | StorefrontAPI | Migrated | GET,POST /carts
GET,PATCH,DELETE /carts/{id}
POST /carts/{id}/items
PATCH,DELETE /carts/{id}/items/{id}
GET /guest-carts
GET,PATCH /guest-carts/{id}
POST /guest-carts/{id}/guest-cart-items
PATCH,DELETE /guest-carts/{id}/guest-cart-items/{id}
GET /customers/{id}/carts | | CatalogSearchRestApi | StorefrontAPI | Migrated | GET /catalog-search
GET /catalog-search-suggestions | | CategoriesRestApi | StorefrontAPI | Migrated | GET /category-trees
GET /category-nodes/{id} | | CheckoutRestApi | StorefrontAPI | Planned | POST /checkout-data
POST /checkout | | CmsPagesRestApi | StorefrontAPI | Planned | GET /cms-pages
GET /cms-pages/{id} | | CompaniesRestApi | StorefrontAPI | Migrated | GET /companies
GET /companies/{id} | | CompanyBusinessUnitAddressesRestApi | StorefrontAPI | Planned | GET /company-business-unit-addresses
GET /company-business-unit-addresses/{id} | | CompanyBusinessUnitsRestApi | StorefrontAPI | Planned | GET /company-business-units
GET /company-business-units/{id} | | CompanyRolesRestApi | StorefrontAPI | Planned | GET /company-roles
GET /company-roles/{id} | | CompanyUserAuthRestApi | StorefrontAPI | Planned | POST /company-user-access-tokens | | CompanyUsersRestApi | StorefrontAPI | Planned | GET /company-users
GET /company-users/{id} | | ConfigurableBundleCartsRestApi | StorefrontAPI | Planned | POST /carts/{id}/configured-bundles
PATCH,DELETE /carts/{id}/configured-bundles/{id}
POST,PATCH,DELETE /guest-carts/{id}/guest-configured-bundles/{id} | | ConfigurableBundlesRestApi | StorefrontAPI | Planned | GET /configurable-bundle-templates
GET /configurable-bundle-templates/{id} | | ContentBannersRestApi | StorefrontAPI | Planned | GET /content-banners/{id} | | CustomerAccessRestApi | StorefrontAPI | Migrated | GET /customer-access | | CustomersRestApi | StorefrontAPI | Migrated | GET,POST /customers
GET,PATCH,DELETE /customers/{id}
GET,POST /customers/{id}/addresses
GET,PATCH,DELETE /customers/{id}/addresses/{id}
POST /customer-forgotten-password
PATCH /customer-restore-password/{id}
PATCH /customer-password/{id}
POST /customer-confirmation | | DiscountPromotionsRestApi | Extension-Only-StorefrontAPI | Planned | CartsRestApi, CartCodesRestApi | | DiscountsRestApi | StorefrontAPI | Migrated | POST /carts/{id}/vouchers
DELETE /carts/{id}/vouchers/{id}
POST /guest-carts/{id}/vouchers
DELETE /guest-carts/{id}/vouchers/{id} | | EntityTagsRestApi | Extension-only StorefrontAPI | Planned | GlueApplication | | GiftCardsRestApi | Extension-only StorefrontAPI | Migrated | GlueApplication | | MerchantProductOfferServicePointAvailabilitiesRestApi | Extension-only StorefrontAPI | Planned | (transfer-only) | | MerchantProductOfferShoppingListsRestApi | Extension-only StorefrontAPI | Planned | (transfer-only) | | MerchantProductOfferWishlistRestApi | Extension-only StorefrontAPI | Planned | WishlistsRestApi | | MerchantProductShoppingListsRestApi | Extension-only StorefrontAPI | Planned | (transfer-only) | | MerchantProductsRestApi | Extension-only StorefrontAPI | Planned | CartsRestApi | | MerchantRelationshipProductListsRestApi | Extension-only StorefrontAPI | Planned | CustomersRestApi | | MerchantSalesReturnsRestApi | Extension-only StorefrontAPI | Planned | (transfer-only) | | MerchantShipmentsRestApi | Extension-only StorefrontAPI | Planned | ShipmentsRestApi | | MultiCartsRestApi | Extension-only StorefrontAPI | Migrated | CartsRestApi | | NavigationsRestApi | StorefrontAPI | Migrated | GET /navigations/{id} | | OauthApi | StorefrontAPI | Migrated | POST /token | | OmsRestApi | Extension-only StorefrontAPI | Planned | OrdersRestApi | | OrderAmendmentsRestApi | Extension-only StorefrontAPI | Planned | OrdersRestApi, CartsRestApi, CartReorderRestApi | | OrdersRestApi | StorefrontAPI | Planned | GET /orders
GET /orders/{id}
GET /customers/{id}/orders | | PriceProductOfferVolumesRestApi | Extension-only StorefrontAPI | Planned | ProductOfferPricesRestApi | | PriceProductVolumesRestApi | Extension-only StorefrontAPI | Planned | ProductPricesRestApi | | ProductAttributesRestApi | StorefrontAPI | Migrated | GET /product-management-attributes
GET /product-management-attributes/{id} | | ProductBundleCartsRestApi | Extension-only StorefrontAPI | Planned | CartsRestApi, ShipmentsRestApi | | ProductBundlesRestApi | StorefrontAPI | Planned | GET /concrete-products/{id}/bundled-products | | ProductConfigurationShoppingListsRestApi | Extension-only StorefrontAPI | Planned | ShoppingListsRestApi | | ProductConfigurationWishlistsRestApi | Extension-only StorefrontAPI | Planned | WishlistsRestApi | | ProductConfigurationsPriceProductVolumesRestApi | Extension-only StorefrontAPI | Planned | ProductConfigurationsRestApi, ProductConfigurationShoppingListsRestApi, ProductConfigurationWishlistsRestApi | | ProductConfigurationsRestApi | Extension-only StorefrontAPI | Planned | ProductsRestApi, CartsRestApi, OrdersRestApi | | ProductDiscontinuedRestApi | Extension-only StorefrontAPI | Planned | ProductsRestApi | | ProductImageSetsRestApi | StorefrontAPI | Migrated | GET /abstract-products/{id}/abstract-product-image-sets
GET /concrete-products/{id}/concrete-product-image-sets | | ProductLabelsRestApi | StorefrontAPI | Planned | GET /product-labels/{id} | | ProductMeasurementUnitsRestApi | StorefrontAPI | Planned | GET /product-measurement-units/{id}
GET /concrete-products/{id}/sales-units | | ProductOfferSalesRestApi | Extension-only StorefrontAPI | Planned | (transfer-only) | | ProductOfferShoppingListsRestApi | Extension-only StorefrontAPI | Planned | (transfer-only) | | ProductOffersRestApi | Extension-only StorefrontAPI | Planned | ProductsRestApi | | ProductOptionsRestApi | Extension-only StorefrontAPI | Planned | CartsRestApi, OrdersRestApi, ProductsRestApi, QuoteRequestsRestApi | | ProductReviewsRestApi | StorefrontAPI | Planned | GET,POST /abstract-products/{id}/product-reviews
GET /abstract-products/{id}/product-reviews/{id} | | QuoteRequestAgentsRestApi | StorefrontAPI | Planned | GET,POST /agent-quote-requests
GET,PATCH /agent-quote-requests/{id}
POST /agent-quote-requests/{id}/agent-quote-request-cancel
POST /agent-quote-requests/{id}/agent-quote-request-revise
POST /agent-quote-requests/{id}/agent-quote-request-send-to-customer | | QuoteRequestsRestApi | StorefrontAPI | Planned | GET,POST /quote-requests
GET,PATCH /quote-requests/{id}
POST /quote-requests/{id}/quote-request-cancel
POST /quote-requests/{id}/quote-request-revise
POST /quote-requests/{id}/quote-request-send-to-user
POST /quote-requests/{id}/quote-request-convert-to-quote | | RelatedProductsRestApi | StorefrontAPI | Planned | GET /abstract-products/{id}/related-products | | SalesOrderThresholdsRestApi | Extension-only StorefrontAPI | Planned | CartsRestApi, CheckoutRestApi | | SalesReturnsRestApi | StorefrontAPI | Planned | GET /return-reasons
GET,POST /returns
GET /returns/{id} | | SecurityBlockerRestApi | Extension-only StorefrontAPI | Planned | GlueApplication | | ServicePointCartsRestApi | Extension-only StorefrontAPI | Planned | CheckoutRestApi | | ServicePointsRestApi | StorefrontAPI | Planned | GET /service-points
GET /service-points/{id}
GET /service-points/{id}/service-point-addresses/{id} | | SharedCartsRestApi | StorefrontAPI | Planned | POST /carts/{id}/shared-carts
PATCH,DELETE /shared-carts/{id} | | ShipmentTypeServicePointsRestApi | Extension-only StorefrontAPI | Planned | CheckoutRestApi, ShipmentsRestApi, ShipmentTypesRestApi | | ShipmentTypesRestApi | StorefrontAPI | Planned | GET /shipment-types
GET /shipment-types/{id} | | ShipmentsRestApi | Extension-only StorefrontAPI | Planned | CheckoutRestApi, OrdersRestApi, QuoteRequestsRestApi | | ShoppingListsRestApi | StorefrontAPI | Planned | GET,POST /shopping-lists
GET,PATCH,DELETE /shopping-lists/{id}
POST /shopping-lists/{id}/shopping-list-items
PATCH,DELETE /shopping-lists/{id}/shopping-list-items/{id} | | TaxAppRestApi | StorefrontAPI | Planned | POST /tax-id-validate | | UpSellingProductsRestApi | StorefrontAPI | Planned | GET /carts/{id}/up-selling-products
GET /guest-carts/{id}/up-selling-products | | UrlsRestApi | StorefrontAPI | Planned | GET /url-resolver | | WishlistsRestApi | StorefrontAPI | Planned | GET,POST /wishlists
GET,PATCH,DELETE /wishlists/{id}
POST /wishlists/{id}/wishlist-items
PATCH,DELETE /wishlists/{id}/wishlist-items/{id} | ## Backend API modules All BackendAPI modules tracked in the migration scope. | Module | Category | Status | Key endpoints | |---|---|---|---| | CartNotesBackendApi | Extension-Only BackendAPI | Planned | SalesOrdersBackendApi | | CategoriesBackendApi | BackendAPI | Planned | GET,POST /categories
GET,PATCH /categories/{id} | | DynamicEntityBackendApi | BackendAPI | Planned | GET,POST,PATCH,PUT /dynamic-entity/{entity-name} (~62 auto-generated entity endpoints) | | OauthBackendApi | BackendAPI | Planned | POST /token | | PickingListsBackendApi | BackendAPI | Planned | GET /picking-lists
GET /picking-lists/{id}
PATCH /picking-lists/{id}/picking-list-items/{id}
POST /start-picking | | PickingListsUsersBackendApi | Extension-Only BackendAPI | Planned | PickingListsBackendApi | | PickingListsWarehousesBackendApi | Extension-Only BackendAPI | Planned | PickingListsBackendApi | | ProductAttributesBackendApi | BackendAPI | Planned | GET,POST /product-attributes
GET,PATCH /product-attributes/{id} | | ProductImageSetsBackendApi | BackendAPI | Planned | GET /concrete-product-image-sets | | ProductPackagingUnitsBackendApi | Extension-Only BackendAPI | Planned | PickingListsBackendApi | | ProductsBackendApi | BackendAPI | Planned | GET,POST /product-abstract
DELETE,GET,PATCH /product-abstract/{id} | | PushNotificationsBackendApi | BackendAPI | Planned | GET,POST /push-notification-providers
PATCH,DELETE /push-notification-providers/{id}
POST /push-notification-subscriptions | | SalesOrdersBackendApi | BackendAPI | Planned | GET /sales-orders | | ServicePointsBackendApi | BackendAPI | Planned | GET,POST /service-points
GET,PATCH /service-points/{id}
GET,POST /service-point-addresses
PATCH /service-points/{id}/service-point-addresses/{id}
GET,POST /service-types
GET,PATCH /service-types/{id}
GET,POST /services
GET,PATCH /services/{id} | | ShipmentTypesBackendApi | BackendAPI | Planned | GET,POST /shipment-types
GET,PATCH /shipment-types/{id} | | ShipmentsBackendApi | BackendAPI | Planned | GET /sales-shipments | | StoresBackendApi | BackendAPI | Planned | GET,POST,PATCH /stores | | UsersBackendApi | BackendAPI | Planned | GET /users | | WarehouseOauthBackendApi | BackendAPI | Planned | POST /warehouse-tokens | | WarehouseUsersBackendApi | BackendAPI | Planned | GET,POST /warehouse-user-assignments
GET,PATCH,DELETE /warehouse-user-assignments/{id} | | WarehousesBackendApi | BackendAPI | Planned | GET /warehouses |

Spryker Core Back Office feature overview

Thu, 07 May 2026 18:46:30 +0000

A Spryker-based shop ships with a comprehensive, intuitive administration area and consists of numerous features that give you a strong hold over the customization of your store. Here you can tailor features to your specific needs, manage orders, products, and customers, and modify the look and feel of your store by—for example, designing eye-catching marketing campaigns and promotions, and much more. The Spryker Back Office provides you with a variety of sections that are logically connected to each other. {% info_block infoBox "Spryker Back Office" %} It provides the product and content management capabilities, categories and navigation building blocks, search and filter customizations, barcode generator, order handling, company structure creation (*for B2B users*), and merchant-buyer contracts' setup. {% endinfo_block %} With Spryker Back Office, you can do the following: - Manage orders placed by your customers as well as create orders for customers. - Create and manage customers. - Build and manage product categories. - Create and manage CMS blocks and pages. - Handle translations. - Manage products and all elements related to them (availability, labels, options, types). - Customize search and filters for the online store. - Create and manage discounts. - Build and manage the main navigation of your online store. - Create new carrier companies and shipment methods as well as manage those. - Create admin users, and add roles and user groups. Depending on the roles and teams in your project, you can limit the access of different Back Office users to specific Back Office areas. **Back Office provides both B2B and B2C capabilities.** {% info_block infoBox "Info" %} The following diagram shows what features are used for both *B2B and B2C* and which are *B2B-specific*. {% endinfo_block %} ![B2B and B2C features](https://spryker.s3.eu-central-1.amazonaws.com/docs/scos/user/features/spryker-core-back-office-feature-overview/spryker-core-back-office-feature-overview.md/b2b-and-b2c-features.png) You can always define what exactly is going to be needed for your specific project. ## Related Business User documents |BACK OFFICE USER GUIDES| |---| | [Get a general idea of the Back Office Translations](/docs/pbc/all/back-office/latest/base-shop/back-office-translations-overview.html) | ## Related Developer articles |INSTALLATION GUIDES | REFERENCES| |---------|---------| | [Install the Spryker Core Back Office feature](/docs/pbc/all/identity-access-management/latest/install-and-upgrade/install-the-spryker-core-back-office-feature.html) | [Back Office Translations overview](/docs/pbc/all/back-office/latest/base-shop/back-office-translations-overview.html) | | [Microsoft Azure Active Directory](/docs/pbc/all/identity-access-management/latest/install-and-upgrade/install-microsoft-azure-active-directory.html) | [Users and rights overview](/docs/pbc/all/user-management/latest/base-shop/user-and-rights-overview.html) | | [Install Federated Authentication via OAuth2/OIDC](/docs/pbc/all/oauth/latest/install-and-upgrade/install-federated-authentication.html) | [Federated Authentication via OAuth2/OIDC](/docs/pbc/all/oauth/latest/federated-authentication.html) |

Merchant users overview

Thu, 07 May 2026 18:46:30 +0000

The merchant concept presupposes having employees with access to the Merchant Portal that will perform various actions on behalf of the merchants. To enable that, the *merchant user* entity is introduced. From the technical point of view, Merchant Portal is a subset of modules in Zed functioning separately from the Back Office application. As in the Back Office, there are users performing different types of actions (they are further on called *Back Office users*); the Merchant Portal has merchant users that function similarly within a merchant account. {% info_block infoBox "Example" %} For example, there can be a person responsible only for creating and managing product offers; the other person takes care of shipping merchant orders to their buyers. It means that two merchant users need to be created for these purposes. {% endinfo_block %} To add merchant users for a merchant, the merchant must be created first. When the merchant record exists, a Marketplace administrator can set up one or several merchant users to manage the merchant account. The merchant users concept follows certain rules: - Every merchant user has a unique email address in the system. - A merchant user belongs to one merchant, and the same merchant user can't be assigned to two or more merchants. ## Merchant user statuses The following table explains all the statuses that may apply to a merchant user. | STATUS | DESCRIPTION | | --- | --- | | Active | When the merchant user has the `Active` status, it means that the merchant is approved, the merchant user account is activated, the email with reset password instructions has been sent, and the merchant user has access to the Merchant Portal. | | Deactivated | Access to the Merchant Portal is revoked for a deactivated merchant user. A merchant user can be deactivated when:

A merchant or Marketplace administrator deactivates the merchant user.
The merchant to whom the merchant user belongs has been [denied](/docs/pbc/all/merchant-management/latest/marketplace/marketplace-merchant-feature-overview/marketplace-merchant-feature-overview.html#merchant-statuses).

| | Deleted | Access to the Merchant Portal is revoked for the deleted merchant user. In the current implementation, both statuses `Deactivated` and `Deleted` have the same functionality—they restrict access to the Merchant Portal. However, this can be changed and adapted on the project level. | ## Merchant user access Both merchant and typical Back Office users have a common entry point, but the login URLs to the Back Office and Merchant Portal are different. The exemplary login link to the Merchant Portal is `https://os.de.marketplace.demo-spryker.com/security-merchant-portal-gui/login`. To log in to the Merchant Portal, both a merchant and merchant user need to be activated in the Back Office. {% info_block infoBox "Info" %} If a merchant is [denied](/docs/pbc/all/merchant-management/latest/marketplace/marketplace-merchant-feature-overview/marketplace-merchant-feature-overview.html#merchant-statuses), all their merchant users get deactivated automatically. If the merchant is re-approved again, their merchant users need to be re-activated one by one manually. {% endinfo_block %} Upon entering the Merchant Portal, a separate area with a different navigation menu is displayed to a merchant user. Merchant users have access only to the information related to their organization through the Merchant Portal application (profile, products, offers, orders); that is, merchant users have their own area and do not access the Back Office. ## Merchant user workflow 1. A Marketplace administrator creates a merchant and approves it. 2. When the merchant is approved, corresponding merchant users can be created in **Back Office > Merchant > Users**. 3. A Marketplace administrator can assign needed user groups to allow or restrict certain permissions for Merchant Portal in **Back Office > Users > Users**. 4. After the merchant user is created, they need to be activated to log in to the Merchant Portal. 5. The "Reset Password" email is sent to the activated merchant user. 6. After the password is reset, the merchant user can log in to the Merchant Portal.

Marketplace Merchant Portal Core feature overview

Thu, 07 May 2026 18:46:30 +0000

The Marketplace Merchant Portal Core enables server configuration and basic functions of the Merchant Portal application, such as secure login, GUI tables, and dashboards. Merchant Portal and Back Office are separate applications with different entry points, bootstraps, and possibilities to register application plugins, configure application base URLs, and debug. To learn more about the Marketplace Application, see [Marketplace Application Composition](/docs/dg/dev/architecture/marketplace-architecture/marketplace-application-composition.html). Login and logout in the Merchant Portal are provided by the `SecurityMerchantPortalGui` module, which also provides the `ZedMerchantUserSecurityPlugin` for extending the Merchant Portal firewall. ## Module dependency graph The following diagram illustrates the dependencies between the modules for the Marketplace Merchant Portal Core feature. ![Modules relation](https://confluence-connect.gliffy.net/embed/image/2e0be237-6e7b-4488-8d4b-811707c14ea0.png?utm_medium=live&utm_source=custom) ### Main Marketplace MerchantPortal Core feature modules The following table lists the main MerchantPortal Core modules: | NAME | DESCRIPTION | | -------------- | ------------------ | | [Acl](https://github.com/spryker/acl) | Acl is part of the Store Administration. The purpose of this module is to define roles, groups, privileges, and resources to manage access privileges to Zed Administration Interface. | | [AclEntity](https://github.com/spryker/acl-entity) | This module provides a database structure for `AclEntitySegment` and `AclEntityRule` as well as methods for managing them. | | [AclMerchantPortal](https://github.com/spryker/acl-merchant-portal) | Acl and merchant entities are connected through this module. | | [GuiTable](https://github.com/spryker/gui-table) | This module provides base functionality for building GuiTables. | | [MerchantPortalApplication](https://github.com/spryker/merchant-portal-application) | This module provides basic infrastructure for the MerchantPortal modules. | | [MerchantUser](https://github.com/spryker/merchant-user) | Merchant user module provides data structure, facade methods and plugins that let users relate to merchants. | | [MerchantUserPasswordResetMail](https://github.com/spryker/merchant-user-password-reset-mail) | This module provides possibility to reset password for the merchant user. | | [Navigation](https://github.com/spryker/navigation) | This module manages multiple navigation menus that can be displayed on the frontend. | | [SecurityMerchantPortalGui](https://github.com/spryker/security-merchant-portal-gui) | This module provides security rules and authentication for merchant users. | | [UserMerchantPortalGui](https://github.com/spryker/user-merchant-portal-gui) | This module module provides components for merchant user management. | | [ZedUi](https://github.com/spryker/zed-ui) | This module provides base UI components for Zed application. | ### Optional Marketplace MerchantPortal Core feature modules The following table lists optional MerchantPortal Core modules: | NAME | DESCRIPTION | | -------------------- | --------------------- | | [DashboardMerchantPortalGui](https://github.com/spryker/dashboard-merchant-portal-gui) | This module contains the dashboard and its related components for the Merchant Portal. | | [DashboardMerchantPortalGuiExtension](https://github.com/spryker/dashboard-merchant-portal-gui-extension) | This module provides extension interfaces for the `DashboardMerchantPortalGui` module.| | [MerchantUserExtension](https://github.com/spryker/merchant-user-extension) | This module provides plugin interfaces to extend `MerchantUser` module from another modules. | | [UserMerchantPortalGuiExtension](https://github.com/spryker/user-merchant-portal-gui-extension) | This module provides plugin interfaces to extend the `UserMerchantPortalGui` module from the other modules. | ## Domain model The following schema illustrates the Marketplace MerchantPortal Core domain model: ![Domain model](https://confluence-connect.gliffy.net/embed/image/2f5bae0d-8b37-45f5-ad08-06ca5c0c562d.png?utm_medium=live&utm_source=custom) ## Gui table `GuiTable` is a Spryker infrastructure component, which displays data as tables and provides search, filtering, sorting, and various interactions with table rows. `GuiTable` components are widely used in the Marketplace Merchant Portal for displaying orders, offers, and products. The `GuiTable` frontend component knows how to create the table itself, where to go for the data, and how to interpret the provided data based on the configuration provided. {% info_block warningBox "Table design" %} To learn more about table design, see [Table design](/docs/dg/dev/frontend-development/latest/marketplace/table-design/table-design.html). {% endinfo_block %} ## Related Developer documents |INSTALLATION GUIDES |GLUE API GUIDES |DATA IMPORT | REFERENCES | |---------|---------|---------|--------| | [Install the Marketplace Merchant Portal Core feature](/docs/pbc/all/merchant-management/latest/marketplace/install-and-upgrade/install-features/install-the-marketplace-merchant-portal-core-feature.html) | | [File details: merchant_user.csv](/docs/pbc/all/merchant-management/latest/marketplace/import-and-export-data/import-file-details-merchant-user.csv.html) | [GUI modules concept](/docs/pbc/all/merchant-management/latest/marketplace/marketplace-merchant-portal-core-feature-overview/gui-modules.html) | | [Install Federated Authentication via OAuth2/OIDC](/docs/pbc/all/oauth/latest/install-and-upgrade/install-federated-authentication.html) | | | [Federated Authentication via OAuth2/OIDC](/docs/pbc/all/oauth/latest/federated-authentication.html) | | | | | [How to create a new GUI module](/docs/pbc/all/merchant-management/latest/marketplace/tutorials-and-howtos/create-gui-modules.html) | | | | | [How to create a new Gui table](/docs/pbc/all/merchant-management/latest/marketplace/tutorials-and-howtos/create-gui-tables.html) | | | | | [How to extend an existing Gui table](/docs/pbc/all/merchant-management/latest/marketplace/tutorials-and-howtos/extend-gui-tables.html) | | | | | [How to create a new Gui table filter type](/docs/pbc/all/merchant-management/latest/marketplace/tutorials-and-howtos/create-gui-table-filter-types.html) | | | | | [How to extend Merchant Portal dashboard](/docs/pbc/all/merchant-management/latest/marketplace/tutorials-and-howtos/extend-merchant-portal-dashboard.html) |

Spryker Documentation

Configure multiple AI providers for AI Commerce

How it works

Prerequisites

1) Configure AI providers in config_ai.php

2) Sync the AI vendor configuration

3) Set credentials in the Back Office

4) Select the active provider per feature

Configuration reference

Configuration Management feature

What It Does

Quick Start

1. Declare settings in a YAML schema

2. Sync schemas

3. Consume in your module Config

Reading Configuration Values

The getModuleConfig() Method

Real-World Examples

Scope-Specific Reads

Integration Checklist

YAML Schema Declaration Reference

Schema Validation

Hierarchy

Feature Level

Tab Level

Group Level

Setting Level

Setting Types

File upload fields

file_upload properties

Options

Environment Variable Defaults

Secret vs Storefront Behavior

Available Scopes

Constraints

Built-in Constraint Types

Dependencies

Dependency Rule

When Clause

Condition

Dependency Operators

XSS Sanitization

Status Badges

Schema File Locations

Backoffice Management

Search

Override Detection

Twig Integration

configurationValue

configurationValues

Data Import

CSV format

Running the import

Behavior

Console Commands

Common Issues

Optimizing Jenkins execution with the resource-aware queue worker

Keeping dependencies updated for performance

General performance guidelines

Configure event queues

Metrics and resource-aware worker configuration

RabbitMqQueueMetricsReaderPlugin

Migration status - Glue API to API Platform

Spryker Core Back Office feature overview

Merchant users overview

Marketplace Merchant Portal Core feature overview

The `getModuleConfig()` Method

`file_upload` properties

`configurationValue`

`configurationValues`