Spryker Documentation

Release notes 202604.0

Fri, 17 Apr 2026 10:26:01 +0000

Spryker Cloud Commerce OS is an end-to-end solution for digital commerce. This document contains a business-level description of new features and improvements. For information about installing Spryker, see [Getting started guide](/docs/dg/dev/development-getting-started-guide). ## Connected, and AI-Enabled Platform ### Algolia configuration in the Back Office {% include badge.html type="improvement" %} We updated the Algolia integration configuration to use the Back Office Configuration Framework instead of the legacy ACP-based setup. This gives users a clearer and more consistent way to manage Algolia credentials directly in the Back Office. **Key capabilities:** - Added a dedicated configuration page under **Back Office > Configuration > Integrations > Algolia** - Added fields for **Application ID**, **Search-only API key**, and **Admin API key** - Added credential validation through the Algolia API - Aligned Algolia configuration with the current integration approach in Spryker **Business benefits:** - Simplifies Algolia setup for project teams - Reduces implementation effort and configuration errors - Replaces legacy integration-specific configuration with a standardized Back Office experience **Documentation:** ### Mollie PSP integration {% include badge.html type="feature" %} We introduced a new Mollie payment service provider integration for European B2B and B2C commerce scenarios. The integration helps customers implement a region-relevant PSP faster and with less custom project effort. **Key capabilities:** - Added support for Mollie as a payment service provider - Enables a PSP option that is well aligned with European market requirements - Delivered in collaboration with Spryker Solution Partner **KPS** **Business benefits:** - Speeds up go-live for European payment setups - Reduces bespoke implementation and maintenance effort - Improves checkout fit for local payment expectations across European markets **Documentation:** ### IAM readiness and standardized OAuth SSO integration {% include badge.html type="feature" %} We introduced a reusable and standardized approach for OAuth 2.0 and OpenID Connect single sign-on across Spryker applications. This release makes identity integrations more predictable and easier to implement for the Back Office, Storefront, and Platform API. **Key capabilities:** - Standardized OAuth SSO approach for the **Back Office**, **Storefront**, and **Platform API** - Added provider-agnostic integration patterns for external identity providers such as Keycloak, Azure AD, and Okta - Added token exchange support for headless scenarios in the Platform API - Added persistent identity linking between external identities and Spryker users or customers - Enabled configuration of OAuth providers through YAML without code changes - Preserved backward compatibility with existing form-based login **Business benefits:** - Reduces custom development for enterprise identity integrations - Makes SSO implementations faster, more repeatable, and more predictable - Improves consistency across applications and user roles **Documentation:** ### Back Office Configuration Framework reaches General Availability The Back Office Configuration Framework is now generally available. This release closes key operational and usability gaps to make configuration management more transparent, searchable, and reliable for production use. **Key capabilities:** - Added stronger governance and transparency for configuration changes - Improved discoverability and search for configuration options - Enhanced usability of configuration workflows in the Back Office - Added support for streamlined configuration import workflows - Improved visibility of conflicts between code-based and Back Office configuration **Business benefits:** - Increases operator confidence through better transparency and governance - Reduces time spent finding and managing configuration settings - Makes the framework ready for broader enterprise adoption **Documentation:** ### Smart PIM in the public demo shop {% include badge.html type="early-access" %} We added Smart PIM to the public demo shop to showcase AI-assisted product enrichment in the Back Office. The feature helps users create richer and more consistent product data with less manual effort. **Key capabilities:** - Supports AI-powered translation of product names and descriptions into any locale - Improves product names and descriptions with AI assistance - Generates alt text for product images - Suggests best-fitting product categories - Provides user-friendly error handling when the AI integration is not configured **Business benefits:** - Reduces manual effort when enriching product data - Helps merchants scale catalog creation and localization faster - Improves product content quality and consistency across markets **Documentation:** ### AI visual search in the demo shop {% include badge.html type="early-access" %} We added AI-powered visual search to the public demo shop. Customers can search for products using an uploaded photo, making product discovery faster and more intuitive in image-driven use cases. **Key capabilities:** - Enables product search through image upload - Supports mobile-friendly visual search experiences - Uses Spryker AI Foundation for AI connectivity - Helps identify products based on visual input instead of manual search terms **Business benefits:** - Reduces friction in product discovery for technical and spare-part scenarios - Helps customers find the right product faster and with fewer errors - Improves conversion through a more intuitive search experience **Documentation:** ### Back Office AI Assistant {% include badge.html type="early-access" %} We introduced an AI-powered assistant in the Back Office that helps operators complete selected tasks through natural language chat. The feature is available as Early Access and is designed to improve efficiency in common operational workflows. **Key capabilities:** - Added a chat interface directly in the Back Office - Supports order status questions and Back Office navigation guidance - Supports discount creation through chat for selected cart rule scenarios - Supports basic product creation through chat - Supports order creation from invoice PDFs with SKU and quantity information - Added AI Foundation enhancements to better support chat-based agent workflows **Business benefits:** - Reduces time spent on repetitive Back Office tasks - Lowers UI navigation effort for operators - Demonstrates AI-assisted operational workflows for pilot and demo scenarios **Documentation:** ### AI workflow visualization in the Back Office {% include badge.html type="early-access" %} We added Back Office visibility for AI workflow execution. Users can now inspect workflow runs, review state history, and manually trigger available actions when needed. **Key capabilities:** - Added an AI workflow list page in the Back Office - Added a workflow details page with state history - Added visualized workflow state progression similar to OMS process views - Added support for triggering manual events when available **Business benefits:** - Improves transparency into AI-driven workflow execution - Makes workflow troubleshooting and monitoring easier - Supports operational control for AI-assisted processes **Documentation:** ### AI Foundation audit log {% include badge.html type="improvement" %} We introduced persistent audit logging for AI interactions and added a dedicated Back Office UI for inspection and monitoring. This provides a structured record of prompts, responses, model details, token usage, and execution timing. **Key capabilities:** - Persisted AI interaction data in the database for auditability - Added a dedicated **Intelligence > Audit Logs** page in the Back Office - Added sorting, filtering, and pagination for AI interaction logs - Added aggregation statistics such as total requests, total tokens, success rate, and average inference time - Added inline inspection for prompts, responses, and metadata **Business benefits:** - Improves traceability and governance for AI-powered features - Simplifies troubleshooting and performance analysis - Helps teams monitor AI usage, optimize prompts, and manage costs **Documentation:** ### Punchout gateway with native cXML and OCI support {% include badge.html type="feature" %} We introduced native Punchout gateway capabilities for cXML and OCI to support procurement-driven B2B commerce scenarios. This makes Punchout integrations more reusable and reduces project-specific implementation effort. **Key capabilities:** - Added native support for **cXML** and **OCI** Punchout flows - Supports key requisition flow steps such as session start, cart editing, and cart return - Added standard OCI parameter handling and OCI cart return support - Added reusable building blocks and implementation guidance for Punchout projects **Business benefits:** - Reduces bespoke development for Punchout integrations - Speeds up delivery of procurement-based sales channels - Improves support for SAP-centric procurement environments **Documentation:** ### New Stripe integration {% include badge.html type="improvement" %} We replaced the legacy ACP-based Stripe approach with a new Stripe integration designed for extensibility and direct integration into the Spryker payment stack. We also added a Back Office configuration page for Stripe settings. **Key capabilities:** - Added a new Stripe Eco module that works without ACP at runtime - Integrated Stripe into the standard Spryker payment stack - Added support for payment initialization, authorization, capture, refund, and cancel flows - Added a dedicated configuration page under **Back Office > Configuration > Integrations > Stripe** - Added validation for configuration values, including webhook-related checks **Business benefits:** - Gives customers and partners more flexibility to extend Stripe payment flows - Reduces dependency on legacy implementation constraints - Improves maintainability and long-term cost efficiency **Documentation:** ### New Vertex integration {% include badge.html type="improvement" %} We introduced a new Vertex integration to replace the legacy ACP-based approach. The new integration is designed to provide more flexibility and reduce dependency on legacy architecture constraints. **Key capabilities:** - Added a new Vertex integration approach outside of the legacy ACP app model - Improves extensibility for tax-related integration scenarios - Reduces architectural constraints for future tax logic adaptations **Business benefits:** - Supports more flexible implementation of tax calculation scenarios - Reduces integration friction for changing tax and business requirements - Improves maintainability and lowers long-term ownership cost **Documentation:** ### API Platform reaches General Availability API Platform is now generally available as the new foundation for API development in Spryker. Existing APIs were migrated internally to API Platform while keeping external contracts backward compatible. **Key capabilities:** - Migrated internal API infrastructure to **API Platform** - Preserved existing external API interfaces for current consumers - Improved extensibility and standardization of API development - Supports more declarative API resource definition and generation - Provides a stronger foundation for future API capabilities **Business benefits:** - Reduces development effort for new and existing APIs - Speeds up API delivery and change cycles - Lowers long-term maintenance effort with a more standardized framework **Documentation:** ## Other ### Back Office Configuration Framework {% include badge.html type="feature" %} Introduced the Back Office Configuration Framework as generally available to provide a structured way to manage and extend Back Office configuration. This helps standardize configuration handling across Back Office capabilities. **Key capabilities:** - Provides a dedicated framework for Back Office configuration management - Supports more consistent and scalable Back Office extensibility **Business benefits:** - Simplifies configuration of Back Office capabilities - Reduces implementation complexity for configuration-related customizations **Documentation:** ### AI Foundation: Audit logs {% include badge.html type="feature" %} Added audit log capabilities for AI Foundation to improve traceability of AI-related actions and events. This helps teams monitor usage and maintain better operational oversight. **Key capabilities:** - Captures audit logs for AI Foundation activities - Improves visibility into AI-related actions **Business benefits:** - Supports governance and compliance requirements - Makes troubleshooting and operational monitoring easier **Documentation:** ### AI Foundation: Audit Log UI in the Back Office {% include badge.html type="feature" %} Added a Back Office user interface for AI Foundation audit logs so users can review audit information directly in the Back Office. This makes audit data more accessible for daily operations and investigations. **Key capabilities:** - Provides a Back Office interface for viewing AI Foundation audit logs - Makes audit information easier to access and review **Business benefits:** - Speeds up investigations and operational checks - Improves usability for business and support teams **Documentation:** ### OCI API compatibility and documentation enablement {% include badge.html type="feature" %} Added foundational OCI compatibility support and documentation enablement for SAP-centric procurement integrations. This reduces project-specific implementation effort and strengthens procurement integration support in enterprise B2B environments. **Key capabilities:** - Supports standard OCI parameters such as `HOOK_URL`, `OCI_VERSION`, and `USERNAME` - Handles OCI cart return flows with line items posted back to the procurement system - Includes documentation and integration guidance for SAP and Ariba use cases - Provides a reference implementation example **Business benefits:** - Reduces effort required to implement OCI-based procurement integrations - Increases confidence for SAP-heavy enterprise B2B projects - Improves Spryker fit for standardized procurement scenarios **Documentation:** ## B2B Business-Ready Commerce Experiences ### Login UX improvements {% include badge.html type="improvement" %} We improved the login experience across the Back Office, Storefront, and Marketplace to help users resume work faster and reduce friction in daily operations. Users now land on a more meaningful starting point after login, and session timeout handling preserves navigation context so they can return to the page they were using. **Key capabilities:** - Redirects Back Office users to the dashboard after login instead of a blank technical page - Adds quick actions to the Back Office dashboard for common tasks such as viewing orders, adding products, opening the catalog, and checking returns - Restores the last visited page after session timeout across the Back Office, Storefront, and Marketplace - Reopens create and edit pages after re-login, while requiring users to re-enter unsaved data **Business benefits:** - Reduces onboarding friction for new users - Improves efficiency for operational teams working across daily workflows - Creates a more intuitive and consistent user experience - Improves product demoability and perceived product maturity **Documentation:** ### Product attribute display types {% include badge.html type="feature" %} You can now control where product attributes are displayed without project-specific customization. This helps keep buyer-facing product information focused while preserving internal attributes for operational and automation use cases. **Key capabilities:** - Introduces native visibility types for product attributes - Supports controlling attribute visibility for internal use, PDP, and PLP and cart contexts - Enables business and technical teams to use operational attributes without exposing them to buyers **Business benefits:** - Reduces repeated custom implementations across projects - Improves time-to-market for B2B implementations - Keeps product pages cleaner and easier for buyers to use - Supports internal pricing, fulfillment, compliance, and AI-driven processes **Documentation:** ### Search Statistics & Google Analytics {% include badge.html type="feature" %} Spryker now provides native search statistics in the Back Office for ElasticSearch-based projects. Business users can analyze search behavior and identify zero-result searches to optimize discoverability and relevance. **Key capabilities:** - Adds Back Office views for top frequent searches and top zero-result searches - Supports time-based filtering for analytics review - Enables sorting, filtering, and CSV export for further analysis - Tracks search-related events through Google Analytics integration **Business benefits:** - Eliminates repeated custom search analytics implementations - Enables data-driven catalog and synonym optimization - Helps identify gaps that lead to zero-result searches - Supports better search relevance and conversion outcomes **Documentation:** ### Budget & Cost Centers EA {% include badge.html type="early-access" %} {% include badge.html type="feature" %} Budget and cost center management is now available in Early Access for procurement-driven B2B scenarios. The release introduces core controls for assigning spend to cost centers, validating budgets during checkout, and integrating budget rules with approval workflows. **Key capabilities:** - Manages cost centers and assigns buyers to them - Creates budgets with configurable enforcement rules such as block, warn, and require approval - Supports cost center selection during checkout - Validates available budget before order placement - Integrates budget-triggered flows with the existing Approval Process - Tracks budget consumption and restoration **Business benefits:** - Improves financial control and policy compliance - Reduces overspending risk in organizational purchasing - Increases transparency for departmental or project-based spend - Streamlines procurement workflows in one system **Documentation:** ### Basic shop theming {% include badge.html type="feature" %} Business users can now configure core branding elements directly in the Back Office without developer support. This makes it easier to prepare demos, launch storefronts faster, and align Storefront, Back Office, and Merchant Portal branding with company identity. **Key capabilities:** - Configures themes through the Back Office configuration experience - Supports global and store-specific theme management - Uploads and manages logos for Storefront, Back Office, and Merchant Portal - Configures core branding colors using standardized design system values - Applies changes without code changes or deployment **Business benefits:** - Reduces dependency on developers for basic branding updates - Accelerates demo preparation, POCs, and customer onboarding - Improves time-to-first-transaction - Increases perceived product maturity and self-service value **Documentation:** ### Back Office support for merchant product ownership Marketplace operators can now manage merchant-product ownership directly in the Back Office. This closes an important operational gap for marketplace models where merchant products are not maintained primarily through the Merchant Portal. **Key capabilities:** - Supports assigning and changing merchant ownership for products in the Back Office - Makes merchant assignment visible within product management workflows - Aligns Back Office product management more closely with marketplace needs **Business benefits:** - Improves operational efficiency for marketplace operators - Increases transparency and auditability of merchant assignments - Supports centralized and hybrid marketplace operating models - Reduces the need for custom implementations **Documentation:** ### Product import and export in the Back Office We introduced the first phase of product import and export capabilities in the Back Office to reduce dependency on developer-oriented CLI tools. Business users can now work with product catalog data through a more accessible workflow designed for operational and demo use cases. **Key capabilities:** - Enables Back Office-based product import and export for product-related data - Supports reusable jobs and executable runs for import and export workflows - Processes data asynchronously in batches for large files - Provides a business-user-friendly file handling approach for creating and updating products **Business benefits:** - Reduces developer bottlenecks for catalog onboarding and updates - Speeds up demo preparation and merchant onboarding - Supports staging-to-production catalog workflows - Improves self-service handling of product data operations **Documentation:** ### Add to cart from image We packaged and integrated the add-to-cart-from-image capability into the public demo setup. Buyers can use an image containing product identifiers and quantities to speed up quick order creation. **Key capabilities:** - Extracts product names or SKUs and quantities from uploaded images - Auto-fills the quick add-to-cart form based on extracted information - Uses Spryker AI Foundation for AI integration **Business benefits:** - Speeds up bulk and repeat ordering workflows - Reduces manual entry effort and ordering errors - Better reflects real-life B2B procurement behaviors in demos - Improves convenience for busy buyers working from unstructured inputs **Documentation:** ### Self-Service Portal demo data improvements {% include badge.html type="improvement" %} We updated the B2B Marketplace demo shop with more realistic Self-Service Portal sample data. The new data better reflects industry-focused scenarios and helps showcase portal capabilities in a more meaningful way. **Key capabilities:** - Adds industry-aligned assets to the demo data set - Includes related services and spare parts for assets - Expands inquiry scenarios for general and asset-related use cases - Populates services, files, models, and CMS-related content to avoid empty states **Business benefits:** - Makes demos more relevant to target industries and ICPs - Improves understanding of Self-Service Portal workflows - Reduces demo friction for sales, partners, and internal teams - Strengthens perceived value and product adoption potential **Documentation:** ### New Spryker Design System for Storefront We established the next phase of the Storefront design system to create a more consistent and scalable UI foundation. This includes both the token-based design foundation and a reusable composite component layer for common storefront patterns. **Key capabilities:** - Defines and structures design tokens for colors, spacing, typography, and related foundations - Aligns design and frontend engineering on a shared naming and implementation approach - Introduces reusable composite components such as cards, lists, tabs, menus, breadcrumbs, dialogs, tables, search bars, and filter panels - Standardizes common UI patterns across browsing, checkout, and account areas **Business benefits:** - Improves consistency and usability across the Storefront - Reduces duplicated UI implementations across teams - Speeds up frontend delivery and future UI evolution - Improves demo quality and overall product perception **Documentation:** ### Back Office design theme update We delivered the first phase of the Back Office theme modernization to improve consistency, responsiveness, and usability. This update creates a stronger visual foundation for future Back Office improvements while reducing UX debt from legacy styling. **Key capabilities:** - Improves visual hierarchy, spacing, and clarity across the Back Office - Introduces a more consistent component structure and page presentation - Improves responsiveness and usability of core layouts - Reduces reliance on fragmented default styling patterns **Business benefits:** - Improves trust and confidence in Back Office demos - Reduces friction in daily operational use - Creates a more scalable base for future Back Office enhancements - Lowers customization effort for common visual improvements **Documentation:** ## Efficient and Flexible Cloud Foundation ### 2026 March-April Cloud Security Improvements {% include badge.html type="feature" %} We delivered a set of security enhancements across Spryker Cloud infrastructure to strengthen access control, reduce credential exposure, improve auditability, and modernize the security posture of runtime services. These updates also prepare the platform for more standardized and scalable identity management. **Key capabilities:** - Improved scheduled maintenance for Jenkins with gradual patch rollouts and controlled maintenance windows - Hardened database security through tighter RDS access control, IAM-based authentication for human users, and improved auditability of RDS operations - Introduced a revamped PaaS role model with composable roles to support standardized access management and future SSO readiness - Restricted container access to EC2 instance metadata and prevented workloads from inheriting excessive EC2-level permissions - Documented and aligned a secure process for temporary root access to AWS member accounts with defined roles and responsibilities - Collected SSH/SFTP and deployment-version usage insights to support security analysis and patch-level visibility - Added compatibility handling for MariaDB 11.8 secure transport defaults - Started migration preparation and rollout patterns for Amazon Linux 2023 to address upcoming end-of-life timelines **Business benefits:** - Reduces the risk of privilege escalation and unauthorized access from running containers - Improves traceability and control for sensitive infrastructure and database operations - Establishes a more secure and scalable foundation for customer access management - Supports safer maintenance rollouts with less operational risk - Helps keep cloud environments aligned with supported and secure platform versions **Documentation:** ### TLS/Auth/SSO for Cloud services (prev. Single-Sign-On for Cloud Services) {% include badge.html type="feature" %} We advanced centralized authentication and access management for Spryker Cloud services, including rollout and production-readiness improvements for SSO-enabled access. This work also included IAM policy cleanup, IAM artifact audits, bastion hardening, and stronger guardrails for privileged access in customer PaaS accounts. **Key capabilities:** - Rolled out SSO-based access management for cloud services such as Jenkins and RabbitMQ - Added production-readiness and post-production rollout enhancements for SSO - Audited IAM roles and policies to identify cleanup and standardization opportunities - Prevented creation of unrestricted `*:*` IAM policies in customer PaaS accounts through stricter control boundaries - Hardened bastion hosts with modernized OS support, workload isolation, and enforced SSO/MFA for human access - Preserved SFTP integration access while deprecating direct SSH-based human access where applicable **Business benefits:** - Enables more secure and centralized user lifecycle management - Reduces manual effort and waiting times for onboarding and offboarding access requests - Lowers the risk of over-permissioned IAM configurations - Improves compliance through MFA-backed human access and clearer access boundaries **Documentation:** ### 2026Q1 Maintenance and service updates {% include badge.html type="feature" %} This release delivers maintenance and service updates across core cloud services and application tooling to keep Spryker Cloud environments secure, supported, and maintainable. It includes runtime service upgrades, application dependency updates, and groundwork for lower-downtime RabbitMQ upgrades. **Key capabilities:** - Updated critical cloud services, including Jenkins LTS and Nginx - Replaced Ubuntu-based service components with Amazon Linux where in scope - Upgraded application tooling with PHPUnit 12 and PHPStan 2.0 support - Prepared support for RabbitMQ 4.2 and rolled out RabbitMQ 4.1 updates - Implemented and validated a blue/green approach for RabbitMQ upgrades to reduce downtime and avoid message loss **Business benefits:** - Keeps cloud services on supported versions with better security and stability - Reduces technical debt and maintenance overhead - Improves developer efficiency through faster tooling and modern test support - Minimizes disruption during future RabbitMQ service upgrades **Documentation:** ### Cloud Observability // SMI: Logs forwarding to Dynatrace and others (Bring your own Monitoring) {% include badge.html type="feature" %} We added support for forwarding logs through SMI using OpenTelemetry-based integration so customers can correlate logs with traces in their monitoring platform of choice. This includes application logs, Jenkins job logs, RDS slow query logs, and application audit logs, along with metering and monitoring for log transfer. **Key capabilities:** - Export logs through SMI for use with Dynatrace and other compatible monitoring tools - Correlate log entries with traces using standard telemetry fields such as trace and span IDs - Forward application container logs, Jenkins job logs, RDS slow query logs, and application audit logs - Support configurable log verbosity to control emitted log volume - Added SMI metering and monitoring for log shipment usage and operational visibility **Business benefits:** - Helps engineering teams investigate issues faster by linking logs to traces - Enables log-based alerting in external APM and observability platforms - Improves flexibility for customers using their own monitoring stack - Supports transparent usage tracking for billing and service monitoring **Documentation:** ## Other ### Data import and queue processing performance {% include badge.html type="improvement" %} We improved long-running data processing flows to make imports and queue workers more transparent, stable, and resource-efficient. This release adds better progress visibility for data imports, reduces memory consumption in large import scenarios, improves queue worker throughput under load, and extends resource-aware queue processing support for Symfony Messenger. **Key capabilities:** - Added a progress bar for data import console commands to provide execution visibility. - Reduced memory consumption in large-volume data imports, including merchant price imports at scale. - Improved queue worker performance with dynamic waiting time adjustments under load. - Added support for limiting the number of parallel jobs to improve worker stability and reduce out-of-memory risks. - Enabled `ResourceAwareQueueWorker` compatibility with the Symfony Messenger adapter. **Business benefits:** - Improves observability for long-running import operations. - Supports larger import volumes with lower memory pressure. - Increases queue processing throughput and operational stability. - Gives teams more control over workload tuning in high-volume environments. **Documentation:** ### Back Office performance improvements {% include badge.html type="improvement" %} We improved several Back Office performance hotspots to reduce response times and lower resource consumption in data-heavy and permission-heavy environments. The updates cover ACL navigation checks, order page rendering, product-related lists, and widget rendering behavior. **Key capabilities:** - Optimized ACL-related access checks that impacted Back Office navigation rendering on every request. - Reduced unnecessary permission evaluation overhead, including on requests where navigation is not needed. - Improved performance of the order detail page for orders with many items. - Improved responsiveness of product-related Back Office lists in large catalogs. - Optimized widget rendering to reduce overall page overhead. **Business benefits:** - Speeds up the Back Office for users with restricted permissions. - Improves usability in large-scale merchant and enterprise environments. - Reduces page load times and infrastructure pressure for high-volume catalogs and order management. **Documentation:** ### AI configuration management for runtime updates {% include badge.html type="feature" %} AI provider configuration values can now be resolved from Configuration Management at runtime. This lets Back Office administrators update selected AI settings, such as model, API key, or system prompt, without requiring code changes or deployments. **Key capabilities:** - Added support for resolving AI configuration values using the `configuration::` prefix. - Enabled recursive runtime resolution for nested AI provider configuration values. - Added validation and clear exception handling for unresolved configuration references. - Supports managing AI-related configuration keys through Configuration Management. **Business benefits:** - Reduces dependency on deployments for AI configuration changes. - Gives Back Office administrators more flexibility to tune AI behavior. - Speeds up experimentation and operational adjustments for AI-powered features. **Documentation:** ### AI agent instruction file generator {% include badge.html type="feature" %} We introduced a new developer command to generate example agent context files for AI-assisted development workflows. The command helps standardize setup for teams using coding agents in their projects. **Key capabilities:** - Added the `ai-dev:generate-agents-file` command. - Generates example `AGENTS.md` or `CLAUDE.md` files for AI agent context. **Business benefits:** - Improves developer experience for teams working with AI coding agents. - Helps standardize project context setup for AI-assisted development. **Documentation:** ### Platform and security updates {% include badge.html type="improvement" %} We updated selected platform dependencies to improve long-term support, security, and maintainability. This includes upgrading frontend tooling to Node.js 24 LTS and updating `symfony/http-foundation` in affected application templates to address known vulnerabilities. **Key capabilities:** - Upgraded frontend tooling baseline to Node.js 24 LTS. - Updated `symfony/http-foundation` to a secure supported version in affected application repositories. **Business benefits:** - Improves platform security and dependency health. - Keeps development tooling on a supported long-term support version. - Helps reduce maintenance and compliance risks. **Documentation:** ### Logging improvements {% include badge.html type="improvement" %} We added support for non-buffered log streaming. This improves log handling in scenarios where immediate log output is preferred. **Key capabilities:** - Added support for streaming logs without buffering. **Business benefits:** - Improves log visibility for real-time monitoring and troubleshooting. - Helps teams react faster during diagnostics and operational review. **Documentation:** ### Demo analytics enablement {% include badge.html type="improvement" %} We enabled Amazon QuickSight support in the master-demo setup to improve demo readiness for analytics scenarios. This ensures demo environments can display analytics content for Back Office users. **Key capabilities:** - Enabled Amazon QuickSight integration in the master-demo branch. - Added analytics asset bundle setup for demo Back Office usage. **Business benefits:** - Improves demo quality for analytics-related use cases. - Makes it easier to showcase business intelligence capabilities in demo environments. **Documentation:**

