Transfer data between Yves and Zed

Fri, 19 Jun 2026 12:58:22 +0000

Yves gets most of its data from the client-side NoSQL data stores (data such as product details, product categories, and prices). There are situations when Yves needs to communicate with Zed either to submit data (for example, the customer has submitted a new order or subscribed to a newsletter) or to retrieve data (for example, order history for the customer or customer account details). This document shows how to set up communication between Yves and Zed and display a random salutation message that is retrieved from Zed. {% info_block warningBox "Prerequisites" %} You need a module for which you set up communication between Yves and Zed. To add the module, see [Add a new module](/docs/dg/dev/backend-development/extend-spryker/create-modules.html). {% endinfo_block %} To implement communication between Yves and Zed, follow the steps below. ## 1. Create a transfer object Communication between Yves and Zed is done using [transfer objects](/docs/dg/dev/backend-development/data-manipulation/data-ingestion/structural-preparations/create-use-and-extend-the-transfer-objects.html). So to establish communication between Yves and Zed, you need to create a transfer object as follows: 1. Create a new transfer object and add it to the `src/Pyz/Shared/HelloWorld/Transfer/` folder. In the example, it's called the `helloworld.transfer.xml` transfer object, and one property is assigned to it: ```xml ``` 2. Generate the transfer object so that it's ready to be used: ```bash console transfer:generate ``` 1. Add an operation to your `HelloWorldFacade` that returns a random salutation message using the transfer object you've just defined: ```php getFactory()->createMessageGenerator()->generateHelloMessage(); } ``` ## 2. Create a gateway controller The `GatewayController` controller is responsible for communication with Yves. It must extend the `AbstractGatewayController` class. So your next step is to create the controller. Create the `GatewayController` in Zed under `Pyz\Zed\HelloWorld\Communication\Controller`. Add an action to this controller that calls the functionality you have exposed through your facade: ```php getFacade() ->getSalutationMessage(); } } ``` ## 3. Implement the stub Move to the client part to add support for calling the added controller action and follow these steps: 1. In `src/Pyz/Client/HelloWorld/Zed`, create a `HelloWorldStub` stub. This stub lets you submit an HTTP request to Zed.

Pyz\Client\HelloWorld\Zed

```php zedRequestClient = $zedRequestClient; } /** * @return \Generated\Shared\Transfer\HelloWorldMessageTransfer */ public function getSalutationMessage() { return $this->zedRequestClient->call( '/hello-world/gateway/get-salutation-message', new HelloWorldMessageTransfer() ); } } ```

{% info_block infoBox "Request parameter" %} Through the second parameter, you can pass a transfer object as a request parameter to the request client call. {% endinfo_block %} 2. Add a corresponding interface for the stub (`HelloWorldStubInterface`). The interface should contain the `getSalutationMessage()` method defined. {% info_block infoBox %} In the example, the stub depends on `ZedRequestClient` that can be provided by implementing `HelloWorldDependencyProvider`:

Pyz\Client\HelloWorld

```php addZedRequestClient($container); return $container; } /** * @param \Spryker\Client\Kernel\Container $container * * @return \Spryker\Client\Kernel\Container */ protected function addZedRequestClient(Container $container) { $container[self::CLIENT_ZED_REQUEST] = function (Container $container) { return $container->getLocator()->zedRequest()->client(); }; return $container; } } ```

{% endinfo_block %} 3. To get an instance of `HelloWorldStub`, create `HelloWorldFactory`: ```php getZedRequestClient()); } /** * @return \Spryker\Client\ZedRequest\ZedRequestClientInterface */ protected function getZedRequestClient() { return $this->getProvidedDependency(HelloWorldDependencyProvider::CLIENT_ZED_REQUEST); } } ``` ## 4. Implement the client Now you can create the client that consumes this service. In `src/Pyz/Client/HelloWorld`, create the `HelloWorldClient` client together with its corresponding interface. ```php getFactory() ->createZedStub() ->getSalutationMessage(); } } ``` ## 5. Create a controller and a view in Yves Now you can move to Yves and create the controller and the Twig template that renders a random message: 1. In `src/Pyz/Yves/HelloWorld/Controller`, create `IndexController`: ```php $this->getClient()->getSalutationMessage() ]; } } ``` 2. In `src/Pyz/Yves/HelloWorld/Theme/default/index`, create the `index.twig` file: ```php {% raw %}{%{% endraw %} extends "@application/layout/layout.twig" {% raw %}%}{% endraw %} {% raw %}{%{% endraw %} block content {% raw %}%}{% endraw %} {% raw %}{{{% endraw %} salutationMessage.value {% raw %}}}{% endraw %} {% raw %}{%{% endraw %} endblock {% raw %}%}{% endraw %} ``` ## 6. Set up the URL routing 1. In `src/Pyz/Yves/HelloWorld/Plugin/Route`, add `HelloWorldRouteProviderPlugin`: ```php buildRoute('/hello', 'HelloWorld', 'index', 'indexAction'); $routeCollection->add(static::ROUTE_HELLO_WORD, $route); return $routeCollection; } } ``` 2. Register your route provider plugin under `RouterDependencyProvider`: ```php protected function getRouteProvider($isSsl) { return [ //... new HelloWorldRouteProviderPlugin(), ]; } ``` 3. Clear cache for routes: ```bash vendor/bin/console router:cache:warm-up ``` That's it! `https://mysprykershop.com/hello` now displays a random salutation message. ## ZedRequest header Since [ZedRequest 3.16.0](https://github.com/spryker/zed-request/releases/tag/3.16.0), you can alter the headers sent with each ZedRequest. You can either use the *default header plugins* or *create your own* by using the `\Spryker\Client\ZedRequestExtension\Dependency\Plugin\HeaderExpanderPluginInterface`. ### Default header plugins You can use the following default header plugins: - `\Spryker\Client\ZedRequest\Plugin\AcceptEncodingHeaderExpanderPlugin`, adds the `Accept-Encoding` header to the request. - `\Spryker\Client\ZedRequest\Plugin\AuthTokenHeaderExpanderPlugin`, adds the `Auth-Token` header to the request. - `\Spryker\Client\ZedRequest\Plugin\RequestIdHeaderExpanderPlugin`, adds the `X-Request-ID` header to the request. These plugins can be added to `\Pyz\Client\ZedRequest\ZedRequestDependencyProvider::getHeaderExpanderPlugins()`. ### Create your own header plugin You can create your own header expander plugin with the `\Spryker\Client\ZedRequestExtension\Dependency\Plugin\HeaderExpanderPluginInterface`. For example, if you need a header with the name `Project-Name`, you just create a plugin like this: ```php

Identity Access Management

Fri, 19 Jun 2026 12:08:07 +0000

The Identity Access Management capability enables all types of users in a Spryker shop to create and manage accounts. Different levels of security let users manage the access of other users. {% info_block infoBox "Federated Authentication via OAuth2/OIDC" %} Spryker now supports [Federated Authentication](/docs/pbc/all/oauth/latest/federated-authentication.html) — a modern alternative to managing separate Spryker credentials. Instead of maintaining a standalone identity per application, your users log in through the Identity Provider your organization already uses. Key benefits: - **Works across all Spryker applications**: Storefront, Back Office, and Merchant Portal are all supported out of the box. - **Broad provider support**: Connect any OAuth2/OIDC-compatible IdP — Keycloak, Microsoft Entra ID, Okta, Auth0, Google Workspace, Salesforce, Amazon Cognito, and more. - **Multiple providers on Storefront and Merchant Portal**: You can connect as many IdPs as your users need, with a dedicated login button for each. {% endinfo_block %} ## Back Office authentication Back Office supports login via two types of accounts: - Back Office account. - Account of a third-party service that is configured as a single sign-on. ### Login with a Back Office account Only an existing Back Office user with sufficient permissions or a developer can create Back Office accounts. That is, if you want to onboard a new Back Office user, you need to create an account for them. For instructions on creating accounts in the Back Office, see [Create users](/docs/pbc/all/user-management/latest/base-shop/manage-in-the-back-office/manage-users/create-users.html). To log in, on the Back Office login page, a user enters the email address and password of their account. If the credentials are correct and their account is active at that time, they are logged in. If a user does not remember their password, they can reset it using the form available on the login page. ### Login with a single sign-on Your project can have a single sign-on(SSO) login configured for the Back Office. SSO lets users log into the Back Office with accounts of a third-party service. The feature is shipped with an exemplary ECO module that supports SSO authentication via Microsoft Azure Active Directory. With the existing infrastructure, you can develop your own ECO modules for the identity managers you need. SSO uses the [OpenID](https://en.wikipedia.org/wiki/OpenID) protocol for authentication. To log in with an SSO, on the Back Office login page, users click **Login with {Third-party service name}**. This opens the sign-in page of the configured service. Users sign in with their accounts and get redirected to the Back Office. If a user chooses to log in using a third party, they are redirected to the OAuth provider's sign-in page—for example, Microsoft Azure. If the user successfully signs into the third-party service, the check is made if the user exists in the Spryker database. If the user exists in the database and is active, the user is logged in. The following sections describe different ways of handling users that have access to your SSO service, but don't have a Back Office account. ### SSO authentication strategies Depending on your access and security requirements, you can have one of the following strategies implemented for SSO authentication. #### Registration is required only with the SSO service If a user logs in with an SSO but does not have a Back Office account, the following happens: - Based on the third-party system's user data, such as first name, last name, and email, a Back Office account is created. - The user is assigned to the default user group. - The user is logged into the Back Office. The login process looks like this: ![image](https://confluence-connect.gliffy.net/embed/image/5b0f6ab5-d4d5-4b53-b82a-d73bec9c81ea.png?utm_medium=live&utm_source=custom) #### Registration is required with the SSO service and with Spryker If a user logs in with an SSO but does not have a Back Office account, the user is not logged in. To be able to log in, a user must have a Back Office account registered using the email address used for their account with the SSO service. Usually, this strategy is used when not all the users that have access to the SSO service need access to the Back Office. ## Post-login redirect When a user's session times out, they are redirected to the login page. Without post-login redirect, after re-authentication, users land on the homepage and lose their context. With post-login redirect enabled, users are automatically sent back to the exact page they were on before the session expired — preserving their workflow across Back Office, Merchant Portal, and Storefront. The last visited page URL is tracked on every eligible GET request and stored in a browser cookie named `last-visited-page`. AJAX requests, login and logout pages, and internal framework paths are excluded from tracking. If the user was on a create or edit page before the session expired, they are redirected back to that page, but any unsaved data is lost. Post-login redirect does not apply to agent users in Storefront and Merchant Portal. Redirect across multiple browsers or devices is not supported. The redirect applies only to the browser in which the original session was active. ## Glue API authentication For details about Glue API authentication, see [Glue API authentication and authorization](/docs/integrations/spryker-glue-api/authenticating-and-authorization/authenticating-and-authorization.html) ## Current constraints The feature has the following functional constraint: Each of the identity managers is an ECO module that must be developed separately. After the module development, the identity manager's roles and permissions must be mapped to the roles and permissions in Spryker. The mapping is always implemented at the project level. ## Related Developer documents |INSTALLATION GUIDES | GLUE API GUIDES | | - | - | | [Install the Spryker Core Back Office feature](/docs/pbc/all/identity-access-management/latest/install-and-upgrade/install-the-spryker-core-back-office-feature.html) | [Authentication and authorization](/docs/integrations/spryker-glue-api/authenticating-and-authorization/authenticating-and-authorization.html) | | [Install Microsoft Azure Active Directory](/docs/pbc/all/identity-access-management/latest/install-and-upgrade/install-microsoft-azure-active-directory.html) | [Authentication and authorization](/docs/integrations/spryker-glue-api/authenticating-and-authorization/authenticating-and-authorization.html) | | [Install the Customer Access Glue API](/docs/pbc/all/identity-access-management/latest/install-and-upgrade/install-the-customer-access-glue-api.html) | [Create customers](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-create-customers.html) | | [Integrate post-login redirect](/docs/pbc/all/identity-access-management/latest/install-and-upgrade/integrate-post-login-redirect.html) | | | | [Federated Authentication via OAuth2/OIDC](/docs/pbc/all/oauth/latest/federated-authentication.html) | | | [Confirm customer registration](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-confirm-customer-registration.html) | | | [Manage customer passwords](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-manage-customer-passwords.html) | | | [Authenticate as a customer](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-customer.html) | | | [Manage customer authentication tokens via OAuth 2.0](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-manage-customer-authentication-tokens-via-oauth-2.0.html) | | | [Manage customer authentication tokens](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-manage-customer-authentication-tokens.html) | | | [Authenticate as a Back Office user](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-back-office-user.html) | | | [Authenticating as a company user](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-company-user.html) | | | [Manage company user authentication tokens](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-manage-company-user-authentication-tokens.html) | | | [Authenticate as an agent assist](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-an-agent-assist.html) | | | [Managing agent assist authentication tokens](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-manage-agent-assist-authentication-tokens.html) | | | [Delete expired refresh tokens](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-delete-expired-refresh-tokens.html) |