Install Search by Image

Fri, 10 Apr 2026 12:25:48 +0000

Search by Image lets storefront customers upload a photo to find products. AI analyzes the image, identifies a search term, and redirects the customer to the search results page or the first matching product detail page. This document describes how to install the Search by Image feature. ## Install the feature core Follow the steps in the following sections to install the Search by Image feature core. ### Prerequisites Install the required features: | NAME | VERSION | INSTALLATION GUIDE | |------|---------|-------------------| | AI Commerce | {{page.release_tag}} | [Install AI Commerce](/docs/dg/dev/ai/ai-commerce/install-ai-commerce.html) | | Configuration Management | {{page.release_tag}} | [Install the Configuration Management feature](/docs/dg/dev/integrate-and-configure/integrate-confguration-feature.html) | | Catalog | {{page.release_tag}} | | ### 1) Add translations Append the glossary according to your configuration: `data/import/common/common/glossary.csv` ```csv ai_commerce.search_by_image.form.image.label,Search by image,en_US ai_commerce.search_by_image.form.image.label,Bildersuche,de_DE ai_commerce.search_by_image.form.image.error.mime_type,"This image type is not supported. Please upload a JPEG, PNG, WebP, or GIF.",en_US ai_commerce.search_by_image.form.image.error.mime_type,"Dieses Bildformat wird nicht unterstützt. Bitte laden Sie ein JPEG, PNG, WebP oder GIF hoch.",de_DE ai_commerce.search_by_image.error.no_image_provided,Please select an image to search.,en_US ai_commerce.search_by_image.error.no_image_provided,Bitte wählen Sie ein Bild für die Suche aus.,de_DE ai_commerce.search_by_image.error.search_failed,Search by Image failed. Please try again.,en_US ai_commerce.search_by_image.error.search_failed,Bildsuche fehlgeschlagen. Bitte versuchen Sie es erneut.,de_DE ai_commerce.search_by_image.error.unavailable,Search by Image is currently unavailable. Please try again later.,en_US ai_commerce.search_by_image.error.unavailable,Bildsuche ist derzeit nicht verfügbar. Bitte versuchen Sie es später erneut.,de_DE ai_commerce.search_by_image.error.disabled,Search by Image is currently disabled.,en_US ai_commerce.search_by_image.error.disabled,Bildsuche ist derzeit deaktiviert.,de_DE ai_commerce.search_by_image.search,Search,en_US ai_commerce.search_by_image.search,Suchen,de_DE ai_commerce.search_by_image.upload_image,Upload image,en_US ai_commerce.search_by_image.upload_image,Bild hochladen,de_DE ai_commerce.search_by_image.upload_image_to_find_products,Upload an image to find similar products.,en_US ai_commerce.search_by_image.upload_image_to_find_products,"Laden Sie ein Bild hoch, um ähnliche Produkte zu finden.",de_DE ai_commerce.error.file.size.invalid,"File size is too big.",en_US ai_commerce.error.file.size.invalid,"Ungültige Gesamtdateigröße.",de_DE ai_commerce.search_by_image.image.description,"Max up to %size% MB. Allowed file formats %format%",en_US ai_commerce.search_by_image.image.description,"Maximal bis zu %size%. Erlaubte Dateiformate: %format%",de_DE ``` Import the data: ```bash console data:import glossary ``` {% info_block warningBox "Verification" %} Make sure that the configured data has been added to the `spy_glossary_key` and `spy_glossary_translation` tables. {% endinfo_block %} ### 2) Set up transfer objects Generate transfer changes: ```bash console transfer:generate ``` {% info_block warningBox "Verification" %} Make sure the following transfers have been created: | TRANSFER | TYPE | EVENT | PATH | |----------|------|-------|------| | SearchByImageRequest | class | created | src/Generated/Shared/Transfer/SearchByImageRequestTransfer.php | | SearchByImageResponse | class | created | src/Generated/Shared/Transfer/SearchByImageResponseTransfer.php | | SearchByImagePromptResponse | class | created | src/Generated/Shared/Transfer/SearchByImagePromptResponseTransfer.php | {% endinfo_block %} ### 3) Register plugins Register the following plugins: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | |--------|---------------|---------------|-----------| | SearchByImageRouteProviderPlugin | Registers the routes required for the Search by Image request handling. | | SprykerFeature\Yves\AiCommerce\SearchByImage\Plugin\Router | | ImageSearchAiWidget | Renders the camera icon and image upload dialog next to the search input. | | SprykerFeature\Yves\AiCommerce\SearchByImage\Widget | **src/Pyz/Yves/Router/RouterDependencyProvider.php** ```php */ protected function getRouteProvider(): array { return [ // ... new SearchByImageRouteProviderPlugin(), ]; } } ``` **src/Pyz/Yves/ShopApplication/ShopApplicationDependencyProvider.php** ```php */ protected function getGlobalWidgets(): array { return [ // ... ImageSearchAiWidget::class, ]; } } ``` {% info_block warningBox "Verification" %} Make sure that the `ImageSearchAiWidget` is registered and the camera icon is rendered next to the search bar when the feature is enabled. {% endinfo_block %} ### 4) Configure AiFoundation for Search by Image For a base AiFoundation setup, see [Configure AiFoundation](/docs/dg/dev/ai/ai-commerce/install-ai-commerce.html#2-configure-aifoundation). Using a dedicated AI configuration for Search by Image is recommended because each named configuration is tracked separately in the AiFoundation audit log. This lets you isolate and review all AI calls made by the image search flow independently from other AI features in your project. To use a dedicated AI model configuration for Search by Image instead of the default one, follow these steps: 1. In `config/Shared/config_ai.php`, add a named configuration entry using `AiCommerceConstants::SEARCH_BY_IMAGE_CONFIGURATION_NAME` as the key: ```php $config[\Spryker\Shared\AiFoundation\AiFoundationConstants::AI_CONFIGURATIONS][\SprykerFeature\Shared\AiCommerce\AiCommerceConstants::SEARCH_BY_IMAGE_CONFIGURATION_NAME] = $openAiConfiguration; ``` 2. Return the configuration name from `AiCommerceConfig`: **src/Pyz/Yves/AiCommerce/AiCommerceConfig.php** ```php > Search by Image > Search by Image**. 2. Turn on **Enable Search by Image**. 3. Set **Redirect type** to the desired behavior: - **Search results** — redirects the customer to the catalog search results page for the identified search term. - **First result product detail page** — redirects the customer directly to the product detail page of the first matching result. 4. Click **Save**. ![Search by Image configuration](https://spryker.s3.eu-central-1.amazonaws.com/docs/dg/dev/ai-commerce/search-by-image-config.png) {% info_block warningBox "Verification" %} On the Storefront, make sure the camera icon is visible next to the search bar. {% endinfo_block %} ## Integrate the feature frontend {% info_block infoBox "Note" %} The Twig template changes in this section reflect the current implementation. These templates may be updated in future releases. Review the latest demo shop templates before applying them at the project level. {% endinfo_block %} ### 1) Add icon sprites {% info_block infoBox "Info" %} Do this step only if you have overridden `icon-sprite.twig` in the `ShopUi` module at the project level. If you have not overridden this template, skip to [2) Update the search form template](#2-update-the-search-form-template). {% endinfo_block %} In `src/Pyz/Yves/ShopUi/Theme/default/components/atoms/icon-sprite/icon-sprite.twig`, add the following SVG symbol definitions inside the `{% raw %}{% block sprite %}{% endraw %}` block: ```twig {% raw %} Upload Image Visual Search {% endraw %} ``` ### 2) Update the search form template {% info_block infoBox "Info" %} Do this step only if you have overridden `search-form.twig` in the `ShopUi` module at the project level. If you have not overridden this template, skip to [3) Update the header template](#3-update-the-header-template). {% endinfo_block %} In `src/Pyz/Yves/ShopUi/Theme/default/components/molecules/search-form/search-form.twig`, add the `ImageSearchAiWidget` inside the search input area. Place it after the `` element and before the submit button: ```twig {% raw %} {% if data.byImage and widgetGlobalExists('ImageSearchAiWidget') %} {% widget 'ImageSearchAiWidget' with { data: { dataSearchId: attributes['data-search-id'], }, } only %}{% endwidget %} {% endif %} {% endraw %} ``` ### 3) Update the header template {% info_block infoBox "Info" %} Do this step only if you have overridden `header.twig` in the `ShopUi` module at the project level. If you have not overridden this template, skip to [6) Apply the frontend changes](#6-apply-the-frontend-changes). {% endinfo_block %} In `src/Pyz/Yves/ShopUi/Theme/default/components/organisms/header/header.twig`, pass `byImage: true` in the `data` block when including the search form molecule: ```twig {% raw %} {% include molecule('search-form', 'SearchPage') with { ... data: { byImage: true, }, } only %} {% endraw %} ``` ### 4) Add the project-level component files Create the following project-level files to register and style the `search-by-image` component. **src/Pyz/Yves/AiCommerce/Theme/default/components/molecules/search-by-image/index.ts** ```ts import './search-by-image'; import register from 'ShopUi/app/registry'; export default register( 'search-by-image', () => import( /* webpackMode: "lazy" */ /* webpackChunkName: "search-by-image" */ 'AiCommerce/components/molecules/search-by-image/search-by-image' ), ); ``` **src/Pyz/Yves/AiCommerce/Theme/default/components/molecules/search-by-image/search-by-image.scss** ```scss @include ai-commerce-search-by-image { position: absolute; right: rem(40); top: 50%; translate: 0 -50%; z-index: $setting-zi-search-suggestions + 2; @include helper-breakpoint(lg) { right: rem(10); } &__popup-trigger { @include helper-effect-transition(rotate); border: none; width: rem(32); height: rem(32); background: none; cursor: pointer; display: flex; align-items: center; justify-content: center; &:hover { rotate: 90deg; } } } ``` **src/Pyz/Yves/AiCommerce/Theme/default/components/molecules/search-by-image/search-by-image.twig** ```twig {% raw %} {% extends molecule('search-by-image', '@SprykerFeature:AiCommerce') %} {% block triggerFileButton %} {% set triggerButtonClassname = "search-by-image__popup-trigger search-by-image__popup-trigger--#{data.dataSearchId}" %} {{ parent() }} {% endblock %} {% block triggerPhotoButton %} {% set triggerButtonClassname = "search-by-image__popup-trigger search-by-image__popup-trigger--#{data.dataSearchId}" %} {{ parent() }} {% endblock %} {% endraw %} ``` ### 5) Update TypeScript configuration In `tsconfig.yves.json`, add the `AiCommerce/*` path alias to the `compilerOptions.paths` section: ```json "AiCommerce/*": ["./vendor/spryker-feature/ai-commerce/src/SprykerFeature/Yves/AiCommerce/Theme/default/*"] ``` {% info_block warningBox "Verification" %} Make sure the `AiCommerce/*` entry is added alongside the other module path aliases in the `paths` object. {% endinfo_block %} ### 6) Apply the frontend changes Apply the frontend changes: ```bash docker/sdk cli npm install docker/sdk cli console frontend:project:install-dependencies docker/sdk cli console frontend:yves:build ``` {% info_block warningBox "Verification" %} On the Storefront, make sure the camera icon is displayed next to the search bar. Click the icon, upload an image, and verify that you are redirected to either the search results page or the matching product detail page, depending on the configured redirect type. {% endinfo_block %}

Search by Image

Fri, 10 Apr 2026 12:20:13 +0000

Search by Image lets customers find products by uploading a photo. A camera icon next to the search input opens an image upload dialog. After the image is uploaded, AI analyzes it, identifies a relevant search term, and redirects the customer — either to the catalog search results page or directly to the first matching product detail page (PDP). **Use case:** A customer sees a product they want to buy but does not know what it is called. They photograph the product and upload the image using the Search by Image button. The system identifies the product and takes the customer directly to the matching product or a list of similar results. Accepted file formats: JPEG, PNG, WebP, and GIF. ## Use Search by Image on the Storefront 1. On any page with the search bar, click the camera icon next to the search input. ![Search by Image button](https://spryker.s3.eu-central-1.amazonaws.com/docs/dg/dev/ai-commerce/search-by-image-button.png) 2. In the dialog that opens, click **Upload image** and select a photo from your device or take a new one using your smartphone camera. ![Search by Image upload dialog](https://spryker.s3.eu-central-1.amazonaws.com/docs/dg/dev/ai-commerce/search-by-image-upload.png) 3. The system analyzes the image and redirects you to the search results or the matching product page. ![Search by Image results](https://spryker.s3.eu-central-1.amazonaws.com/docs/dg/dev/ai-commerce/search-by-image-results.png) ## Enable Search by Image To enable the feature, in the Back Office, go to **AI Commerce > Search by Image > Search by Image** and turn on **Enable Search by Image**. ![Search by Image configuration](https://spryker.s3.eu-central-1.amazonaws.com/docs/dg/dev/ai-commerce/search-by-image-config.png) ## Configure the redirect behavior After enabling Search by Image, you can control where customers land after a successful image search. In the same settings group, set **Redirect type** to one of the following options: | OPTION | DESCRIPTION | |--------|-------------| | Search results | Redirects the customer to the catalog search results page for the identified search term. This is the default. | | First result product detail page | Redirects the customer directly to the PDP of the first matching product. | ## Developer resources | RESOURCE | DESCRIPTION | |----------|-------------| | [Search by Image](/docs/dg/dev/ai/ai-commerce/search-by-image/search-by-image.html) | Technical overview: architecture, configuration options, and AiFoundation integration. | | [Install Search by Image](/docs/dg/dev/ai/ai-commerce/search-by-image/install-search-by-image.html) | Step-by-step installation guide. |