Enable Dynamic Multistore

Fri, 19 Jun 2026 12:03:03 +0000

This document describes how to enable Dynamic Multistore (DMS).

Prerequisites

If your project version is below 202307.0, Install Dynamic Multistore.

Enable Dynamic Multistore

Staging environment

To avoid unexpected downtime and data loss, perform and test *all* of the following steps in a staging environment first.

Replace StoreClient::getCurrentStore() and StoreFacade::getCurrentStore() methods with StoreStorageClient:getStoreNames(), StoreStorageClient::findStoreByName(), or StoreFacade::getStoreCollection() in the following:

Back Office
Merchant Portal
Console Commands
Gateway
BackendAPI

Update custom console commands to meet the following rules:

Store(Facade|Client)::getCurrentStore() isn’t used in the code a console command executes.
All store-aware commands implement Spryker\Zed\Kernel\Communication\Console\StoreAwareConsole and execute actions for a specific store if a store parameter is provided; if not provided, actions are executed for all the stores in the region.
Optional: We recommend using the --store parameter instead of APPLICATION_STORE env variable; both methods are supported.

After enabling DMS, the basic domain structure must change from store to region for all the applications. For example, https://yves.de.mysprykershop.com will change to https://yves.eu.mysprykershop.com. To prevent negative SEO effects, set up the needed redirects. If your target domain doesn’t change, for example it doesn’t contain a region name - yves.mysprykershop.com - you may skip this step.
Update AWS deployment files to DMS mode using the example:

Original environment variables section:

SPRYKER_HOOK_BEFORE_DEPLOY: 'vendor/bin/install -r pre-deploy.dynamic-store-off -vvv'
SPRYKER_HOOK_AFTER_DEPLOY: 'true'
SPRYKER_HOOK_INSTALL: 'vendor/bin/install -r production.dynamic-store-off --no-ansi -vvv'
SPRYKER_HOOK_DESTRUCTIVE_INSTALL: 'vendor/bin/install -r destructive.dynamic-store-off --no-ansi -vvv'
SPRYKER_YVES_HOST_DE: de.
SPRYKER_YVES_HOST_AT: at.

Updated environment variables section:

SPRYKER_HOOK_BEFORE_DEPLOY: 'vendor/bin/install -r pre-deploy -vvv'
SPRYKER_HOOK_AFTER_DEPLOY: 'true'
SPRYKER_HOOK_INSTALL: 'vendor/bin/install -r dynamic-store --no-ansi -vvv'
SPRYKER_HOOK_DESTRUCTIVE_INSTALL: 'vendor/bin/install -r destructive --no-ansi -vvv'
SPRYKER_DYNAMIC_STORE_MODE: true
SPRYKER_YVES_HOST_EU: yves.eu.

Original regions section:

regions:
  stores:
    DE:
      services:
        broker:
          namespace: de_queue
        key_value_store:
          namespace: 1
        search:
          namespace: de_search
        session:
          namespace: 2
    AT:
      services:
        broker:
          namespace: at_queue
        key_value_store:
          namespace: 3
        search:
          namespace: at_search
        session:
          namespace: 4

Updated regions section:

regions:
  broker:
    namespace: eu-docker
  key_value_store:
    namespace: 1
  search:
    namespace: eu_search

Before first deployment, create a support case and provide the deploy.ABC.yml file that contains the dynamic multistore setup. For example: “We have added the dynamic multistore setup to our deploy.ABC.yml and would like it to be activated.”
DMS changes the structure of RabbitMQ messages. When you’re ready for the migration, wait for all the remaining messages in the queue to be processed. When the queue is empty, enable the maintenance mode.

The downtime associated with the maintenance mode is limited to the deployment time, which usually takes up to an hour.

Run a normal deploy for your server pipeline.

Verification

- Make sure your store is available at `https://yves.eu.mysprykershop.com` or `https://backoffice.eu.mysprykershop.com`. - Make sure the store switcher is displayed on the Storefront.

Your shop is now running in DMS mode.

Check if Dynamic Multistore is enabled

DMS is enabled if at least one of the following applies:

Using environment: If the value of SPRYKER_DYNAMIC_STORE_MODE environment variable is true
Using interface: In the Back Office > Administration > Stores, an Edit button is displayed next to each store.

Disable Dynamic Multistore

Staging environment

To avoid unexpected downtime and data loss, perform and test *all* of the following steps in a staging environment first.

After disabling DMS, the basic domain structure will change from region to store for all the applications. To prevent negative SEO effects, set up the needed redirects.
DMS changes the structure of RabbitMQ messages. When you’re ready for the migration, wait for all the remaining messages in the queue to be processed. When the queue is empty, enable the maintenance mode. (Expected downtime is limited to the deployment time, normally it takes less than 1hr)
Revert changes in deploy files to disable DMS:

Original environment variables section:

SPRYKER_HOOK_BEFORE_DEPLOY: 'vendor/bin/install -r pre-deploy -vvv'
SPRYKER_HOOK_AFTER_DEPLOY: 'true'
SPRYKER_HOOK_INSTALL: 'vendor/bin/install -r dynamic-store --no-ansi -vvv'
SPRYKER_HOOK_DESTRUCTIVE_INSTALL: 'vendor/bin/install -r destructive --no-ansi -vvv'
SPRYKER_DYNAMIC_STORE_MODE: true
SPRYKER_YVES_HOST_EU: yves.eu.

Updated environment variables section:

SPRYKER_HOOK_BEFORE_DEPLOY: 'vendor/bin/install -r pre-deploy.dynamic-store-off -vvv'
SPRYKER_HOOK_AFTER_DEPLOY: 'true'
SPRYKER_HOOK_INSTALL: 'vendor/bin/install -r production.dynamic-store-off --no-ansi -vvv'
SPRYKER_HOOK_DESTRUCTIVE_INSTALL: 'vendor/bin/install -r destructive.dynamic-store-off --no-ansi -vvv'
SPRYKER_YVES_HOST_DE: de.
SPRYKER_YVES_HOST_AT: at.

Original regions section:

regions:
  broker:
    namespace: eu-docker
  key_value_store:
    namespace: 1
  search:
    namespace: eu_search

Updated regions section:

regions:
  stores:
    DE:
      services:
        broker:
          namespace: de_queue
        key_value_store:
          namespace: 1
        search:
          namespace: de_search
        session:
          namespace: 2
    AT:
      services:
        broker:
          namespace: at_queue
        key_value_store:
          namespace: 3
        search:
          namespace: at_search
        session:
          namespace: 4

Run a normal deploy for your server pipeline.

Verification

- Make sure your store is available at `https://yves.de.mysprykershop.com` or `https://backoffice.de.mysprykershop.com`. - Make sure the store switcher is *not* displayed on the Storefront.

Architecture as Code

Fri, 19 Jun 2026 11:56:26 +0000

Well-documented project architecture enables faster internal and external onboarding, passes audits cleanly and aligns teams on requirements. Without it, your system becomes a black box that only the original developers understand.

Architecture as Code treats architecture documentation like code, similarly to the Infrastructure-as-Code concept. Instead of storing architecture in binary formats or external tools (Word, PowerPoint, Visio, Confluence) that become outdated quickly, you store and maintain architecture documentation in version control alongside your implementation.

Spryker ships the architecture/ folder with a complete Architecture as Code structure with its demoshop codebase. You can refer to architecture/README.md that describes how to work with it. Below, you find all the general information about the structure and principles. We go into the details of each aspect to help you understand and extend this architecture documentation in your project.

Existing projects

If your project is based on a Spryker release before 202602.0, refer to the Spryker B2B Demo Marketplace master branch source code to see how the Architecture as Code structure is implemented and to copy the “architecture/” folder into your project.

Why Architecture as Code

Traditional architecture documentation suffers from several challenges:

Documentation drift - Binary formats stored separately from code become outdated quickly
Version control gaps - Specialized tools do not integrate with Git workflows
Collaboration barriers - Requires specialized software and binary file merging
AI limitations - AI tools understand code and Markdown effectively but struggle with proprietary formats and binary documents

Architecture as Code solves these problems:

Version controlled - Store in Git alongside implementation. Track every change with full history.
AI-ready - Markdown and diagrams-as-code enable AI assistance, automated validation, and intelligent analysis.
Standard formats - Use industry standards (arc42, C4, ADRs, Mermaid) that external teams understand immediately.
Collaborative - Review through pull requests. No special tools required — only a text editor.
Living documentation - Update during development, not after. Documentation evolves with your system.

Core Principles

Standards over invention - Use industry-proven formats and standards (arc42, C4, ADRs, Mermaid) instead of custom documentation.

Minimal but sufficient - Start simple. Prioritize clarity and expansion over completeness on day one.

Architecture is code - Write in plain text, store in Git, review through pull requests, deploy automatically.

Concepts and Choices

arc42

arc42 is a proven template for architecture documentation used globally across industries.

Why arc42 fits Spryker projects:

Spryker projects vary dramatically in complexity — from simple B2C shops to complex B2B marketplaces with extensive integrations and order management systems. arc42 is flexible enough to cover architecture of any complexity and scales as your Spryker implementation grows. You can start simple with minimal sections and expand as your architecture requires more detail.

The template includes 12 sections (described below) covering all architectural aspects. Section 4 (Solution Designs) provides RFC-style exploration templates. Section 9 (Architecture Decisions) uses ADRs to document decisions with context and consequences. This workflow — explore with Solution Designs, then document decisions with ADRs — ensures thoughtful architecture evolution.

C4 Model

C4 Model provides a hierarchical approach to system visualization with four levels of abstraction.

Why C4 fits Spryker architecture:

Spryker architecture unfolds naturally through C4 layers — start with the system context, zoom into containers (Yves, Zed, Client, databases, services), then dive deeper into layers and components as needed. This progressive detail matches how Spryker complexity reveals itself. The entire Spryker feature set can be shown using this unfolding approach.

Flexibility advantage:

You control the depth. Start at C1 (context) and continue only as deep as your documentation needs require. Given limited architect time, this flexibility is essential — stop at the level appropriate for your stakeholders and complexity.

Mermaid and PlantUML

Mermaid - Our primary choice for diagramming-as-code:

Renders automatically in GitHub and GitLab, and can be rendered via plugins in popular IDEs
No proprietary tools required
Covers 90% of diagram needs: flowcharts, sequences, C4 diagrams
Online editor at mermaid.live for convenient editing and better visualization than most IDEs

PlantUML - For precision when needed:

Essential for Entity-Relationship Diagrams where field-level precision matters
Online editor at plantuml.com for live editing and preview

What Comes Out of the Box

We provide templates with clear structure and minimal context, plus examples of the most common diagram types (C4, data flow, integration, sequence) and documentation patterns (ADRs, Solution Designs). AI tools work most efficiently when they see the methodology (like arc42), understand the structure, and have examples to follow. This approach enables you to generate architecture documentation much faster with AI assistance.

Templates provide examples and structural guidance — you should adapt content to your project’s context. You do not need to implement all sections immediately; remove or keep unused sections based on your documentation strategy.

Folder Structure