Search by Image

Fri, 10 Apr 2026 12:20:13 +0000

Search by Image lets storefront customers find products by uploading a photo. AI analyzes the image, identifies a search term, and redirects the customer to either a catalog search results page or the first matching product detail page (PDP). For the business overview and storefront usage, see [Search by Image](/docs/pbc/all/ai-commerce/latest/search-by-image.html). ## Architecture The feature is built on the `AiFoundation` abstraction layer, which decouples the image analysis logic from any specific AI provider. The AI model and provider are configured per named configuration entry, so you can swap or reconfigure them without changing application code. The Yves-side widget `ImageSearchAiWidget` renders the camera icon and the image upload dialog next to the search input. Routing is handled by `SearchByImageRouteProviderPlugin`. After the AI returns a search term, the redirect target is determined by the Back Office configuration — either the catalog search results page or the PDP of the first matching result. ## How it works 1. The customer clicks the camera icon next to the search bar. 2. The customer uploads an image. 3. The system validates the file format and size. 4. The image is encoded and sent to the AI model via the `AiFoundation` abstraction layer. 5. The AI returns a search term derived from the image content. 6. Depending on the configured redirect type, the customer is sent to: - The catalog search results page for the identified search term, or - The PDP of the first matching product. ## Configuration The following options can be configured at the project level in `AiCommerceConfig`: | CONFIGURATION | DEFAULT | DESCRIPTION | |---------------|---------|-------------| | `isSearchByImageEnabled()` | `false` | Enables or disables the feature. Controlled via the Back Office. | | `getSearchByImageSupportedMimeTypes()` | `image/jpeg`, `image/png`, `image/webp`, `image/gif` | Allowed upload MIME types. | | `getSearchByImageMaxFileSizeInBytes()` | Defined in `AiCommerceConfig` | Maximum upload file size in bytes. | | `getSearchByImageAiConfigurationName()` | `null` | Named AI model configuration identifier used to look up the provider config from `AiFoundation`. When `null`, the default configuration is used. | | `getSearchByImageRedirectType()` | `search_results` | Controls the redirect target after a successful image search. Controlled via the Back Office. | ## Install [Install Search by Image](/docs/dg/dev/ai/ai-commerce/search-by-image/install-search-by-image.html)