architecture/
├── 01-introduction-and-goals.md           # Requirements, quality goals, stakeholders
├── 02-constraints.md                      # Technical, organizational constraints
├── 03-system-scope-and-context.md         # System boundaries, external interfaces
│                                          # Includes: External systems and integration tables
├── 04-solution-designs/                   # RFC-style exploration documents
│   ├── README.md                          # Workflow explanation
│   └── sd-000-template.md                 # Solution design template
├── 05-building-block-view.md              # System decomposition
├── 06-runtime-view.md                     # Behavior and interactions
├── 07-deployment-view.md                  # Infrastructure topology
├── 08-crosscutting-concepts.md            # Patterns spanning components
├── 09-architecture-decisions/             # Architecture decision records
│   ├── README.md                          # ADR workflow and sources
│   └── adr-000-template.md                # ADR template
├── 10-quality-requirements.md             # Performance, scalability, testing
│                                          # Includes: Volume planning, testing strategy
├── 11-risks-and-technical-debt.md         # Known issues and mitigation
├── 12-glossary.md                         # Domain terminology
├── diagrams/
│   ├── c4/
│   │   ├── c1-system-context.mmd          # System context diagram
│   │   ├── c2-spryker-container.mmd       # Container diagram
│   │   └── c3-component-diagram.mmd       # Component diagram
│   ├── data-flow/
│   │   └── product-price-data-flow.mmd    # Price data flow example
│   ├── integration/
│   │   └── product-price-integration.mmd  # Integration overview with protocols
│   ├── sequence/
│   │   ├── api-payment.mmd                # Payment flow
│   │   ├── publish-sync.mmd               # Publish and Sync process
│   │   └── punchout-greenwing-integration.mmd  # PunchOut example
│   └── erd/                               # Entity-relationship diagrams (PlantUML)
└── README.md                              # Quick start and overview

Diagram Organization and Best Practices

You have two approaches to managing diagrams. Choose based on your documentation use case.

Approach 1: Inline Diagrams

Write diagram code directly in markdown using code fences:

>flowchart LR
    A --> B

Pros: Diagrams are visible immediately; self-contained

Cons: Increases file size; duplicates code if reused

Approach 2: External Diagram Files

Store diagram code in /diagrams/ folder and reference via links:

[C1 System Context](diagrams/c4/c1-system-context.mmd)

Pros: Single source-of-truth; cleaner markdown; scalable

Cons: Requires clicking to view (less immediate)

Choosing Your Approach

This template uses Approach 2 for scalability and maintainability, but projects can mix both — use external files for core views, inline for one-off diagrams.

Universal Color Scheme:

All diagrams use colors optimized for both light and dark modes:

Orange #E67E22 - Communication layer
Blue #2980B9 - Backend services, APIs
Green #27AE60 - Web apps, external systems
Purple #9B59B6 - Storage (databases, caches)
Gray #95A5A6 - Infrastructure

Templates and Guidelines

Solution Design Template (04-solution-designs/sd-000-template.md):

Metadata section (status, date, stakeholders)
Problem statement
Goals and requirements
Proposed solution with diagrams
Implementation plan
Trade-offs and alternatives

ADR Template (09-architecture-decisions/adr-000-template.md):

Standard ADR structure
Status tracking
Context, decision, consequences
Links to related decisions

Volume Planning Table (Section 10):

Pre-structured table for capacity planning covering:

Catalog entities (products, categories, prices)
Cart constraints
User load projections
B2B customers structure
Marketplace metrics
Internationalization requirements
Orders and infrastructure

Getting Help

Resources

arc42 Documentation: https://arc42.org/
C4 Model Guide: https://c4model.com/
Mermaid Syntax: https://mermaid.js.org/
ADR Guidelines: https://adr.github.io/

Common Questions

Q: Do I need to fill in every arc42 section?

A: No. Fill in what is relevant for your project. Some sections may remain minimal.

Q: Can I add custom sections?

A: First, check all 12 arc42 sections — the standard format covers most architectural concerns. If no existing section fits your content, you can add a custom section. Ensure the section purpose is clear and describe it in the README.md file.

Q: How detailed should diagrams be?

A: For C4 diagrams, follow the levels: Context (high-level), Container (more detail), Component (detailed). For other diagram types (data flow, integration, sequence), follow industry standards for that specific notation.

Q: When should I create an ADR vs Solution Design?

A: Use Solution Design for exploration. Use ADR for documenting the final decision.

Q: Can I use different diagram notations?

A: Yes. The choice is yours — we do not limit you to Mermaid or PlantUML. Ensure your notation follows the core principles: viewable by people, understandable by AI tools, and ideally diagrams-as-code (text-based format in version control).

Q: Will diagrams-as-code replace whiteboards and visual editing tools?

A: No. The art of creating and drawing diagrams — whether on whiteboards, visual tools, or pen and paper — remains valuable. Diagrams-as-code is for documenting what you have drawn and decided. Use whatever tools help you think and collaborate, then capture the final result as code for version control and documentation.

Q: Can I use images as diagrams instead of diagrams-as-code?

A: Yes, it is better to have image diagrams than no diagrams at all, but understand the trade-off. Hand-drawn or visually edited diagrams often look more polished than generated ones. However, images are not as understandable or generable by AI (at least currently) and lack version control benefits. You can use both: include beautiful images for presentations and stakeholder communication, alongside diagrams-as-code for AI assistance and documentation processes.

Smart PIM

Fri, 19 Jun 2026 11:35:00 +0000

Smart PIM is an AI assistant embedded in the Back Office product creation and editing pages. It helps catalog managers enrich product data through AI-powered capabilities — all without leaving the product form. {% info_block infoBox "Example use case" %} A catalog manager is adding a new product and needs to write a compelling description, fill in image alt text, and assign the right categories. Instead of doing each task manually, the manager opens the Smart PIM panel and uses the built-in AI tools to generate and refine the content in seconds. {% endinfo_block %} ## Capabilities | CAPABILITY | DESCRIPTION | |------------|-------------| | Content improvement | Rewrites or enriches product descriptions, names, and attributes using AI. | | Image alt text | Generates descriptive alt text for product images automatically. | | Category suggestion | Suggests the most relevant categories for a product based on its content. | | Translation | Translates product content into other configured languages. | ## Use Smart PIM 1. In the Back Office, go to **Products > Products** and open a product create or edit page. 2. Click the sparkle icon to open the Smart PIM panel. ![Smart PIM sparkle icons](https://spryker.s3.eu-central-1.amazonaws.com/docs/dg/dev/ai-commerce/smart-pim-sparkle-icons.png) 3. Select a capability: - **Content improvement or Translation**: Select the option, review the result, and click **Apply**. ![Smart PIM translate improve dialog](https://spryker.s3.eu-central-1.amazonaws.com/docs/dg/dev/ai-commerce/smart-pim-translate-improve-dialog.png) ![Smart PIM translate dialog result](https://spryker.s3.eu-central-1.amazonaws.com/docs/dg/dev/ai-commerce/smart-pim-translate-dialog-result.png) - **Category suggestion**: Review the AI-generated category suggestions and assign them to the product. ![Smart PIM category suggestion](https://spryker.s3.eu-central-1.amazonaws.com/docs/dg/dev/ai-commerce/smart-pim-category-suggestion.png) - **Image alt text**: Review the AI-generated alt text and apply it to your product images. ![Smart PIM image alt text](https://spryker.s3.eu-central-1.amazonaws.com/docs/dg/dev/ai-commerce/smart-pim-image-alt-text.png) 4. Save the product. ## Developer resources | RESOURCE | DESCRIPTION | |----------|-------------| | [Smart PIM](/docs/dg/dev/ai/ai-commerce/smart-pim/smart-pim.html) | Technical overview: architecture, plugin structure, configuration options, and AiFoundation integration. | | [Install Smart PIM](/docs/dg/dev/ai/ai-commerce/smart-pim/install-smart-pim.html) | Step-by-step installation guide. |

Create a product configurator

Tue, 16 Jun 2026 14:58:00 +0000