AI Commerce

Fri, 10 Apr 2026 12:20:13 +0000

AI Commerce brings AI-powered capabilities to your Spryker storefront, reducing manual effort for buyers and accelerating commerce workflows. Features are built on the AiFoundation abstraction layer, so the underlying AI model can be swapped or configured per feature without changing application code.

Features

FEATURE	DESCRIPTION
Visual Add to Cart	Lets buyers upload a product image on the Quick Order page. AI recognizes the products in the image and pre-fills the order form with matching SKUs and quantities — enabling rapid bulk ordering without manual entry.
Back Office Assistant	An AI-powered chat widget embedded in the Back Office. Admin users can ask natural language questions to navigate the Back Office, diagnose order issues, and create or update discounts.
Search by Image	Lets customers upload a photo to search for products. AI analyzes the image, identifies a search term, and redirects to search results or the first matching product page.

Who benefits

ROLE	BENEFIT
B2B buyers	Faster reordering from photos of shelves, product lists, or packaging. Find products by uploading a photo instead of searching by name.
Store operators	Reduced support requests caused by manual order entry errors. Faster Back Office workflows through conversational AI assistance.
Developers	AI provider-agnostic integration — swap or configure models per feature via configuration.

Set up DNS

Thu, 09 Apr 2026 12:35:13 +0000