This document explains how to build a custom [product configurator](/docs/pbc/all/product-information-management/{{page.version}}/base-shop/feature-overviews/configurable-product-feature-overview/configurable-product-feature-overview.html) at the code level and integrate it with a Spryker shop. It uses the *Water Treatment* configurator example (`WaterTreatmentConfiguratorPageExample`) as a reference. The example lets a customer configure an industrial water treatment system (flow rate, filtration type, tank material, control system, inlet connection, and power supply). Use it as a blueprint for your own configurator. Before you start, make sure the [Product Configuration feature is installed](/docs/pbc/all/product-information-management/{{page.version}}/base-shop/install-and-upgrade/install-features/install-the-product-configuration-feature.html). This document does not cover the core modules (`ProductConfiguration`, `ProductConfigurationStorage`, `ProductConfiguratorGatewayPage`, `ProductConfigurationCart`, the configuration widgets) — they are reused as is. ## Architecture overview A product configurator consists of two parts: 1. **A standalone configurator application** — a self-contained web app, served on its own host, where the customer selects the configuration. It is not part of the Yves/Zed application; it is bootstrapped from its own `public/` entry point. 2. **Shop-side integration** — the plugins and configuration that let the shop redirect to the configurator, route by configurator key, render the saved configuration on the Storefront and in the Back Office, and accept the configurator key in the cart, shopping list, and checkout. The data flow between the two is described in [Configuration process flow of configurable products](/docs/pbc/all/product-information-management/{{page.version}}/base-shop/feature-overviews/configurable-product-feature-overview/configuration-process-flow-of-configurable-product.html). The example module spans the following layers: ```text src/Pyz/Shared/WaterTreatmentConfiguratorPageExample/ # configurator key constant src/Pyz/Client/WaterTreatmentConfiguratorPageExample/ # request expander (access token URL) src/Pyz/Yves/WaterTreatmentConfiguratorPageExample/ # ConfiguratorPage, Theme (HTML shell + render views), render-strategy + security plugins src/Pyz/Zed/WaterTreatmentConfiguratorPageExample/ # frontend mirror config/console, sales render-strategy plugin public/WaterTreatmentConfigurator/ # PHP entry point, configurator.json data, i18n, and the mirrored app assets (dist) ``` ## 1. Define the configurator key Each configurator is identified by a unique key. Add a shared config that exposes it: ```php // src/Pyz/Shared/WaterTreatmentConfiguratorPageExample/WaterTreatmentConfiguratorPageExampleConfig.php namespace Pyz\Shared\WaterTreatmentConfiguratorPageExample; class WaterTreatmentConfiguratorPageExampleConfig { public const WATER_TREATMENT_CONFIGURATOR_KEY = 'WATER_TREATMENT_CONFIGURATOR'; } ``` This key is used everywhere the shop needs to recognize the configurator: the request expander, the supported-keys configs, and the data import. ## 2. Configure the host and shared secrets The configurator is served on a dedicated host. Set the host and port per environment in your `deploy.*.yml` files, and register the host in the application endpoints: ```yaml # deploy.dev.yml environment: SPRYKER_WATER_TREATMENT_CONFIGURATOR_HOST: water-treatment-configurator.spryker.local SPRYKER_WATER_TREATMENT_CONFIGURATOR_PORT: 80 # ... groups: applications: yves: endpoints: water-treatment-configurator.spryker.local: entry-point: WaterTreatmentConfigurator ``` {% info_block warningBox "Cloud environments" %} Adding a new host in `deploy.*.yml` does not create the DNS record in the cloud hosted zone. For cloud environments, align with the infrastructure team to add the DNS record for the new host. {% endinfo_block %} The configurator and the shop exchange a checksum signed with a shared secret. Keep the encryption key and initialization vector in `config/Shared/config_default.php` (shared by the shop and the configurator app): ```php $config[ProductConfigurationConstants::SPRYKER_PRODUCT_CONFIGURATOR_ENCRYPTION_KEY] = getenv('SPRYKER_PRODUCT_CONFIGURATOR_ENCRYPTION_KEY') ?: 'change123'; $config[ProductConfigurationConstants::SPRYKER_PRODUCT_CONFIGURATOR_HEX_INITIALIZATION_VECTOR] = getenv('SPRYKER_PRODUCT_CONFIGURATOR_HEX_INITIALIZATION_VECTOR') ?: '0c1ffefeebdab4a3d839d0e52590c9a2'; ``` The shop redirects the customer to the configurator host, so add the host to the kernel domain allowlist in the same file: ```php $config[KernelConstants::DOMAIN_WHITELIST][] = getenv('SPRYKER_WATER_TREATMENT_CONFIGURATOR_HOST'); ``` ## 3. Build the standalone configurator application ### Entry point The configurator app is bootstrapped from its own `public/` entry point. It loads the autoloader only — it does not boot the Yves/Zed kernel—so it stays lightweight: ```php // public/WaterTreatmentConfigurator/index.php use Pyz\Yves\WaterTreatmentConfiguratorPageExample\ConfiguratorPage; use Symfony\Component\HttpFoundation\Response; define('APPLICATION', 'CONFIGURATOR'); defined('APPLICATION_ROOT_DIR') || define('APPLICATION_ROOT_DIR', dirname(__DIR__, 2)); require_once APPLICATION_ROOT_DIR . '/vendor/autoload.php'; $response = (new ConfiguratorPage())->render(); if ($response instanceof Response) { $response->send(); } echo $response; ``` Because the kernel is not bootstrapped here, read environment values directly with `getenv()` rather than `Config::get()`. ### ConfiguratorPage `ConfiguratorPage` handles all requests to the configurator host. It distinguishes them by method and query parameters: - `POST` (create token) — starts a session, stores the request payload sent by the shop, and returns the redirect URL to the configurator page. - `GET` with `getConfigurationByToken` — returns the stored payload for a session token, so the frontend app can render it. - `POST` with `prepareConfiguration` — signs the submitted configuration with the shared key and returns the checksum and timestamp. - Default `GET` — serves the configurator HTML page (the built frontend app). ```php // src/Pyz/Yves/WaterTreatmentConfiguratorPageExample/ConfiguratorPage.php namespace Pyz\Yves\WaterTreatmentConfiguratorPageExample; class ConfiguratorPage { public function render() { if ($this->request->isMethod('GET') && $this->request->query->has('getConfigurationByToken')) { return $this->getRequestDataByTokenAction(); } if ($this->request->isMethod('POST') && $this->request->query->has('prepareConfiguration')) { return $this->prepareConfigurationResponseAction(); } if ($this->request->isMethod('POST')) { return $this->createTokenAction(); } return $this->renderHtmlPageAction(); } protected function createConfiguratorRedirectUrl(): string { return sprintf( '%s://%s?token=%s', getenv('SPRYKER_WATER_TREATMENT_CONFIGURATOR_PORT') === '443' ? 'https' : 'http', getenv('SPRYKER_WATER_TREATMENT_CONFIGURATOR_HOST') ?: '', htmlspecialchars($this->session->getId()), ); } } ``` The checksum is generated with the shared encryption key and initialization vector, so the shop can validate the configuration the configurator returns: ```php $checkSum = (new CrcOpenSslChecksumGenerator(getenv('SPRYKER_PRODUCT_CONFIGURATOR_HEX_INITIALIZATION_VECTOR') ?: '')) ->generateChecksum($productConfiguration, getenv('SPRYKER_PRODUCT_CONFIGURATOR_ENCRYPTION_KEY') ?: ''); ``` ### Frontend application The configurator UI is a self-contained frontend application (in the example, an Angular app). The example does not build it at the project level. Instead, it reuses the pre-built, data-driven app shipped in the `spryker-shop/date-time-configurator-page-example` package and feeds it the project's own data, so no project-level frontend build or tooling is required. The app is generic: at runtime, it loads its options from `./configurator.json`, served from `public/WaterTreatmentConfigurator/`. To turn it into a water treatment configurator, the example provides its own `public/WaterTreatmentConfigurator/configurator.json` and translations under `public/WaterTreatmentConfigurator/i18n/`. The default `GET` request to the configurator host serves a static shell, `Theme/index.html`, which loads the app assets from `./dist/`: ```php // ConfiguratorPage::renderHtmlPageAction() return file_get_contents(__DIR__ . '/Theme/index.html'); ``` The build step copies the pre-built app into the public folder of the configurator host. In the Zed module config, `getFrontendOriginPath()` resolves the built `dist` inside the vendor package, and `getFrontendTargetPath()` resolves the public folder of the configurator host: ```php // src/Pyz/Zed/WaterTreatmentConfiguratorPageExample/WaterTreatmentConfiguratorPageExampleConfig.php protected const FRONTEND_TARGET_PATH = '/public/WaterTreatmentConfigurator/dist'; protected const FRONTEND_ORIGIN_PATH = '../../../../vendor/spryker-shop/date-time-configurator-page-example/src/SprykerShop/Configurator/DateTimeConfiguratorPageExample/Theme/ConfiguratorApplication/dist'; public function getFrontendOriginPath(): string { return sprintf('%s/%s', __DIR__, static::FRONTEND_ORIGIN_PATH); } public function getFrontendTargetPath(): string { return sprintf('%s/%s', APPLICATION_ROOT_DIR, static::FRONTEND_TARGET_PATH); } ``` The copy is handled by the module's Zed business layer (`Business/Builder/FrontendBuilder`, which mirrors the origin `dist` into the target with `Filesystem::mirror()`), exposed through `WaterTreatmentConfiguratorPageExampleFacade::buildProductConfigurationFrontend()` and triggered by a console command: ```php // src/Pyz/Zed/WaterTreatmentConfiguratorPageExample/Communication/Console/WaterTreatmentProductConfiguratorBuildFrontendConsole.php public const COMMAND_NAME = 'frontend:water-treatment-product-configurator:build'; ``` Register the console in `Pyz\Zed\Console\ConsoleDependencyProvider` and run it during the build/install step of your environment: ```bash console frontend:water-treatment-product-configurator:build ``` Running this command copies the configurator app's built `dist` folder (from `FRONTEND_ORIGIN_PATH`) into the configurator host's public folder (`FRONTEND_TARGET_PATH`, `public/WaterTreatmentConfigurator/dist`). The configurator host serves the app from there, so the configurator only works after this copy step. Run the command on every build or install, and whenever the app assets or `configurator.json` change. {% info_block infoBox "Shipping your own frontend app" %} The example reuses the pre-built app from the `spryker-shop/date-time-configurator-page-example` package, so it needs no frontend tooling at the project level. If you ship your own configurator app instead, point `FRONTEND_ORIGIN_PATH` to its built output and exclude the app sources from the project linters and formatters—for example, add their path to `.stylelintignore` and `.prettierignore`. {% endinfo_block %} ### Configurator data and translations The reused app is data-driven: the product, its options, prices, and compatibility rules all come from the project-level `configurator.json`, and the wording comes from the project-level glossary files. Both are served from `public/WaterTreatmentConfigurator/` and are what make this instance a *water treatment* configurator. `public/WaterTreatmentConfigurator/configurator.json` holds the full product data — the sample product and all possible options: - `data` — the product shown in the configurator: `name`, `image`, `logo`, and `defaultPrice` per currency. - `configuration` — the list of parameter groups. Each group has an `id`, a `label`, an optional `tooltip`, and a `data` array of selectable options. Each option carries a `value`, a `title`, a `price` per currency, and optional `disabled` rules that switch off incompatible options in other groups. ```json { "data": { "name": "Industrial Water Treatment System", "image": "https://spryker.s3.eu-central-1.amazonaws.com/image/industrial-water-treatment-system.webp", "logo": "./logo.svg", "defaultPrice": { "EUR": 1245000, "CHF": 1189000, "USD": 1350000 } }, "configuration": [ { "id": "flowRate", "label": "Flow Rate (m³/h)", "tooltip": "Select the required flow rate", "data": [ { "value": "5", "title": "5 m³/h", "price": { "EUR": 0, "CHF": 0, "USD": 0 }, "disabled": { "tank": { "condition": ["duplex", "titanium"], "tooltip": "Not available with Duplex Steel or Titanium tank" } } } ] } ] } ``` The `i18n/` folder localizes the configurator. Each `i18n/.json` file (for example, `i18n/de_DE.json`) is a flat glossary that maps the English source strings used in `configurator.json`—group labels, tooltips, and option titles—to their translations. These keys extend the app's default glossary at the project level, so you add only the strings your own data introduces: ```json { "Flow Rate (m³/h)": "Durchflussrate (m³/h)", "Filtration Type": "Filtrationstyp", "Reverse Osmosis": "Umkehrosmose", "Select the required flow rate": "Benötigte Durchflussrate auswählen" } ``` ## 4. Route the shop to the configurator When a customer clicks **Configure**, the shop sends an access-token request to the configurator host. Tell the shop which host to use for your configurator key with a `ProductConfiguratorRequestExpanderPlugin`: ```php // src/Pyz/Client/WaterTreatmentConfiguratorPageExample/Plugin/ProductConfiguration/ExampleWaterTreatmentProductConfiguratorRequestExpanderPlugin.php namespace Pyz\Client\WaterTreatmentConfiguratorPageExample\Plugin\ProductConfiguration; class ExampleWaterTreatmentProductConfiguratorRequestExpanderPlugin extends AbstractPlugin implements ProductConfiguratorRequestExpanderPluginInterface { public function expand(ProductConfiguratorRequestTransfer $productConfiguratorRequestTransfer): ProductConfiguratorRequestTransfer { return $productConfiguratorRequestTransfer->setAccessTokenRequestUrl($this->createConfiguratorUrl()); } protected function createConfiguratorUrl(): string { return sprintf( '%s://%s', getenv('SPRYKER_WATER_TREATMENT_CONFIGURATOR_PORT') === '443' ? 'https' : 'http', getenv('SPRYKER_WATER_TREATMENT_CONFIGURATOR_HOST') ?: '', ); } } ``` Register it in `Pyz\Client\ProductConfiguration\ProductConfigurationDependencyProvider::getProductConfigurationRequestExpanderPlugins()`. {% info_block infoBox "Multiple configurators" %} If your shop has several configurators, route by `configuratorKey` inside `expand()`: read `$productConfiguratorRequestTransfer->getProductConfiguratorRequestDataOrFail()->getConfiguratorKey()` and map each key to its host. {% endinfo_block %} ### Content Security Policy The shop redirects to the configurator host through a form submit, so the configurator host must be allowlisted in the `form-action` directive of the `Content-Security-Policy` header. Add a `SecurityHeaderExpanderPlugin`: ```php // src/Pyz/Yves/WaterTreatmentConfiguratorPageExample/Plugin/Application/WaterTreatmentConfiguratorSecurityHeaderExpanderPlugin.php public function expand(array $securityHeaders): array { $securityHeaders['Content-Security-Policy'] = str_replace( 'form-action', sprintf('form-action %s', $this->createConfiguratorUrl()), $securityHeaders['Content-Security-Policy'] ?? '', ); return $securityHeaders; } ``` Register it in `Pyz\Yves\Application\ApplicationDependencyProvider`. ## 5. Allow the configurator key in the shop By default, the configuration widgets and the gateway page accept only the configurator key shipped with the feature. Override `getSupportedConfiguratorKeys()` to add your key in each place a customer can configure or reconfigure a product: - `Pyz\Yves\ProductConfiguratorGatewayPage\ProductConfiguratorGatewayPageConfig` — the **Configure** button on the Product Details page. - `Pyz\Yves\ProductConfigurationCartWidget\ProductConfigurationCartWidgetConfig` — reconfiguring from the cart. - `Pyz\Yves\ProductConfigurationShoppingListWidget\ProductConfigurationShoppingListWidgetConfig` — reconfiguring from a shopping list. ```php public function getSupportedConfiguratorKeys(): array { return [ WaterTreatmentConfiguratorPageExampleConfig::WATER_TREATMENT_CONFIGURATOR_KEY, ]; } ``` ## 6. Render the saved configuration After a configuration is saved, the shop displays it on the Storefront and in the Back Office. Provide a render-strategy plugin for each location, returning the display data and a template path. Implement one plugin per widget: | Location | Widget | Plugin interface | |---|---|---| | Product Details page | `ProductConfigurationWidget` | `ProductConfigurationRenderStrategyPluginInterface` | | Cart | `ProductConfigurationCartWidget` | `CartProductConfigurationRenderStrategyPluginInterface` | | Shopping list | `ProductConfigurationShoppingListWidget` | `ShoppingListItemProductConfigurationRenderStrategyPluginInterface` | | Order (Storefront) | `SalesProductConfigurationWidget` | `SalesProductConfigurationRenderStrategyPluginInterface` | | Order (Back Office) | `SalesProductConfigurationGui` | `SalesProductConfigurationRenderStrategyPluginInterface` | Each Yves plugin implements the widget-specific render-strategy interface (for example, `CartProductConfigurationRenderStrategyPluginInterface` for the cart widget), matches the configurator key in `isApplicable()`, and in `getTemplate()` renders the `options-list` view from the module theme: ```php public function isApplicable(ProductConfigurationInstanceTransfer $productConfigurationInstance): bool { return $productConfigurationInstance->getConfiguratorKey() === WaterTreatmentConfiguratorPageExampleConfig::WATER_TREATMENT_CONFIGURATOR_KEY; } public function getTemplate(ProductConfigurationInstanceTransfer $productConfigurationInstance): ProductConfigurationTemplateTransfer { return (new ProductConfigurationTemplateTransfer()) ->setData(json_decode($productConfigurationInstance->getDisplayDataOrFail(), true) ?? []) ->setModuleName('WaterTreatmentConfiguratorPageExample') ->setTemplateType('view') ->setTemplateName('options-list'); } ``` The Back Office (Zed) plugin renders a presentation partial of the module: ```php return (new SalesProductConfigurationTemplateTransfer()) ->setData(json_decode($itemTransfer->getSalesOrderItemConfigurationOrFail()->getDisplayDataOrFail(), true) ?? []) ->setTemplatePath('@WaterTreatmentConfiguratorPageExample/_partials/order-item-configuration.twig'); ``` Provide the templates in your module. The Storefront `options-list` view renders the display data as a collapsible list: {% raw %} ```twig {# src/Pyz/Yves/WaterTreatmentConfiguratorPageExample/Theme/default/views/options-list/options-list.twig #} {% extends model('template') %} {% define data = { listItems: {}, } %} {% block body %} {% include molecule('collapsible-list') with { data: { listItems: data.listItems, }, } only %} {% endblock %} ``` {% endraw %} The Back Office partial renders the first three attributes, with the rest collapsed behind a **Show more** toggle: {% raw %} ```twig {# src/Pyz/Zed/WaterTreatmentConfiguratorPageExample/Presentation/_partials/order-item-configuration.twig #}
{% for key, configuration in data | slice(0, 3) %}

{{ key }}: {{ configuration }}

{% endfor %} {% if data | length > 3 %} {{ 'Show more' | trans }} {{ 'Show less' | trans }} {% endif %} ``` {% endraw %} Register each plugin in the corresponding widget's `DependencyProvider` (for example, `Pyz\Yves\ProductConfigurationCartWidget\ProductConfigurationCartWidgetDependencyProvider`). ## 7. Mark products as configurable A regular product becomes configurable when a configuration is imported for it. Import a `product_configuration.csv` file that maps the concrete SKU to your configurator key: ```csv concrete_sku,configurator_key,is_complete,default_configuration,default_display_data IWT-SYSTEM-1,WATER_TREATMENT_CONFIGURATOR,0,, ``` - `is_complete` — whether the imported configuration is complete. If `0`, the customer must open the configurator and save a configuration before purchasing. See [Complete and incomplete configuration](/docs/pbc/all/product-information-management/{{page.version}}/base-shop/feature-overviews/configurable-product-feature-overview/configurable-product-feature-overview.html#complete-and-incomplete-configuration). - `default_configuration` / `default_display_data` — optional [preconfigured parameter values](/docs/pbc/all/product-information-management/{{page.version}}/base-shop/feature-overviews/configurable-product-feature-overview/configurable-product-feature-overview.html#preconfigured-parameter-values). Add the import to your data import configuration: ```yaml - data_entity: product-configuration source: data/import/.../product_configuration.csv ``` ## Verify the integration 1. Build the configurator frontend app and clear the cache (`console cache:empty-all`). 2. Import a configurable product. 3. On the Product Details page of the product, click **Configure** — you must be redirected to the configurator host. 4. Select a configuration and submit — you must be redirected back to the shop with the configuration applied. 5. Add the product to the cart, reconfigure it from the cart, and place an order — the configuration must be displayed on the cart, order, and in the Back Office. ## Related documents - [Configurable Product feature overview](/docs/pbc/all/product-information-management/{{page.version}}/base-shop/feature-overviews/configurable-product-feature-overview/configurable-product-feature-overview.html) - [Configuration process flow of configurable products](/docs/pbc/all/product-information-management/{{page.version}}/base-shop/feature-overviews/configurable-product-feature-overview/configuration-process-flow-of-configurable-product.html) - [Install the Product Configuration feature](/docs/pbc/all/product-information-management/{{page.version}}/base-shop/install-and-upgrade/install-features/install-the-product-configuration-feature.html)

Configuration process flow of configurable products

Tue, 16 Jun 2026 14:58:00 +0000

The configuration process of a configurable product consists of eight phases illustrated in the following flow chart:

Product configuration data flow on the product details page

When configuration starts on Yves, from the product details page (PDP), the product configuration data flow consists of the following phases.

Phase 1

A customer is on a PDP—the page with the product configuration.
The product configuration can be a complete configuration or use an incomplete pre-configuration defined by the shop owner.
The product configuration can be taken from two sources:
- A session for complete configuration.
- Key-value store (Redis or Valkey) for the pre-configuration.

The following table shows the configuration data that is stored in the Session and Storage.

PARAMETER	VALUE	COMMENTS
`ProductConfigurationInstance.isComplete`	`true` or `false`	Sensitive data.
`ProductConfigurationInstance.displayData`	Some text of JSON blob—for example, `{"Flow Rate":"10 m³/h","Filtration Type":"Reverse Osmosis","Tank Material":"SS316L"}`
`ProductConfigurationInstance.configuratorKey`	`WATER_TREATMENT_CONFIGURATOR`
`ProductConfigurationInstance.configuration`	`{"flowRate":"10","filtration":"reverse_osmosis","tank":"ss316l"}`	Sensitive data.

The framework generates a back URL that points to the gateway page with the following parameters:

PARAMETER	VALUE	COMMENT
`sourceType`	`pdp`, `cart-page`	Defines the page type where the configurator request is started. Resolves the `backUrl`, when the configurator response is processed.
`SKU`	`some_sku`
`Quantity`	`2`

The following table contains request parameters, which the plugin adds to the request:

PARAMETER	VALUE
`idCustomer`	`DE-1`
`localeName`	`de_DE`
`storeName`	`DE`
`currencyCode`	`EUR`
`priceMode`	`NET_MODE` or `GROSS_MODE`
`backUrl`	`https://SOME_URL`

Phase 2

The customer clicks the configuration button, and the request is redirected to the gateway page with a given product configuration using a GET method.

Phase 3

The configuration data is read from the session or storage for the given SKU.
A plugin that handles the request is selected based on the configurator type.
The plugin expands the request with additional necessary data:

store, locale, currency, customer, price mode.
backUrl—based on the referer header.

The plugin generates the URL that points to the configurator page together with all of the necessary data.

Phase 4

The request comes from the gateway to the configurator index.php.
The configurator handles the request by creating a new session and saving the request’s data there.
The configurator responds with a redirect URL that contains what session ID needs to be picked up.
The request comes from the gateway to the configurator index.php to pick up a session.
The response redirects the customer to the configurator page by a GET request using a secured connection.

Phase 5

The customer is on the configurator page.
The configurator page is rendered based on the data in the session.
The customer does the configuration and submits the configuration form.
The configurator redirects the customer to the gateway page with configuration data.

PARAMETER	VALUE	COMMENT
`ProductConfigurationInstance.prices`	`{{"EUR":{"GROSS_MODE":{"DEFAULT":30000}},{"NET_MODE":{"DEFAULT": 25000}},"priceData":{"volume_prices":[{"quantity": 5,"net_price": 28500,"gross_price": 29000}]}}`	Sensitive data.
`ProductConfigurationInstance.isComplete`	`true`	Sensitive data.
`ProductConfigurationInstance.availableQuantity`	`2`
`ProductConfigurationInstance.displayData`	Some text of JSON blob—for example, `{"Flow Rate":"10 m³/h","Filtration Type":"Reverse Osmosis","Tank Material":"SS316L"}`
`ProductConfigurationInstance.configuration`	`{"flowRate":"10","filtration":"reverse_osmosis","tank":"ss316l"}`	Sensitive data.
`idCustomer`	`DE-1`
sourceType	SOURCE_TYPE_PDP, SOURCE_TYPE_CART, SOURCE_TYPE_WISHLIST_DETAIL, …
`SKU`	`some_sku`
`timestamp`	`1231313123123`
`CheckSum`	It’s an encrypted value of the `CheckSum`. It must be based on the all requested parameters and must have the same order for decryption.

Phase 6

The customer finishes the configuration and clicks a button that creates an AJAX POST request with the data to the configurator page (self).
In the backend, the response is prepared according to the public data API from the configurator to Spryker.
In the backend, a CheckSum is prepared based on the response data, which is encrypted with a shared key and returns these as the AJAX response.
On the configurator page, the framework puts data to a hidden form and submits the form, which points to the gateway page.
After the successful configuration, the customer is redirected to the configurator gateway with a configuration response.
The gateway URL does not equal the back URL; it’s a fixed, known URL.

Phase 7

The gateway page receives data.
The data is checked through the execution of the validator plugins stack for received data.

If validation is not successful, the request is redirected to the backUrl without saving the configuration. A warning message is displayed.
If the validation part is successful, the configuration is saved to the session.

All applicable plugins that can handle the configurator response are executed. A plugin that applies to the PDP source type resolves the back URL according to the response data.

Phase 8

The customer is redirected back to the PDP.

Product configuration data flow on the Cart page

When configuration starts on Yves, from the Cart page, the product configuration data flow consists of the following phases:

Phase 1

The customer is on the Cart page—the page with items that contains the product configuration.
The product configuration can be already complete or not.
The item product configuration can be taken from one source only: Quote.
The framework generates the URL that points to the gateway page with the following parameters.

PARAMETER	VALUE	COMMENT
`ProductConfigurationInstance.displayData`	Some text of JSON blob—for example, `{"Flow Rate":"10 m³/h","Filtration Type":"Reverse Osmosis","Tank Material":"SS316L"}`
`ProductConfigurationInstance.configuration`	`{"flowRate":"10","filtration":"reverse_osmosis","tank":"ss316l"}`	Sensitive data.
`ProductConfigurationInstance.configuratorKey`	`WATER_TREATMENT_CONFIGURATOR`
`ProductConfigurationInstance.isComplete`	`true` or `false`	Sensitive data.
`backUrl`	`https://some.url`	Sensitive data.
`SubmitUrl`	`https://some.url`	Sensitive data.
sourceType	SOURCE_TYPE_PDP, SOURCE_TYPE_CART, SOURCE_TYPE_WISHLIST_DETAIL, …
`SKU`	`some_sku`
`Quantity`	`2`
`ItemGroupKey`	`some_key`

Phase 2

The customer clicks the configuration button.
The form request is redirected to the gateway page with a given product configuration using the GET method.

Phase 3

The configuration data is read from the quote for the given ItemGroupKey and SKU.
A plugin that handles the request is selected based on the configurator type.
The plugin expands the request with additional necessary data:

store, locale, currency, customer, price mode.
CheckSum—calculates the CRC32 polynomial of a request data as a string.
timestamp—the timestamp when the request is created.
backUrl—based on the Referer header.

The plugin generates the URL that points to the configurator page together with all the necessary data.

Phase 4

Redirects the customer to the configurator page using the GET request.

Phase 5

The customer is on the configurator page.
The customer does the configuration.
Submits the configuration form.
The configurator has to redirect to the gateway page with configuration data.