To make your application accessible through your own domain, configure DNS records that point your domain to the Spryker-managed endpoint. In most cases, this means adding a `CNAME` record in your DNS management for the domain you want to use. Spryker provides the target values as part of the setup process. ## Before you start Before requesting DNS setup: - Make sure the endpoint you want to use is final. - Make sure the endpoint has been tested and approved internally. - Make sure the `deploy.yml` file you provide to Spryker is the same file that will later be used for the Normal or Destructive deployment pipeline. - Be aware that DNS setup is not immediate and can take up to a week to complete. {% info_block infoBox "Info" %} This process can take up to a full week because it includes both DNS propagation time and Spryker infrastructure work. To avoid rework, submit only final endpoint selections. {% endinfo_block %} ## DNS setup process The DNS setup usually follows these steps: 1. Add the endpoint you want to use to the appropriate `deploy.yml` file. For example, add a new endpoint under the desired application in your `deploy.yml`: ```yaml groups: EU: region: EU applications: yves: application: yves endpoints: www.example.com: store: DE ``` 2. Create a support case and provide the `deploy.yml` file that contains the endpoint configuration. For example: "We have added the endpoint `www.example.com` to our `deploy.yml` and would like to set up DNS for it." 3. Ensure that this is the same `deploy.yml` file that will later be used for the Normal or Destructive deployment pipeline. 4. Spryker prepares the endpoint configuration and sends you the DNS records required for TLS verification. For example, you may receive a `CNAME` record like `_acme-challenge.www.example.com` pointing to a validation target. 5. Add the provided TLS verification records in your DNS management. 6. After the records are in place and have propagated, notify Spryker Support. 7. Spryker completes the infrastructure configuration. 8. Spryker sends you the final DNS target values, usually `CNAME` records, that must be added in your DNS management. For example: `www.example.com CNAME xxx.elb.amazonaws.com`. Root domains are treated differently — see [Root domain configuration](#root-domain-configuration). 9. After the DNS records are added and propagated, your application becomes accessible through the new domain. 10. Trigger the Normal or Destructive deployment pipeline using the same `deploy.yml` file that was provided to Spryker. ## Important: Configuration changes are staged DNS-related endpoint changes are prepared first, but they do not become active immediately. After Spryker prepares the new endpoint configuration, the change remains staged until a deployment pipeline is triggered. This is especially important for infrastructure components that support only one active endpoint at a time. ## Critical constraint for Scheduler and Queue endpoints The following services support only **one active endpoint configuration at a time**: - Scheduler (`Jenkins`) - Queue (`RabbitMQ`) When a new domain endpoint is configured for either of these services, the previous endpoint is replaced. It is not kept in parallel. Dual-domain operation is **not supported** for these components. {% info_block warningBox "Warning" %} If a deployment is triggered before the required DNS records are fully added and propagated, `Jenkins` and `RabbitMQ` can become unreachable because their previous endpoints will already have been replaced. {% endinfo_block %} ## Safe activation sequence Do **not** trigger deployment immediately after receiving the DNS records from Spryker. Before triggering a Normal or Destructive deployment pipeline: 1. Confirm that the pipeline will use the same `deploy.yml` file that was provided to Spryker for DNS setup. 2. Add all required TLS verification records. 3. Add all required final DNS records at your registrar or DNS provider. 4. Verify that DNS propagation is complete. 5. Notify Spryker Support that DNS setup is complete. 6. Wait for confirmation from Spryker that the infrastructure-side setup is finished. 7. Only then trigger the deployment pipeline. ## Recommended pre-deployment checklist Before triggering deployment for a new domain or domain migration, confirm all of the following: - The `deploy.yml` file used for deployment is the same one that was provided to Spryker for DNS setup. - TLS verification records were added. - Final DNS records were added at the registrar or DNS provider. - DNS propagation was verified, for example with `dig` or another DNS checker. - Spryker Support was notified that DNS setup is complete. - Spryker confirmed that the infrastructure configuration is complete. Only after all items are completed should deployment be triggered. ## Root domain configuration If you want to use a root domain such as `example.com`, use an `A` record instead of a `CNAME` record. In this case, contact Spryker so the team can provide the correct IP address to use. Do **not** use the load balancer IP addresses directly as your `A` record target, because those IP addresses are subject to rotation. ## NS record delegation Spryker does not normally support full DNS delegation. Do **not** change your domain's `NS` records to delegate the full DNS zone to Spryker unless explicitly instructed by Spryker. ## Troubleshooting and practical notes ### Adding the endpoint to deploy.yml does not make it active Adding the endpoint in code only starts the setup flow. The endpoint becomes active only after the DNS setup is complete and deployment is triggered. ### The deploy.yml file must match the one shared for DNS setup The `deploy.yml` file used in the Normal or Destructive deployment pipeline must match the one provided to Spryker during the DNS setup process. Otherwise, the deployed configuration may not match the DNS configuration prepared by Spryker. ### Old and new domains cannot be active at the same time for Jenkins or RabbitMQ These services support only one active endpoint configuration at a time. ### Biggest risk: premature deployment or mismatched deploy.yml The main risk is triggering deployment too early or using a different `deploy.yml` file than the one shared with Spryker. If DNS records are not fully in place and propagated, or if the deployed configuration does not match the prepared DNS setup, `Jenkins` and `RabbitMQ` can become unavailable. ### Verifying DNS propagation You can verify propagation with tools such as `dig` or another public DNS checker. Check that the records returned publicly match the values provided by Spryker.

Install the Basic Shop Theme feature

Tue, 07 Apr 2026 08:04:11 +0000

This document describes how to install the Basic Shop Theme feature. The feature lets Business Admins configure logos, theme colors, and custom CSS for the Storefront, Back Office, and Merchant Portal directly from the Back Office. ## Prerequisites Before installing this feature, install and configure the following: | NAME | VERSION | INTEGRATION GUIDE | |------|---------|-------------------| | Configuration Management feature | ^0.1.0 | [Install the Configuration Management feature](/docs/dg/dev/integrate-and-configure/integrate-confguration-feature.html) | | Spryker Core | ^3.82 | — | ## Install feature core ### 1) Install the required modules Install the required modules using Composer: ```bash composer require spryker/gui:"^3.0.0" spryker/zed-ui:"^2.0.0" spryker-shop/shop-ui:"^1.0.0" symfony/html-sanitizer:"^7.4" --update-with-dependencies ``` {% info_block warningBox "Verification" %} Make sure the following modules have been installed: | MODULE | EXPECTED DIRECTORY | |--------|-------------------| | Gui | vendor/spryker/gui | | ZedUi | vendor/spryker/zed-ui | | ShopUi | vendor/spryker-shop/shop-ui | | symfony/html-sanitizer | vendor/symfony/html-sanitizer | {% endinfo_block %} ### 2) Sync the theme configuration schema Run the configuration sync command to register the theme settings in the Back Office: ```bash console configuration:sync ``` {% info_block warningBox "Verification" %} 1. Log in to the Back Office. 2. Navigate to **Configuration**. 3. Verify that the **Theme** feature appears in the sidebar with four tabs: **Storefront**, **Back Office**, **Merchant Portal**, and **Logos**. {% endinfo_block %} ### 3) Set up behavior The `configurationValue()` and `configurationValues()` Twig functions are made available by existing plugins that are already registered in a standard Spryker installation: - **Storefront (Yves)**: `ShopUiTwigExtension` - **Back Office and Merchant Portal (Zed)**: `\Spryker\Zed\Twig\Communication\Plugin\Application\TwigApplicationPlugin` No additional Twig plugin registration is required. #### 3.1) Register ACL plugins for Merchant Portal Register the ACL entity configuration and rule expander plugins so that Merchant Portal users can read theme configuration values through the ACL layer: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | |--------|---------------|---------------|-----------| | ConfigurationValueAclEntityConfigurationExpanderPlugin | Expands the ACL entity configuration with `ConfigurationValue` entity rules for Merchant Portal access. | None | Spryker\Zed\Configuration\Communication\Plugin\AclMerchantPortal | | ConfigurationValueMerchantAclEntityRuleExpanderPlugin | Expands the Merchant ACL entity rule set to allow Merchant Portal users to read published configuration values. | None | Spryker\Zed\Configuration\Communication\Plugin\AclMerchantPortal | **src/Pyz/Zed/AclMerchantPortal/AclMerchantPortalDependencyProvider.php** Add the import statements: ```php use Spryker\Zed\Configuration\Communication\Plugin\AclMerchantPortal\ConfigurationValueAclEntityConfigurationExpanderPlugin; use Spryker\Zed\Configuration\Communication\Plugin\AclMerchantPortal\ConfigurationValueMerchantAclEntityRuleExpanderPlugin; ``` Register the plugins in the respective methods: ```php protected function getAclEntityConfigurationExpanderPlugins(): array { return [ // ... new ConfigurationValueAclEntityConfigurationExpanderPlugin(), ]; } protected function getMerchantAclEntityRuleExpanderPlugins(): array { return [ // ... new ConfigurationValueMerchantAclEntityRuleExpanderPlugin(), ]; } ``` {% info_block warningBox "Verification" %} Log in to the Merchant Portal and navigate to any page. Verify there are no ACL-related errors in the application log. {% endinfo_block %} ### 4) Configure media filesystems The logo upload feature requires three Flysystem filesystem services: one per application context. Configure them in your shared config and provide local overrides for development and CI environments. #### 4.1) Add filesystem services to the shared config Add the three media filesystem services to `config/Shared/config_default.php`. In production, they read from S3 using the `SPRYKER_S3_PUBLIC_ASSETS_*` environment variables. **config/Shared/config_default.php** Add the three media filesystem entries inside the existing `$config[FileSystemConstants::FILESYSTEM_SERVICE]` array: ```php $config[FileSystemConstants::FILESYSTEM_SERVICE] = [ // ... existing entries ... 'backoffice-media' => [ 'sprykerAdapterClass' => Aws3v3FilesystemBuilderPlugin::class, 'key' => getenv('SPRYKER_S3_PUBLIC_ASSETS_KEY') ?: '', 'bucket' => getenv('SPRYKER_S3_PUBLIC_ASSETS_BUCKET') ?: '', 'secret' => getenv('SPRYKER_S3_PUBLIC_ASSETS_SECRET') ?: '', 'root' => '/backoffice-media', 'path' => '/', 'version' => 'latest', 'region' => getenv('AWS_REGION'), ], 'storefront-media' => [ 'sprykerAdapterClass' => Aws3v3FilesystemBuilderPlugin::class, 'key' => getenv('SPRYKER_S3_PUBLIC_ASSETS_KEY') ?: '', 'bucket' => getenv('SPRYKER_S3_PUBLIC_ASSETS_BUCKET') ?: '', 'secret' => getenv('SPRYKER_S3_PUBLIC_ASSETS_SECRET') ?: '', 'root' => '/storefront-media', 'path' => '', 'version' => 'latest', 'region' => getenv('AWS_REGION'), ], 'merchant-portal-media' => [ 'sprykerAdapterClass' => Aws3v3FilesystemBuilderPlugin::class, 'key' => getenv('SPRYKER_S3_PUBLIC_ASSETS_KEY') ?: '', 'bucket' => getenv('SPRYKER_S3_PUBLIC_ASSETS_BUCKET') ?: '', 'secret' => getenv('SPRYKER_S3_PUBLIC_ASSETS_SECRET') ?: '', 'root' => '/merchant-portal-media', 'path' => '', 'version' => 'latest', 'region' => getenv('AWS_REGION'), ], ]; ``` #### 4.2) Add local filesystem fallback for development In the development environment, override the three filesystem services with a local adapter when the S3 bucket is not configured. This stores uploaded files under `public/Yves/assets/static/images` and serves them via the Yves assets path. **config/Shared/config_default-docker.dev.php** Add the import statement: ```php use Spryker\Shared\Flysystem\FlysystemConstants; ``` Add the following block in the filesystem section: ```php if (!getenv('SPRYKER_S3_PUBLIC_ASSETS_BUCKET')) { $publicUrl = sprintf( '%s%s', $config[ApplicationConstants::BASE_URL_YVES], '/assets/static/images', ); $localMediaFilesystemConfig = [ 'sprykerAdapterClass' => LocalFilesystemBuilderPlugin::class, 'root' => APPLICATION_ROOT_DIR . '/public/Yves/assets/static/images', 'path' => '', ]; $config[FileSystemConstants::FILESYSTEM_SERVICE]['backoffice-media'] = $localMediaFilesystemConfig; $config[FileSystemConstants::FILESYSTEM_SERVICE]['storefront-media'] = $localMediaFilesystemConfig; $config[FileSystemConstants::FILESYSTEM_SERVICE]['merchant-portal-media'] = $localMediaFilesystemConfig; $config[FlysystemConstants::FLYSYSTEM_OPTIONS] = [ 'public_url' => $publicUrl, ]; } ``` #### 4.3) Add local filesystem fallback for CI **config/Shared/config_default-docker.ci.php** Add the import statements: ```php use Spryker\Shared\Application\ApplicationConstants; use Spryker\Shared\Flysystem\FlysystemConstants; ``` Add the `$localMediaFilesystemConfig` variable before the `$config[FileSystemConstants::FILESYSTEM_SERVICE]` array, and add the three services as entries inside that array. After the array, add the public URL config: ```php $localMediaFilesystemConfig = [ 'sprykerAdapterClass' => LocalFilesystemBuilderPlugin::class, 'root' => APPLICATION_ROOT_DIR . '/public/Yves/assets/static/images', 'path' => '', ]; $config[FileSystemConstants::FILESYSTEM_SERVICE] = [ // ... existing entries ... 'backoffice-media' => $localMediaFilesystemConfig, 'storefront-media' => $localMediaFilesystemConfig, 'merchant-portal-media' => $localMediaFilesystemConfig, ]; $publicUrl = sprintf( '%s%s', $config[ApplicationConstants::BASE_URL_YVES], '/assets/static/images', ); $config[FlysystemConstants::FLYSYSTEM_OPTIONS] = [ 'public_url' => $publicUrl, ]; ``` {% info_block warningBox "Verification" %} 1. Log in to the Back Office. 2. Navigate to **Configuration > Theme > Logos**. 3. Upload a logo image using the file upload widget. 4. Verify the uploaded file is accessible at the public URL shown after upload. {% endinfo_block %} ### 5) Clear caches Clear the Twig cache and application cache to apply the new Twig functions: ```bash console twig:cache:warmer console cache:clear ``` ## Configure the feature After installing the feature, configure branding settings in the Back Office: 1. Log in to the Back Office. 2. Go to **Configuration > Theme**. 3. Select the tab for the context you want to configure: **Storefront**, **Back Office**, **Merchant Portal**, or **Logos**. 4. Enter the desired values and click **Save**. Changes to Storefront settings are published to key-value storage automatically. Back Office and Merchant Portal settings take effect on the next page load. ### Logo upload fields Logo settings support direct file upload from the Back Office. Uploaded files are stored via the corresponding Flysystem media filesystem service (`storefront-media`, `backoffice-media`, `merchant-portal-media`) and served from the configured `public_url`. | Context | Setting | Recommended size | Supported formats | Filesystem service | |---------|---------|-----------------|-------------------|--------------------| | Storefront | Storefront Logo | 186×50 px | GIF, PNG, JPEG, BMP, WebP, SVG | `storefront-media` | | Back Office | Back Office Logo | 186×50 px | GIF, PNG, JPEG, BMP, WebP, SVG | `backoffice-media` | | Merchant Portal | Merchant Portal Logo | 186×50 px | GIF, PNG, JPEG, BMP, WebP, SVG | `merchant-portal-media` | In production, configure the `SPRYKER_S3_PUBLIC_ASSETS_BUCKET`, `SPRYKER_S3_PUBLIC_ASSETS_KEY`, `SPRYKER_S3_PUBLIC_ASSETS_SECRET`, and `AWS_REGION` environment variables to point to an S3 bucket (or compatible object storage). In development and CI, files are stored locally at `public/Yves/assets/static/images`. ### Store-level overrides To configure a per-store override: 1. In the scope selector at the top of the Configuration page, switch from **Default** to the target store (for example, **DE**). 2. Adjust the setting value. 3. Click **Save**. Stores without a store-level value inherit the global (Default) value. ## Theme configuration key reference The following theme settings are registered by the feature's YAML schema. Use their compound keys in `configurationValue()` Twig calls or via `getModuleConfig()` in a module Config class. | Compound Key | Context | Type | Default | |-------------|---------|------|---------| | `theme:storefront:colors:background_brand_primary` | Storefront | color | `#00bebe` | | `theme:storefront:colors:background_brand_subtle` | Storefront | color | `#eb553c` | | `theme:storefront:custom_css:yves_custom_css` | Storefront | text | (empty) | | `theme:logos:logos:yves_logo_url` | Storefront | file | (empty) | | `theme:backoffice:colors:bo_main_color` | Back Office | color | `#1ebea0` | | `theme:backoffice:colors:bo_sidenav_color` | Back Office | color | `#23303c` | | `theme:backoffice:colors:bo_sidenav_text_color` | Back Office | color | `#e4e4e4` | | `theme:logos:logos:backoffice_logo_url` | Back Office | file | (empty) | | `theme:merchant_portal:colors:spy_primary_color` | Merchant Portal | color | `#1ebea0` | | `theme:logos:logos:merchant_portal_logo` | Merchant Portal | file | (empty) | ### Twig usage examples Inject a theme color as a CSS custom property in a Back Office layout: {% raw %} ```twig ``` {% endraw %} Read multiple values at once: {% raw %} ```twig {% set themeValues = configurationValues([ 'theme:backoffice:colors:bo_main_color', 'theme:logos:logos:backoffice_logo_url', ]) %} ``` {% endraw %}