PARAMETER	VALUE	COMMENT
`ProductConfigurationInstance.prices`	`{"EUR":{"GROSS_MODE":{"DEFAULT":30000}},{"NET_MODE":{"DEFAULT": 25000}},"priceData":{"volume_prices":[{"quantity": 5,"net_price": 28500,"gross_price": 29000}]}}`	Sensitive data.
`ProductConfigurationInstance.isComplete`	`1`	Sensitive data.
`ProductConfigurationInstance.availableQuantity`	`2`
`ProductConfigurationInstance.displayData`	Some text of JSON blob—for example, `{"Flow Rate":"10 m³/h","Filtration Type":"Reverse Osmosis","Tank Material":"SS316L"}`
`ProductConfigurationInstance.configuration`	`{"flowRate":"10","filtration":"reverse_osmosis","tank":"ss316l"}`	Sensitive data.
`ProductConfigurationInstance.timestamp`	`10312313135234`	Sensitive data, a certain configuration must be valid only a certain amount of the time given.
`sourceType`	`SOURCE_TYPE_PDP`, `SOURCE_TYPE_CART`, `SOURCE_TYPE_WISHLIST_DETAIL`, …
`SKU`	`some_sku`
itemGroupKey	`some_group_key`

Phase 6

After the successful configuration, the customer is redirected to the configurator gateway with a configuration response.
The gateway URL is not the same as the back URL; it’s a fixed known URL.

Phase 7

The gateway page receives data.
The data is checked through the execution of the validator plugins stack for received data.

If validation is not successful, the request is redirected to backUrl without saving the configuration. A warning message is displayed.
If validation is successful, the framework updates the cart item configuration in the cart.

All applicable plugins that can handle the configurator response are executed. A plugin that applies to the cart page source type resolves the back URL according to the response data.

Phase 8

The customer is redirected back to the Cart page.

Configurable Product feature overview

Tue, 16 Jun 2026 14:58:00 +0000

The Configurable Product feature introduces a new type of product, a configurable product, that customers can customize.

The feature lets you sell complex products with modular designs or services. For example, if you sell clothes, your customers can define the material and color and add their names to the product. Or if you are selling a service, you can allow them to select a preferred date and time for the service delivery.

Configurable product

A configurable product is a product that customers can customize based on the parameters provided in a product configurator.

For example, if you are selling an industrial water treatment system, before purchasing it, customers can configure parameters such as the flow rate, filtration type, and tank material.

Configuring a configurable product

To configure a product, a customer opens a product configurator from the Product Details page by clicking the Configure button. They are then redirected back to the Product Details page and can add the configured product to the wishlist or cart.

After adding a configurable product to the cart, a customer can change the product configuration from the Cart page.

Creating configurable products

Configurable products are created in two steps:

A Back Office user creates regular products, or a developer imports them. See Creating an abstract product to learn how they create products in the Back Office or File details: product_concrete.csv to learn about the file they import.
A developer converts regular products into configurable products by importing configuration parameters. See File details: product_concrete_pre_configuration.csv to learn about the file they import.

Managing configurable products

A Back Office user can add configurable products as regular products to pages, categories, and content items.

They can see which products are configurable in the product catalog and edit them as regular products. However, a Back Office user cannot change configuration parameters.

In the orders, a Back Office user can see which products are configurable. They can also see the configuration of each product, but they cannot change the selected parameters.

Product configurator

A product configurator is a tool that lets customers customize the product parameters provided by the shop owner or product manufacturer.

You can create a product configurator as a part of your shop or integrate a third-party one. The feature is shipped with an example product configurator. The example product configurator allows configuring the parameters of an industrial water treatment system, such as Flow Rate, Filtration Type, Tank Material, Control System, Inlet Connection, and Power Supply.

How a Spryker shop interacts with a product configurator

A Spryker shop interacts with product configurators using parameters. When a customer is redirected from a Spryker shop to the configurator page, the shop passes the customer and product parameters. When the customer is redirected back to the shop, the configurator passes the updated parameters back.

The behavior of the configurator is based on the parameters passed by a shop. For example, a shop passes the store_name parameter. If a customer is redirected from a US store, the language of the configurator is English. Also, the shop passes the URL of the page the customer is redirected from. After the customer saves the configuration, the configurator uses this URL to redirect them back to the same page.

The selected configuration is also passed back to the shop as parameters. The shop uses the parameters to display the selected configuration on all related pages and process the order with the product.

Parameter types

There are two parameter types: configuration parameters and display parameters.

Configuration parameters are used by shops to interact with product configurators.

Display parameters are used to display product configuration on the Storefront and in the Back Office.

Display parameter values are usually converted from configuration parameter values to show data in a user-friendly format. For example, a product configurator passes the configuration parameter to a shop: "filtration": "reverse_osmosis". Since, in the configurator, reverse_osmosis stands for the human-readable option Reverse Osmosis, the shop displays Filtration Type: Reverse Osmosis.

Availability calculation in a product configurator

The availability of a configurable product is based on the selected configuration.

A customer selects the quantity of a product in a configurator or a shop. If a configurator allows them to select a product quantity, it passes the specified quantity to the shop as a parameter. Otherwise, it passes the availability as a parameter, and they select the product quantity in the shop.

If a configurator does not pass availability, regular product availability is used.

Price calculation in a product configurator

The price of a configurable product is based on the selected configuration. When a customer chooses a configuration, the product’s price in the selected configuration is displayed. After they save the configuration, the product price in the selected configuration is passed to the shop. The customer is redirected back to the shop where they can purchase the product for the price.

If the configurator does not provide a price, a regular product price is used.

Complete and incomplete configuration

When importing configurable products, a developer defines if the configuration is complete for each product.

If the configuration is complete, on the Product details page, a customer sees a message that the configuration is complete. By default, the message is followed by the first three descriptive attributes set in the configurator. Under the attributes, the Show and Hide buttons let the customer expand and collapse the remaining attributes to review them. The customer can purchase the product without again opening the configurator and selecting parameters, if they determine the configuration is complete.

If the configuration is not complete, on the Product details page, a customer sees a message that the configuration needs to be completed. To purchase the product, they open the configurator and select a configuration. However, they can add a product with an incomplete configuration to a wishlist. In this scenario, they can finish the configuration from the Wishlist page.

Even if all the parameter values are preconfigured, but the configuration is not complete, a customer has to open the configurator and save the configuration. They are not required to change the preconfigured values, though.

Request for Quote with a configurable product

The information in the Complete and incomplete configuration section applies to Quotation Process & RFQ functionalities. A customer can only request a quote for a product with a complete configuration.

Shopping List with a configurable product

The information in the Complete and incomplete configuration section applies to the Shopping List functionality. A customer can add products with the complete or incomplete configuration.

Wish List with a configurable product

The information in the Complete and incomplete configuration section applies to the Wish List functionality. A customer can add products with the complete or incomplete configuration.

Preconfigured parameter values

When a developer creates configurable products by importing them, they can preconfigure parameter values. If customers choose to configure such a product, they start with the preconfigured parameter values and can change them.

If a developer also defines that the configuration of such a product is complete, a customer sees the preconfigured parameter values on the Product details page. They can add the product to the cart without adjusting the configuration.

If a developer defines that the configuration of such a product needs to be completed, on the Product details page a customer does not see the preconfigured parameter values. However, they are still assigned to the product. The customer has to configure the product, but they can keep the same preconfigured parameter values.

Configurable product on the Storefront

Customers configure a product on the Storefront as follows:

INSTALLATION GUIDES	MIGRATION GUIDES	DATA IMPORT	REFERENCES
Install the Product feature	Upgrade the ProductConfiguration module	File details product_concrete_pre_configuration.csv	Configuration process flow of Configurable Product
Install the Product Configuration Glue API	Upgrade the ProductConfigurationStorage module		Create a product configurator
	Upgrade the ProductConfigurationsPriceProductVolumesRestApi module
	Upgrade the ProductConfigurationsRestApi module
	Upgrade the ProductConfigurationWidget module
	Upgrade the ProductConfiguratorGatewayPage module

Troubleshooting API Platform

Tue, 16 Jun 2026 12:18:37 +0000

This document provides solutions to common issues when working with API Platform in Spryker. ## Generation issues ### Resources not generating **Symptom:** Running `docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate` completes but no resources are created. **Possible causes:** 1. **Schema file location is incorrect** ```bash ❌ src/Pyz/Glue/Customer/api/customers.resource.yml ✅ src/Pyz/Glue/Customer/resources/api/backend/customers.resource.yml ``` 2. **API type not configured** Check `config/{APPLICATION}/packages/spryker_api_platform.php`: ```php $containerConfigurator->extension('spryker_api_platform', [ 'api_types' => [ 'backend', // Must match directory name ], ]); ``` 3. **Bundle not registered** Verify `config/{APPLICATION}/bundles.php` includes: ```php SprykerApiPlatformBundle::class => ['all' => true], ``` **Solution:** ```bash # Debug to see what's being discovered docker/sdk cli glue api:debug --list # Check schema validation docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --validate-only # Force regeneration docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --force ``` ### Schema validation errors **Symptom:** Generation fails with schema validation errors. **Common errors:** ```bash # Error: Invalid operation type ❌ operations: - type: CREATE ✅ operations: - type: Post # Error: Invalid property type ❌ type: int ✅ type: integer # Error: Missing resource name ❌ resource: shortName: customers ✅ resource: name: Customers shortName: customers ``` **Solution:** 1. Check schema against examples in documentation 2. Use `--validate-only` flag for detailed validation: ```bash docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --validate-only ``` 3. Inspect merged schema: ```bash docker/sdk cli glue api:debug resource-name --show-merged ``` ## Runtime issues ### Provider/Processor not found **Symptom:** ```bash Error: Class "Pyz\Glue\Customer\Api\Backend\Provider\CustomerBackendProvider" not found ``` **Possible causes:** 1. Class doesn't exist or namespace is wrong 2. Not registered in the Dependency Injection container 3. Typo in the schema file **Solution:** 1. Verify the class exists and namespace matches: ```php namespace Pyz\Glue\Customer\Api\Backend\Provider; class CustomerBackendProvider implements ProviderInterface ``` 2. Ensure services are auto-discovered in `ApplicationServices.php`: ```php $services->load('Pyz\\Glue\\', '../../../src/Pyz/Glue/'); ``` 3. Check class name in the resource schema file of the module matches exactly: ```yaml provider: "Pyz\\Glue\\Customer\\Api\\Backend\\Provider\\CustomerBackendProvider" ``` ### Validation not working **Symptom:** API accepts invalid data despite validation rules. **Possible causes:** 1. Validation schema file not found 2. Wrong operation name in validation schema 3. Validation groups not matching **Solution:** 1. Ensure validation file exists: ```bash ✅ resources/api/backend/customers.validation.yml ``` 2. Match operation names to HTTP methods: ```yaml post: # For POST /customers email: - NotBlank patch: # For PATCH /customers/{id} email: - Optional: constraints: - Email ``` 3. Check generated resource class (for example `Generated\Api\Storefront\CustomersStorefrontResource`) has validation attributes: ```php #[Assert\NotBlank(groups: ['customers:create'])] #[Assert\Email(groups: ['customers:create'])] public ?string $email = null; ``` ### API documentation UI not displaying correctly **Symptom:** When accessing the root URL of your API application, you see: - Missing styles/CSS - Broken JavaScript functionality - Plain HTML without formatting - "Failed to load resource" errors in browser docker/sdk cli glue **Cause:** Assets were not installed after API Platform integration. **Solution:** Run the appropriate assets:install command for your application: ### For Glue application ```bash docker/sdk cli glue assets:install public/Glue/assets --symlink ``` ### For GlueStorefront ```bash docker/sdk cli GLUE_APPLICATION=GLUE_STOREFRONT glue assets:install public/GlueStorefront/assets/ --symlink ``` ### For GlueBackend ```bash docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue assets:install public/GlueBackend/assets/ --symlink ``` Then verify the documentation UI loads correctly by visiting the root URL: - Storefront: `https://glue-storefront.mysprykershop.com/` - Backend: `https://glue-backend.mysprykershop.com/` {% info_block warningBox "Required after integration" %} The `assets:install` command must be run after integrating API Platform and whenever API Platform assets are updated. This is a required step documented in [How to integrate API Platform](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html). {% endinfo_block %} ### 404 Not Found for API endpoints **Symptom:** API requests return 404. **Possible causes:** 1. Router not configured 2. Routes not loaded 3. Wrong URL format **Solution:** 1. Verify `SymfonyFrameworkRouterPlugin` is registered: ```php // RouterDependencyProvider protected function getRouterPlugins(): array { return [ new GlueRouterPlugin(), new SymfonyFrameworkRouterPlugin(), // Must be present ]; } ``` 2. Check API documentation for correct URLs: ```bash Storefront: https://glue-storefront.mysprykershop.com/ Backend: https://glue-backend.mysprykershop.com/ ``` The interactive API documentation is available at the root URL of each application. 3. Use correct URL format: ```bash ❌ /api/v1/customers ✅ /customers ``` ### Requests without an `Accept` header are rejected or return the wrong format **Symptom:** A client request that omits the `Accept` header — or sends only `Accept: */*` — returns `406 Not Acceptable`, or a response in a format other than the legacy `application/vnd.api+json`. The legacy Glue REST API silently accepted the same request and answered with `application/vnd.api+json`. **Cause:** API Platform runs content negotiation that requires a satisfiable `Accept` header and does not assume the legacy Glue default. This is a behavioral difference from the legacy Glue REST stack. **Solution:** 1. Upgrade `spryker/api-platform` to **1.15.0 or higher**. Its `AcceptHeaderFallbackSubscriber` restores the legacy behavior — a missing or `*/*` `Accept` header defaults to `application/vnd.api+json`: ```bash composer update spryker/api-platform --with-dependencies ``` 2. If you cannot upgrade, send an explicit `Accept` header from the client: ```bash curl -H "Accept: application/vnd.api+json" https://glue-backend.mysprykershop.com/customers ``` ### Pagination not working **Symptom:** All results returned instead of paginated response. **Solution:** 1. Enable pagination in the schema file of the defining module: ```yaml resource: paginationEnabled: true paginationItemsPerPage: 10 ``` 2. Return `PaginatorInterface` from provider: ```php use ApiPlatform\State\Pagination\TraversablePaginator; return new TraversablePaginator( new \ArrayObject($results), $currentPage, $itemsPerPage, $totalItems ); ``` 3. Use pagination query parameters: ```bash GET /customers?page=2&itemsPerPage=20 ``` ### Client cannot change items per page **Symptom:** The `itemsPerPage` query parameter is ignored. **Solution:** Enable client-side items-per-page control and set a maximum limit in the resource schema: ```yaml resource: paginationEnabled: true paginationItemsPerPage: 10 paginationClientItemsPerPage: true paginationMaximumItemsPerPage: 100 ``` Without `paginationClientItemsPerPage: true`, the `itemsPerPage` query parameter has no effect. The `paginationMaximumItemsPerPage` option prevents clients from requesting excessively large pages. ### Client cannot disable pagination **Symptom:** The `pagination=false` query parameter is ignored and results are still paginated. **Solution:** Enable client-side pagination control in the resource schema: ```yaml resource: paginationClientEnabled: true ``` Without `paginationClientEnabled: true`, the `pagination` query parameter has no effect. For a full reference of all pagination options, see [Resource Schemas — Pagination](/docs/dg/dev/architecture/api-platform/resource-schemas.html#pagination). ## Dependency Injection issues ### Services not autowired **Symptom:** ```bash Cannot autowire service "CustomerBackendProvider": argument "$customerFacade" references class "CustomerFacadeInterface" but no such service exists. ``` **Solution:** 1. Register facade in the respective applications `ApplicationServices.php`: ```php use Pyz\Zed\Customer\Business\CustomerFacadeInterface; use Pyz\Zed\Customer\Business\CustomerFacade; $services->set(CustomerFacadeInterface::class, CustomerFacade::class); ``` 2. Ensure constructor uses interface type hints: ```php public function __construct( private CustomerFacadeInterface $customerFacade, // ✅ Interface ) {} ``` ## Performance issues ### Slow API responses **Symptom:** API endpoints respond slowly. **Solution:** 1. Enable Symfony cache: ```bash docker/sdk cli glue cache:warmup ``` 2. Use pagination for collections 3. Optimize database queries in Provider 4. Use API Platform's built-in caching features ## Development tips ### Debugging schema merging See which schemas contribute to final resource: ```bash docker/sdk cli glue api:debug customers --api-type=backend --show-sources ``` Output: ```bash Source Files (priority order): ✓ vendor/spryker/customer/resources/api/backend/customers.resource.yml (CORE) ✓ src/SprykerFeature/CRM/resources/api/backend/customers.resource.yml (FEATURE) ✓ src/Pyz/Glue/Customer/resources/api/backend/customers.resource.yml (PROJECT) ``` ### Inspecting generated code View the generated resource class: ```bash cat src/Generated/Api/Backend/CustomersBackendResource.php ``` Check for: - Correct property types - Validation attributes - API Platform metadata ### Testing with dry-run Preview generation without writing files: ```bash docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --dry-run ``` ## Getting help If you encounter issues not covered here: 1. **Check logs:** ```bash tail -f var/log/application.log tail -f var/log/exception.log ``` 2. **Enable debug mode:** ```php // config/{APPLICATION}/packages/spryker_api_platform.php $containerConfigurator->extension('spryker_api_platform', [ 'debug' => true, ]); ``` 3. **Validate environment:** ```bash php -v # Check PHP version (8.3+) composer show | grep api-platform docker/sdk cli glue debug:container | grep -i api ``` 4. **Common error patterns:** | Error | Likely cause | Solution | |-------|--------------|----------| | `Class not found` | Autoloading issue | Run `composer dump-autoload` | | `Service not found` | DI configuration | Check `ApplicationServices.php` | | `Route not found` | Router not configured | Add `SymfonyFrameworkRouterPlugin` | | `Validation failed` | Schema mismatch | Regenerate with `--force` | | `Cache is stale` | Outdated cache | Run `cache:clear` | | API docs UI broken/unstyled | Assets not installed | Run `docker/sdk cli glue /glue assets:install` | ## Next steps - [API Platform](/docs/dg/dev/architecture/api-platform.html) - Overview and concepts - [How to integrate API Platform](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html) - Setup guide - [API Platform Enablement](/docs/dg/dev/architecture/api-platform/enablement.html) - Creating resources - [Resource Schemas](/docs/dg/dev/architecture/api-platform/resource-schemas.html) - Resource schema reference - [Validation Schemas](/docs/dg/dev/architecture/api-platform/validation-schemas.html) - Validation schema reference - [API Platform Testing](/docs/dg/dev/architecture/api-platform/testing.html) - Testing guide

How to migrate to API Platform

Tue, 16 Jun 2026 12:18:37 +0000