Configuration Management feature

Tue, 07 Apr 2026 08:04:11 +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.
    order: 0                             # Optional. Sort order (lower = first).
    enabled: true                        # Optional. Default: true.
    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.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, feature and all children are hidden.
`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.
    order: 0                             # Optional. Sort order (lower = first).
    enabled: true                        # Optional. Default: true.
    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	Icon class (for example `settings`, `cable`, `trending_up`).
`description`	string	No	`null`	max 1000 chars	Tab description text.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, tab and all children are hidden.
`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.
    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.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, group and all settings are hidden.
`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.
    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.
    secret: false                        # Optional. Default: false.
    storefront: true                     # Optional. Default: false.
    constraints: [...]                   # Optional. Validation constraints.
    dependencies: [...]                  # Optional. Conditional visibility rules.

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.
`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.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, setting is excluded from schema.
`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.

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).

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.

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
Tabbed layout per feature
Scope switcher (global, store with identifier)
Input widgets matching setting types
Inline validation with constraint error messages
“Revert to default” to delete scope-specific overrides
Batch save with per-field error reporting

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.

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.

Basic Shop Theme feature overview

Tue, 07 Apr 2026 08:04:11 +0000

The Basic Shop Theme feature lets Business Admins configure the visual branding of a Spryker shop directly from the Back Office. Logos, theme colors, and custom CSS for the Storefront, Back Office, and Merchant Portal can all be set without code changes or redeployment.

Business problems it solves

Basic visual customization of a Spryker shop — such as applying a company logo or brand color — traditionally requires developer involvement, project-specific work, or code changes. This creates friction in critical moments:

Demo preparation by Solution Engineers — demos feel less customer-ready without brand-specific visuals.
Early project phases and proofs of concept — customers cannot easily apply their own branding.
First weeks after go-live — unnecessary delivery work delays Time-to-First-Transaction.

The Basic Shop Theme feature removes this dependency by providing a self-service branding interface in the Back Office.

What you can configure

All theme settings are managed under Back Office > Configuration > Theme.

Storefront

Setting	Type	Default	Description
Theme Main Color	Color picker	`#00bebe`	Primary brand color applied across the storefront. Exposed as the `--theme-main-color` CSS custom property.
Theme Alternative Color	Color picker	`#eb553c`	Secondary brand color for accents and highlights. Exposed as `--theme-alt-color`.
Storefront Logo	File upload	(empty)	Logo displayed in the storefront header. Recommended size: 186×50 px. Supported formats: GIF, PNG, JPEG, BMP, WebP, SVG.
Storefront Custom CSS	Text area	(empty)	Custom CSS injected into storefront pages. Use with caution — invalid CSS may break page layout.

Back Office

Setting	Type	Default	Description
Backoffice Theme Color	Color picker	`#1ebea0`	Primary theme color for the Back Office interface. Exposed as the `--bo-main-color` CSS custom property.
Backoffice Side Navigation Background	Color picker	`#23303c`	Side navigation and login background. Exposed as the `--bo-sidenav-color` CSS custom property.
Backoffice Side Navigation Text Color	Color picker	`#e4e4e4`	Side navigation text color. Exposed as the `--bo-sidenav-text-color` CSS custom property.
Back Office Logo	File upload	(empty)	Logo displayed in the Back Office sidebar. Recommended size: 186×50 px. Supported formats: GIF, PNG, JPEG, BMP, WebP, SVG.

Merchant Portal