{% info_block infoBox "Start here for batch migration" %} If you're migrating multiple modules in one go (the default), follow the [API Platform migration overview](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform-overview.html) first — it covers the shop-baseline upgrade, project-config checklist, and batch cleanup. This document is the per-module deep dive referenced from that overview. {% endinfo_block %} This document describes how to migrate existing Glue API resources to the API-Platform while maintaining backward compatibility. ## Overview Migrating from Glue API to API Platform provides several benefits: - **Schema-based development**: Define resources declaratively in YAML instead of PHP code - **Automatic OpenAPI documentation**: Interactive API docs generated from schemas - **Reduced boilerplate**: No need for manual resource builders, mappers, and route definitions - **Built-in validation**: Declarative validation rules with operation-specific constraints - **Standardized pagination**: Consistent pagination across all resources - **Better maintainability**: Clearer separation of concerns with providers and processors The recommended default is **batch migration** — migrating a group of related modules together, as described in the [API Platform migration overview](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform-overview.html). The per-resource steps below are the mechanics you apply to each resource *within* a batch; none of it breaks existing API consumers. ## Prerequisites Before migrating resources, ensure you have: - Integrated API Platform as described in [How to integrate API Platform](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html) - Configured router plugins in correct order (see below) - Tested that API Platform is working with at least one test resource ## Migration strategy and router setup This guide covers the mechanics of migrating a single resource. The overall strategy (batch migration is the default), the router-plugin ordering, and how routing flips between Glue and API Platform are owned by the [API Platform migration overview](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform-overview.html) — read it first. The steps below are what you apply to each resource within a batch. ## Migration process ### Step 1: Identify resources to migrate List all existing Glue resources in your application: Backend API resources are typically registered in: `\Pyz\Glue\GlueBackendApiApplication\GlueBackendApiApplicationDependencyProvider::getResourcePlugins()` Storefront API resources are typically registered in: `\Pyz\Glue\GlueApplication\GlueApplicationDependencyProvider::getResourceRoutePlugins()` Create a migration checklist: ```bash [ ] Customers resource [ ] Products resource [ ] Orders resource [ ] Cart resource [ ] Wishlist resource ... ``` {% info_block infoBox "Migration order recommendation" %} Start with simpler, read-only resources (GET operations only) before migrating complex resources with write operations and business logic. {% endinfo_block %} ### Step 2: Analyze existing Glue resource Before migrating, understand the existing resource structure. **Example: Existing Glue Customer Resource** 1. **Resource route plugin:** `src/Pyz/Glue/CustomersRestApi/Plugin/GlueApplication/CustomersResourceRoutePlugin.php` 2. **Resource class:** `src/Pyz/Glue/CustomersRestApi/Processor/Customer/CustomerReader.php` 3. **Attributes transfer:** `src/Generated/Shared/Transfer/RestCustomersAttributesTransfer.php` 4. **Operations supported:** - GET `/customers/{customerReference}` - Get single customer - GET `/customers` - Get customer collection - POST `/customers` - Create customer - PATCH `/customers/{customerReference}` - Update customer ### Step 3: Create API Platform schema Create the equivalent API Platform schema for the resource. **Map Glue concepts to API Platform:** | Glue API | API Platform | |---------------|--------------| | Resource class | Provider class | | Resource builder | Schema definition (YAML) | | Attributes transfer | Resource class (auto-generated) | | Reader | Provider | | Writer | Processor | | Resource route plugin | Operations in schema | | Relationship plugins | Properties in schema | **Create schema file:** `src/Pyz/Zed/Customer/resources/api/backend/customers.yml` ```yaml resource: name: Customers shortName: Customer description: "Customer resource for backend API" provider: "Pyz\\Glue\\Customer\\Api\\Backend\\Provider\\CustomerBackendProvider" processor: "Pyz\\Glue\\Customer\\Api\\Backend\\Processor\\CustomerBackendProcessor" paginationEnabled: true paginationItemsPerPage: 10 operations: - type: Post - type: Get - type: GetCollection - type: Patch properties: customerReference: type: string description: "A unique reference for a customer." writable: false identifier: true email: type: string description: "The email address of the customer." openapiContext: example: "john.doe@example.com" firstName: type: string description: "The first name of the customer." openapiContext: example: "John" lastName: type: string description: "The last name of the customer." openapiContext: example: "Doe" # Map all properties from RestCustomersAttributesTransfer ``` **Create validation schema:** `src/Pyz/Zed/Customer/resources/api/backend/customers.validation.yml` ```yaml post: email: - NotBlank: message: "Email is required" - Email: message: "Invalid email format" firstName: - NotBlank: message: "First name is required" lastName: - NotBlank: message: "Last name is required" patch: email: - Optional: constraints: - Email ``` ### Step 4: Implement Provider Create the Provider to handle read operations, reusing existing business logic. {% info_block infoBox "Reuse existing business logic" %} The Provider should primarily call existing Facade methods. This ensures consistency and reduces duplication of business logic. {% endinfo_block %} `src/Pyz/Zed/Customer/Api/Backend/Provider/CustomerBackendProvider.php` ```php getCustomer($uriVariables['customerReference']); } return $this->getCustomers($context); } private function getCustomer(string $customerReference): ?CustomersBackendResource { // Reuse existing Glue logic $customerTransfer = $this->customerFacade->findCustomerByReference($customerReference); if ($customerTransfer === null) { return null; } // Map transfer to API Platform resource $resource = new CustomersBackendResource(); $resource->fromArray($customerTransfer->toArray()); return $resource; } private function getCustomers(array $context): TraversablePaginator { $filters = $context['filters'] ?? []; $page = (int) ($filters['page'] ?? 1); $itemsPerPage = (int) ($filters['itemsPerPage'] ?? 10); // Reuse existing facade method $customerCollection = $this->customerFacade->getCustomerCollection($page, $itemsPerPage); $resources = []; foreach ($customerCollection->getCustomers() as $customerTransfer) { $resource = new CustomersBackendResource(); $resource->fromArray($customerTransfer->toArray()); $resources[] = $resource; } return new TraversablePaginator( new \ArrayObject($resources), $page, $itemsPerPage, $customerCollection->getTotalCount() ); } } ``` ### Step 5: Implement Processor Create the Processor to handle write operations. {% info_block infoBox "Reuse existing business logic" %} The Processor should primarily call existing Facade methods. This ensures consistency and reduces duplication of business logic. {% endinfo_block %} `src/Pyz/Zed/Customer/Api/Backend/Processor/CustomerBackendProcessor.php` ```php createCustomer($data); } if ($operation instanceof Patch) { return $this->updateCustomer($data, $uriVariables['customerReference']); } return null; } private function createCustomer(CustomersBackendResource $resource): CustomersBackendResource { $customerTransfer = new CustomerTransfer(); $customerTransfer->fromArray($resource->toArray(), true); // Reuse existing facade method $customerResponseTransfer = $this->customerFacade->addCustomer($customerTransfer); $result = new CustomersBackendResource(); $result->fromArray($customerResponseTransfer->getCustomerTransfer()->toArray()); return $result; } private function updateCustomer(CustomersBackendResource $resource, string $customerReference): CustomersBackendResource { $customerTransfer = new CustomerTransfer(); $customerTransfer->fromArray($resource->toArray(), true); $customerTransfer->setCustomerReference($customerReference); // Reuse existing facade method $customerResponseTransfer = $this->customerFacade->updateCustomer($customerTransfer); $result = new CustomersBackendResource(); $result->fromArray($customerResponseTransfer->getCustomerTransfer()->toArray()); return $result; } } ``` ### Step 6: Generate API Platform resource Generate the backend resource class from the schema: ```bash docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate # Verify generation ls -la src/Generated/Api/Backend/CustomersBackendResource.php ``` ### Step 7: Test the API Platform endpoint Test that the new endpoint works correctly: ```bash # Test single resource curl -X GET http://glue-backend.eu.spryker.local/customers/DE--1 # Test collection curl -X GET http://glue-backend.eu.spryker.local/customers?page=1&itemsPerPage=10 # Test create curl -X POST http://glue-backend.eu.spryker.local/customers \ -H "Content-Type: application/json" \ -d '{"email":"test@example.com","firstName":"John","lastName":"Doe"}' # Test update curl -X PATCH http://glue-backend.eu.spryker.local/customers/DE--1 \ -H "Content-Type: application/json" \ -d '{"firstName":"Jane"}' ``` Verify: - ✅ Responses match expected format - ✅ Validation rules work correctly - ✅ Error handling is appropriate - ✅ Pagination works for collections - ✅ OpenAPI documentation is generated at root URL `/` ### Step 8: Run existing Glue API tests Ensure backward compatibility by running existing tests: ```bash # Run Glue API tests vendor/bin/codecept run -c tests/PyzTest/Glue/CustomersRestApi # Or specific test vendor/bin/codecept run -c tests/PyzTest/Glue/CustomersRestApi/RestApi/CustomerRestApiCest ``` All existing tests should still pass because: - `GlueRouterPlugin` is checked first - Existing Glue endpoints still work - No breaking changes to consumers ### Step 9: Remove Glue resource files {% info_block warningBox "Plugin removal is the migration switch" %} The actual switch from Glue REST to API Platform for this module is removing its `*ResourceRoutePlugin` from the project-level dependency provider (shown below). The optional `excludedPathFragments` setting in `spryker_api_platform.php` controls schema generation only — it does not flip routing. The `spryker/-rest-api` composer package may stay installed; it simply no longer serves routes once the plugin is unregistered. {% endinfo_block %} Once the API Platform endpoint is working and tested, remove the old Glue files: ```bash # Remove resource route plugin rm src/Pyz/Glue/CustomersRestApi/Plugin/GlueApplication/CustomersResourceRoutePlugin.php # Remove processor classes rm -rf src/Pyz/Glue/CustomersRestApi/Processor/ # Update dependency provider to remove plugin registration ``` **Update GlueApplicationDependencyProvider:** `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php` ```php protected function getResourceRoutePlugins(): array { return [ // new CustomersResourceRoutePlugin(), // ← Remove this line new ProductsResourceRoutePlugin(), new OrdersResourceRoutePlugin(), // ... keep other plugins ]; } ``` ### Step 10: Verify migration After removing Glue resource files: ```bash # Clear caches console cache:clear # Test that API Platform endpoint still works curl -X GET http://glue-backend.eu.spryker.local/customers/DE--1 # Verify OpenAPI docs include the resource curl http://glue-backend.eu.spryker.local/docs.json | jq '.paths' # Check the interactive documentation at root URL # Visit: http://glue-backend.eu.spryker.local/ ``` ### Step 11: Repeat for remaining resources Repeat steps 2-10 for each resource in your migration checklist: ```bash [✓] Customers resource ← Migrated [ ] Products resource ← Next [ ] Orders resource [ ] Cart resource [ ] Wishlist resource ... ``` ## Migration comparison ### Before: Glue API ```bash Request: GET /customers/DE--1 ↓ GlueRouterPlugin ↓ CustomersResourceRoutePlugin ↓ CustomerReaderInterface ↓ CustomerFacade ↓ RestResourceBuilder ↓ Response: RestCustomersAttributesTransfer ``` ### After: API Platform ```bash Request: GET /customers/DE--1 ↓ SymfonyFrameworkRouterPlugin ↓ API Platform Router ↓ CustomerBackendProvider ↓ CustomerFacade (same!) ↓ CustomersBackendResource ↓ Response: JSON (auto-serialized) ``` ## Key differences | Aspect | Glue API | API Platform | |--------|----------|--------------| | **Definition** | PHP classes & plugins | YAML schemas | | **Routing** | ResourceRoutePlugin | Schema operations | | **Reading data** | Reader classes | Provider classes | | **Writing data** | Writer classes | Processor classes | | **Validation** | Manual in reader/writer | Declarative in validation schema | | **Documentation** | Separate OpenAPI schema | Auto-generated from schema | | **Response building** | Manual RestResourceBuilder | Auto-serialization | | **Relationships** | Relationship plugins | Schema properties | | **File count** | ~10-15 files per resource | ~3-5 files per resource | ## Troubleshooting migration ### Both old and new endpoints respond **Symptom:** Both Glue and API Platform endpoints return responses. **Cause:** Different URLs are being used. Check if they're actually the same: ```bash # Glue endpoint GET /customers/DE--1 # API Platform endpoint GET /customers/DE--1 # Check URL prefixes in configuration ``` **Solution:** Ensure URLs match exactly. API Platform resources use `shortName` for URL generation. ### API Platform endpoint returns 404 during migration **Symptom:** After creating schema and generating resource, endpoint returns 404. **Possible causes:** 1. Router order is wrong (SymfonyFrameworkRouterPlugin before GlueRouterPlugin) 2. Cache not cleared 3. Resource not generated **Solution:** ```bash # Check router order in RouterDependencyProvider # Should be: GlueRouterPlugin, then SymfonyFrameworkRouterPlugin # Clear caches console cache:clear # Regenerate resources docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate # Verify generated file exists ls -la src/Generated/Api/Backend/CustomersBackendResource.php ``` ### Different response format between Glue and API Platform **Symptom:** API Platform returns different JSON structure than Glue. **Cause:** Glue uses JSON:API format, API Platform uses JSON-LD by default which is configurable and depending on your needs you can migrate to JSON-LD as well or stay with the JSON API format. API-Platform covers this possibility for you **Solution:** This is expected. You have three options: 1. **Accept the difference** (recommended): Update API consumers to handle both formats during migration 2. **Configure API Platform format**: Customize serialization to match the Glue format. See [Serialization](/docs/dg/dev/architecture/api-platform/serialization.html) for how API Platform serialization works and how to register custom normalizers. 3. **Use content negotiation**: Support both formats based on `Accept` header ### Business logic differs between implementations **Symptom:** API Platform endpoint behaves differently than a Glue endpoint. **Cause:** Provider/Processor uses different facade methods or has different logic. **Solution:** Review and ensure both use the same facade methods: ```php // Glue Reader $customerReader->readCustomer($customerReference); ↓ calls $this->customerFacade->findCustomerByReference($customerReference); // API Platform Provider $this->customerFacade->findCustomerByReference($customerReference); // ← Same method! ``` ## Best practices ### 1. Keep batches small Batch migration is the default (see the [migration overview](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform-overview.html)), but keep each batch small and ship it before starting the next — don't try to migrate every resource in one go. For example: ```bash Sprint 1: Customers, Products (read-only) Sprint 2: Orders, Cart Sprint 3: Wishlist, Checkout ``` ### 2. Keep business logic in facades Don't duplicate business logic in Providers/Processors: ```php // ❌ Bad: Logic in Provider private function getCustomer(string $reference): ?CustomersBackendResource { $customer = $this->repository->findByReference($reference); // ... business logic here } // ✅ Good: Delegate to Facade private function getCustomer(string $reference): ?CustomersBackendResource { $customerTransfer = $this->customerFacade->findCustomerByReference($reference); return $this->mapToResource($customerTransfer); } ``` ### 3. Use toArray/fromArray for mapping Leverage generated `toArray()` and `fromArray()` methods: ```php // Easy mapping between Transfer and Resource $resource = new CustomersBackendResource(); $resource->fromArray($customerTransfer->toArray()); ``` ### 4. Test thoroughly before removing Glue code - Run all existing tests - Perform manual testing - Check with API consumers - Monitor production traffic ### 5. Document breaking changes If response formats differ, document changes for API consumers: ```markdown ## Migration Notice: Customers API The `/customers` endpoint is being migrated to API-Platform. ### Changes: - Response format: JSON:API → JSON-LD - Date format: unix timestamp → ISO 8601 - Error format: JSON:API errors → RFC 7807 Problem Details ### Timeline: - Old endpoint: Supported until 2026-12-31 - New endpoint: Available now - Deprecation: Old endpoint will return deprecation headers starting 2026-09-01 ``` ## Next steps - [API Platform](/docs/dg/dev/architecture/api-platform.html) - Architecture overview - [API Platform Enablement](/docs/dg/dev/architecture/api-platform/enablement.html) - Creating resources - [Resource Schemas](/docs/dg/dev/architecture/api-platform/resource-schemas.html) - Resource Schemas - [Validation Schemas](/docs/dg/dev/architecture/api-platform/validation-schemas.html) - Validation Schemas - [Troubleshooting](/docs/dg/dev/architecture/api-platform/troubleshooting.html) - Common issues

Spryker Documentation

Transfer data between Yves and Zed

Identity Access Management

Enable Dynamic Multistore

Prerequisites

Enable Dynamic Multistore

Check if Dynamic Multistore is enabled

Disable Dynamic Multistore

Architecture as Code

Why Architecture as Code

Core Principles

Concepts and Choices

arc42

C4 Model

Mermaid and PlantUML

What Comes Out of the Box

Folder Structure

Diagram Organization and Best Practices

Templates and Guidelines

Getting Help

Resources

Common Questions

Smart PIM

Create a product configurator

Configuration process flow of configurable products

Product configuration data flow on the product details page

Phase 1

Phase 2

Phase 3

Phase 4

Phase 5

Phase 6

Phase 7

Phase 8

Product configuration data flow on the Cart page

Phase 1

Phase 2

Phase 3

Phase 4

Phase 5

Phase 6

Phase 7

Phase 8

Configurable Product feature overview

Configurable product

Configuring a configurable product

Creating configurable products

Managing configurable products

Product configurator

How a Spryker shop interacts with a product configurator

Parameter types

Availability calculation in a product configurator

Price calculation in a product configurator

Complete and incomplete configuration

Request for Quote with a configurable product

Shopping List with a configurable product

Wish List with a configurable product

Preconfigured parameter values

Configurable product on the Storefront

Related Developer documents

Troubleshooting API Platform

How to migrate to API Platform