Setting	Type	Default	Description
Merchant Portal Theme Color	Color picker	`#1ebea0`	Primary theme color for the Merchant Portal interface. Exposed as the `--mp-theme-color` CSS custom property.
Merchant Portal Logo	File upload	(empty)	Logo displayed in the Merchant Portal header. Recommended size: 186×50 px. Supported formats: GIF, PNG, JPEG, BMP, WebP, SVG.

How it works

The Basic Shop Theme feature is built on top of the Back Office Configuration Framework. All settings are declared in a YAML schema file bundled with the Spryker core modules. The Configuration module reads this file and renders the corresponding UI in the Back Office.

Storefront theming flow

A Business Admin sets a theme color or logo in the Back Office.
The value is saved and published to key-value storage (Redis) via the Publish & Synchronize mechanism.
The configurationValue() Twig function reads the value from storage and injects it into the page-blank layout as a CSS custom property or logo image tag.

Back Office and Merchant Portal theming flow

A Business Admin sets a theme color or logo in the Back Office.
The value is saved in the database.
The configurationValue() Twig function reads the value from the database and injects it into the respective layout template as a CSS custom property or logo image tag.

CSS custom properties

Theme colors are injected as CSS custom properties so that the design system can use them throughout component styles:

Custom Property	Scope	Description
`--background-brand-primary`	Storefront	Storefront primary brand color
`--background-brand-subtle`	Storefront	Storefront secondary accent color
`--bo-main-color`	Back Office	Back Office primary theme color
`--bo-sidenav-color`	Back Office	Back Office side navigation and login background
`--bo-sidenav-text-color`	Back Office	Back Office side navigation text color
`--spy-primary-color`	Merchant Portal	Merchant Portal primary theme color

Logo upload fields

Logo settings use a file upload widget in the Back Office. Uploaded files are stored via a configured Flysystem media filesystem service and served from a public URL. Each application context uses its own filesystem service:

Context	Filesystem service
Storefront	`storefront-media`
Back Office	`backoffice-media`
Merchant Portal	`merchant-portal-media`

In production, these services write to an S3 bucket (or compatible object storage). In development and CI environments, files are stored locally at public/Yves/assets/static/images and served via the Yves assets path.

If the field is left empty, the default logo is displayed.

Store-level customization

All theme settings support both global and store scopes. You can apply the same branding across all stores (global scope) or override individual settings per store (store scope).

Example:

Store	Theme Main Color	Behavior
Global	`#00bebe`	Applied to all stores by default
DE	`#ff0000`	Overrides the global value for DE only
AT	(not set)	Inherits `#00bebe` from global

To switch scope, use the scope selector at the top of the Configuration Management page.

Security

Twig access — the configurationValue() and configurationValues() Twig functions are available in templates, but theme layout templates only read the specific compound keys they are designed for.
Color injection — color values are escaped with | e('css') to prevent CSS injection.
Custom CSS sanitization — custom CSS input is sanitized using symfony/html-sanitizer before being saved, reducing the risk of injecting malicious markup. The rendered output still uses | raw since CSS must be injected verbatim, so this setting should only be accessible to trusted administrators.
File uploads — uploaded logo files are stored in isolated filesystem services per context. File types are validated on upload.
All theme settings are protected by Back Office authentication and ACL.

Feature	Link
Back Office Configuration Framework	Overview
Configuration Management	Developer guide
Install the Basic Shop Theme	Integration guide

Back Office Configuration Framework

Tue, 07 Apr 2026 08:04:11 +0000

The Back Office Configuration Framework is a structured approach to exposing business-relevant configuration options directly in the Spryker Back Office. Instead of defining configuration in code or YAML files that require redeployment, businesses can manage defined behaviors through structured UI pages. Developers define configuration options once in YAML, and the framework automatically renders them as configurable Back Office interfaces.

Business problems it solves

Managing configuration in traditional commerce platforms creates friction between technical and business teams:

Configuration changes require developer involvement, code modifications, and a full deployment cycle.
Business teams depend on IT to adjust behaviors that are fundamentally business decisions.
YAML and code-level configuration is inaccessible to non-technical stakeholders and prone to error.
Each configuration change introduces risk, slows down operations, and increases the total cost of change.

The Back Office Configuration Framework addresses these challenges by creating a clear, controlled boundary between what developers define and what business users can adjust.

Key value for your business

Faster time to change Business users adjust configured behaviors directly in the Back Office. No code change, no pull request, no deployment required.
Reduced operational risk Configuration is exposed through structured, validated UI pages. Business users work within defined options rather than editing raw configuration files.
Developer efficiency Developers define configuration options once in YAML. The framework handles rendering, validation, and persistence automatically, eliminating repetitive UI work.
Consistent experience All configuration pages follow the same structure and interaction patterns, making it easier for business users to navigate and manage settings across features.
Extensibility by design The framework supports both out of the box Spryker features and project-specific customizations, so teams can introduce new configurable behaviors without building new infrastructure.

Who benefits and how

For business leaders

Lower cost of change Adjusting business behaviors no longer requires a development sprint or deployment window. Teams can respond to market conditions and business needs faster.
Reduced dependency on IT Business teams gain direct control over selected configuration options without needing to involve developers for every adjustment.
Stable, governed configurability The framework exposes only explicitly defined options. Business users operate within guardrails set by the development team, reducing the risk of misconfiguration.

For product and commerce teams

Self-service configuration Manage feature behavior directly from the Back Office, using familiar UI patterns. No need to understand YAML syntax or request a deployment.
Faster iteration Test different configurations, observe results, and adjust without waiting for a release cycle.
Visibility into configurable options All available configuration options are surfaced in one place, making it easy to understand what can be changed and what the current settings are.

For developers and architects

Define once, render automatically Declare configuration options in YAML. The framework generates the corresponding Back Office UI, saving significant development and maintenance effort.
Separation of concerns Configuration definition stays with the developer; configuration management becomes a business user activity. This boundary is enforced by the framework.
Standardized patterns Avoid building custom configuration UIs for each feature. The framework provides consistent infrastructure that all teams benefit from.

Key capabilities

Support for out of the box and custom features

The framework supports configuration for existing Spryker out of the box features as well as project-specific customizations. Teams can use it to expose configuration options for both standard platform capabilities and bespoke features built for a specific project.

Structured and controlled business configurability

Selected business-relevant configuration moves from code level to UI level without exposing low-level technical complexity. The developer controls which options are available, what values are valid, and how they are presented. The business user controls what value is set, within those defined parameters.

Out of the box implementations

The Back Office Configuration Framework ships with the following out of the box implementations.

B2B Product Availability Display

The initial release ships with a configuration UI for B2B Product Availability Display. This implementation demonstrates the framework in a real-world use case, allowing business users to configure how product availability information is presented to B2B buyers directly from the Back Office.

Basic Shop Theme

The second out of the box implementation provides a configuration UI for shop branding. Business Admins can set theme colors, logo URLs, and custom CSS for the Storefront, Back Office, and Merchant Portal without code changes or redeployment. For details, see Basic Shop Theme feature overview.

How it works

The Back Office Configuration Framework follows a developer-first definition approach with a business-user-facing runtime experience:

Developer defines configuration options in YAML The developer declares the available configuration options, their data types, validation rules, and default values in a structured YAML definition.
Framework generates the Back Office UI The framework reads the YAML definition and automatically renders the corresponding configuration page in the Back Office, including form fields, labels, and validation feedback.
Business user manages configuration A Back Office user with appropriate permissions accesses the configuration page, adjusts the available options, and saves changes.
Changes take effect without redeployment Configuration updates are stored and applied at runtime. No code changes or deployments are required.

Comparison to traditional configuration approaches

Code-level configuration

Traditional approach: Configuration values are hardcoded or set in PHP configuration files. Changing a value requires a code change, review, and deployment.

Back Office Configuration Framework: Configuration values are managed in the Back Office UI. Changes take effect immediately, within the boundaries defined by the developer.

YAML-based configuration

Traditional approach: Configuration is declared in YAML files that are part of the codebase. Changing a value requires editing a file, committing the change, and triggering a deployment.

Back Office Configuration Framework: YAML is still used, but only by developers to define what options are available. Business users interact with the resulting UI, not with YAML directly.

Custom configuration UIs

Traditional approach: Each feature that requires business-user configuration needs a custom-built UI, resulting in inconsistent experiences and duplicated development effort.

Back Office Configuration Framework: All configurable features share the same framework-generated UI infrastructure, reducing development effort and ensuring a consistent experience.

Spryker Documentation

Release notes 202604.0

Install Search by Image

Search by Image

Search by Image

AI Commerce

Features

Who benefits

Set up DNS

Install the Basic Shop Theme feature

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

Secret vs Storefront Behavior

Available Scopes

Constraints

Built-in Constraint Types

Dependencies

Dependency Rule

When Clause

Condition

Dependency Operators

Schema File Locations

Backoffice Management

Twig Integration

configurationValue

configurationValues

Common Issues

Basic Shop Theme feature overview

Business problems it solves

What you can configure

Storefront

Back Office

Merchant Portal

How it works

Storefront theming flow

Back Office and Merchant Portal theming flow

CSS custom properties

Logo upload fields

Store-level customization

Security

Related features

Back Office Configuration Framework

Business problems it solves

Key value for your business

Who benefits and how

For business leaders

For product and commerce teams

For developers and architects

Key capabilities

Support for out of the box and custom features

Structured and controlled business configurability

Out of the box implementations

How it works

Comparison to traditional configuration approaches

Code-level configuration

YAML-based configuration

Custom configuration UIs

The `getModuleConfig()` Method

`file_upload` properties

`configurationValue`

`configurationValues`