Spryker Documentation

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

Migration status - Glue API to API Platform

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

This document tracks Spryker's migration of API-providing modules to the **API Platform** (built on Symfony and the API Platform library). Use it to plan upgrades and check the current status of every module. {% info_block infoBox "Looking for the integration guide?" %} This page does **not** describe how to integrate API Platform into your project. For step-by-step integration instructions, see: - [Migrate to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform.html) - [Integrate API Platform](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html) - [Integrate API Platform security](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform-security.html) - [API Platform architecture](/docs/dg/dev/architecture/api-platform.html) {% endinfo_block %} ## How to migrate a module The end-to-end migration steps — upgrade the module, confirm configuration, flip routing, verify, and clean up — are owned by the [API Platform migration overview](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform-overview.html). This page only tracks **which** modules are available on API Platform and their status. ## Status legend | Status | Meaning | |---|---| | Migrated | Module is available on API Platform and production-ready. | | Planned | Module is scheduled or queued for migration to API Platform. | ## Storefront API modules All StorefrontAPI and Extension-only StorefrontAPI modules. Migrated modules are listed first. | Module | Category | Status | Released In | Requires | Key endpoints | |---|---|---|---|---|---| | ContentProductAbstractListsRestApi | StorefrontAPI | Migrated | 1.4.0 | ProductsRestApi | GET /content-product-abstract-lists/{id}
GET /content-product-abstract-lists/{id}/abstract-products | | MerchantOpeningHoursRestApi | StorefrontAPI | Migrated | 1.2.0 | — | GET /merchants/{id}/merchant-opening-hours | | MerchantCategoriesRestApi | Extension-only StorefrontAPI | Migrated | 1.2.0 | MerchantsRestApi | (extension-only) | | MerchantProductOffersRestApi | StorefrontAPI | Migrated | 2.2.0 | — | GET /concrete-products/{id}/product-offers
GET /product-offers/{id} | | MerchantProductOfferServicePointAvailabilitiesRestApi | Extension-only StorefrontAPI | Migrated | 0.4.0 | ProductOfferServicePointAvailabilitiesRestApi | (extension-only) | | MerchantsRestApi | StorefrontAPI | Migrated | 1.2.0 | — | GET /merchants
GET /merchants/{id}
GET /merchants/{id}/merchant-addresses | | OrderPaymentsRestApi | StorefrontAPI | Migrated | 1.2.0 | — | POST /order-payments | | PaymentsRestApi | StorefrontAPI | Migrated | 1.7.0 | — | POST /payments
POST /payment-cancellations
POST /payment-customers | | ProductAvailabilitiesRestApi | StorefrontAPI | Migrated | 4.4.0 | ProductsRestApi | GET /abstract-products/{id}/abstract-product-availabilities
GET /concrete-products/{id}/concrete-product-availabilities | | ProductOfferAvailabilitiesRestApi | StorefrontAPI | Migrated | 1.3.0 | — | GET /product-offers/{id}/product-offer-availabilities | | ProductOfferServicePointAvailabilitiesRestApi | StorefrontAPI | Migrated | 1.2.0 | — | POST /product-offer-service-point-availabilities | | ProductOfferPricesRestApi | StorefrontAPI | Migrated | 2.5.0 | — | GET /product-offers/{id}/product-offer-prices | | ProductPricesRestApi | StorefrontAPI | Migrated | 1.12.0 | ProductsRestApi | GET /abstract-products/{id}/abstract-product-prices
GET /concrete-products/{id}/concrete-product-prices | | ProductTaxSetsRestApi | StorefrontAPI | Migrated | 2.3.0 | — | GET /abstract-products/{id}/product-tax-sets | | ProductsRestApi | StorefrontAPI | Migrated | 2.17.0 | — | GET /abstract-products/{id}
GET /concrete-products/{id} | | ShipmentTypeProductOfferServicePointAvailabilitiesRestApi | Extension-only StorefrontAPI | Migrated | 1.2.0 | ProductOfferServicePointAvailabilitiesRestApi | (extension-only) | | StoresApi | StorefrontAPI | Migrated | 1.3.0 | — | GET /stores | | AgentAuthRestApi | StorefrontAPI | Migrated | 1.3.0 | — | POST /agent-access-tokens
POST /agent-customer-impersonation-access-tokens
GET /agent-customer-search | | AlternativeProductsRestApi | StorefrontAPI | Migrated | 1.3.0 | ProductsRestApi | GET /abstract-products/{id}/related-products
GET /concrete-products/{id}/abstract-alternative-products
GET /concrete-products/{id}/concrete-alternative-products | | AuthRestApi | StorefrontAPI | Migrated | 2.17.0 | — | POST /token
POST /access-tokens
POST /refresh-tokens
DELETE /refresh-tokens/{id} | | AvailabilityNotificationsRestApi | StorefrontAPI | Migrated | 1.4.0 | — | POST /availability-notifications
DELETE /availability-notifications/{id}
GET /my-availability-notifications
GET /customers/{id}/availability-notifications | | CartCodesRestApi | StorefrontAPI | Migrated | 1.7.0 | CartsRestApi | POST /carts/{id}/cart-codes
DELETE /carts/{id}/cart-codes/{id}
POST /guest-carts/{id}/cart-codes
DELETE /guest-carts/{id}/cart-codes/{id} | | CartPermissionGroupsRestApi | StorefrontAPI | Migrated | 1.4.0 | — | GET /cart-permission-groups
GET /cart-permission-groups/{id} | | CartReorderRestApi | StorefrontAPI | Migrated | 1.3.0 | CartsRestApi | POST /cart-reorder | | CartsRestApi | StorefrontAPI | Migrated | 5.25.0 | — | GET,POST /carts
GET,PATCH,DELETE /carts/{id}
POST /carts/{id}/items
PATCH,DELETE /carts/{id}/items/{id}
GET /guest-carts
GET,PATCH /guest-carts/{id}
POST /guest-carts/{id}/guest-cart-items
PATCH,DELETE /guest-carts/{id}/guest-cart-items/{id}
GET /customers/{id}/carts | | CatalogSearchRestApi | StorefrontAPI | Migrated | 2.13.0 | — | GET /catalog-search
GET /catalog-search-suggestions | | CategoriesRestApi | StorefrontAPI | Migrated | 1.9.0 | — | GET /category-trees
GET /category-nodes/{id} | | CheckoutRestApi | StorefrontAPI | Migrated | 3.14.0 | CartsRestApi | POST /checkout-data
POST /checkout | | CmsPagesRestApi | StorefrontAPI | Migrated | 1.2.0 | — | GET /cms-pages
GET /cms-pages/{id} | | CompaniesRestApi | StorefrontAPI | Migrated | 1.5.0 | — | GET /companies
GET /companies/{id} | | CompanyBusinessUnitAddressesRestApi | StorefrontAPI | Migrated | 1.4.0 | — | GET /company-business-unit-addresses
GET /company-business-unit-addresses/{id} | | CompanyBusinessUnitsRestApi | StorefrontAPI | Migrated | 1.6.0 | — | GET /company-business-units
GET /company-business-units/{id} | | CompanyRolesRestApi | StorefrontAPI | Migrated | 1.3.0 | — | GET /company-roles
GET /company-roles/{id} | | CompanyUserAuthRestApi | StorefrontAPI | Migrated | 2.3.0 | — | POST /company-user-access-tokens | | CompanyUsersRestApi | StorefrontAPI | Migrated | 2.11.0 | — | GET /company-users
GET /company-users/{id} | | ConfigurableBundleCartsRestApi | StorefrontAPI | Migrated | 1.2.0 | CartsRestApi | POST /carts/{id}/configured-bundles
PATCH,DELETE /carts/{id}/configured-bundles/{id}
POST,PATCH,DELETE /guest-carts/{id}/guest-configured-bundles/{id} | | ConfigurableBundlesRestApi | StorefrontAPI | Migrated | 1.3.0 | — | GET /configurable-bundle-templates
GET /configurable-bundle-templates/{id} | | ContentBannersRestApi | StorefrontAPI | Migrated | 2.4.0 | — | GET /content-banners/{id} | | CustomerAccessRestApi | StorefrontAPI | Migrated | 1.3.0 | — | GET /customer-access | | CustomersRestApi | StorefrontAPI | Migrated | 1.28.0 | — | GET,POST /customers
GET,PATCH,DELETE /customers/{id}
GET,POST /customers/{id}/addresses
GET,PATCH,DELETE /customers/{id}/addresses/{id}
POST /customer-forgotten-password
PATCH /customer-restore-password/{id}
PATCH /customer-password/{id}
POST /customer-confirmation | | DiscountPromotionsRestApi | Extension-Only-StorefrontAPI | Migrated | 1.6.0 | CartCodesRestApi, CartsRestApi | (extension-only) | | EntityTagsRestApi | Extension-only StorefrontAPI | Migrated | 1.1.0 | — | (extension-only) | | GiftCardsRestApi | Extension-only StorefrontAPI | Migrated | 1.2.0 | — | (extension-only) | | HealthCheck | StorefrontAPI | Migrated | 1.1.0 | — | GET /health-check | | MerchantProductOfferShoppingListsRestApi | Extension-only StorefrontAPI | Migrated | 1.2.0 | — | (extension-only) | | MerchantProductOfferWishlistRestApi | Extension-only StorefrontAPI | Migrated | 1.3.0 | WishlistsRestApi | (extension-only) | | MerchantProductShoppingListsRestApi | Extension-only StorefrontAPI | Migrated | 1.2.0 | — | (extension-only) | | MerchantProductsRestApi | Extension-only StorefrontAPI | Migrated | 1.1.0 | CartsRestApi | (extension-only) | | MerchantSalesReturnsRestApi | Extension-only StorefrontAPI | Migrated | 1.1.0 | — | (extension-only) | | MerchantShipmentsRestApi | Extension-only StorefrontAPI | Migrated | 0.1.1 | ShipmentsRestApi | (extension-only) | | MultiCartsRestApi | Extension-only StorefrontAPI | Migrated | 1.1.0 | CartsRestApi | (extension-only) | | MultiFactorAuth | StorefrontAPI | Migrated | 2.5.0 | — | GET /multi-factor-auth-types, POST /multi-factor-auth-trigger, POST /multi-factor-auth-type-activate, POST /multi-factor-auth-type-verify, POST /multi-factor-auth-type-deactivate | | NavigationsRestApi | StorefrontAPI | Migrated | 2.3.0 | — | GET /navigations/{id} | | OauthApi | StorefrontAPI | Migrated | 1.4.1 | — | POST /token | | OrderAmendmentsRestApi | Extension-only StorefrontAPI | Migrated | 1.2.0 | CartReorderRestApi, CartsRestApi, OrdersRestApi | (extension-only) | | OrdersRestApi | StorefrontAPI | Migrated | 4.14.0 | — | GET /orders
GET /orders/{orderReference}
GET /orders/{orderReference}/order-items/{uuid}
GET /customers/{customerReference}/orders | | PriceProductOfferVolumesRestApi | Extension-only StorefrontAPI | Migrated | 1.1.1 | ProductOfferPricesRestApi | (extension-only) | | PriceProductVolumesRestApi | Extension-only StorefrontAPI | Migrated | 1.2.0 | ProductPricesRestApi | (extension-only) | | ProductAttributesRestApi | StorefrontAPI | Migrated | 1.3.0 | — | GET /product-management-attributes
GET /product-management-attributes/{id} | | ProductBundleCartsRestApi | Extension-only StorefrontAPI | Migrated | 1.4.0 | CartsRestApi, ShipmentsRestApi | (extension-only) | | ProductBundlesRestApi | StorefrontAPI | Migrated | 1.2.0 | OrdersRestApi | GET /concrete-products/{id}/bundled-products | | ProductConfigurationShoppingListsRestApi | Extension-only StorefrontAPI | Migrated | 1.2.0 | ShoppingListsRestApi | (extension-only) | | ProductConfigurationWishlistsRestApi | Extension-only StorefrontAPI | Migrated | 1.3.0 | WishlistsRestApi | (extension-only) | | ProductConfigurationsPriceProductVolumesRestApi | Extension-only StorefrontAPI | Migrated | 1.1.0 | ProductConfigurationShoppingListsRestApi, ProductConfigurationWishlistsRestApi, ProductConfigurationsRestApi | (extension-only) | | ProductConfigurationsRestApi | Extension-only StorefrontAPI | Migrated | 1.2.0 | CartsRestApi, OrdersRestApi, ProductsRestApi | (extension-only) | | ProductDiscontinuedRestApi | Extension-only StorefrontAPI | Migrated | 1.1.1 | ProductsRestApi | (extension-only) | | ProductImageSetsRestApi | StorefrontAPI | Migrated | 1.3.0 | ProductsRestApi | GET /abstract-products/{id}/abstract-product-image-sets
GET /concrete-products/{id}/concrete-product-image-sets | | ProductLabelsRestApi | StorefrontAPI | Migrated | 1.5.0 | — | GET /product-labels/{id} | | ProductMeasurementUnitsRestApi | StorefrontAPI | Migrated | 1.3.0 | — | GET /product-measurement-units/{id}
GET /concrete-products/{id}/sales-units | | ProductOfferSalesRestApi | Extension-only StorefrontAPI | Migrated | 1.2.0 | — | (extension-only) | | ProductOfferShoppingListsRestApi | Extension-only StorefrontAPI | Migrated | 1.2.0 | — | (extension-only) | | ProductOffersRestApi | Extension-only StorefrontAPI | Migrated | 1.1.0 | ProductsRestApi | (extension-only) | | ProductOptionsRestApi | Extension-only StorefrontAPI | Migrated | 1.5.0 | CartsRestApi, OrdersRestApi, ProductsRestApi, QuoteRequestsRestApi | (extension-only) | | ProductReviewsRestApi | StorefrontAPI | Migrated | 1.3.0 | — | GET,POST /abstract-products/{id}/product-reviews
GET /abstract-products/{id}/product-reviews/{id} | | QuoteRequestAgentsRestApi | StorefrontAPI | Migrated | 0.4.2 | QuoteRequestsRestApi | GET,POST /agent-quote-requests
GET,PATCH /agent-quote-requests/{id}
POST /agent-quote-requests/{id}/agent-quote-request-cancel
POST /agent-quote-requests/{id}/agent-quote-request-revise
POST /agent-quote-requests/{id}/agent-quote-request-send-to-customer | | QuoteRequestsRestApi | StorefrontAPI | Migrated | 0.2.2 | CartsRestApi | GET,POST /quote-requests
GET,PATCH /quote-requests/{id}
POST /quote-requests/{id}/quote-request-cancel
POST /quote-requests/{id}/quote-request-revise
POST /quote-requests/{id}/quote-request-send-to-user
POST /quote-requests/{id}/quote-request-convert-to-quote | | RelatedProductsRestApi | StorefrontAPI | Migrated | 1.5.0 | ProductsRestApi | GET /abstract-products/{id}/related-products | | SalesOrderThresholdsRestApi | Extension-only StorefrontAPI | Migrated | 1.1.0 | CartsRestApi, CheckoutRestApi | (extension-only) | | SalesReturnsRestApi | StorefrontAPI | Migrated | 1.3.0 | — | GET /return-reasons
GET,POST /returns
GET /returns/{id} | | SecurityBlockerRestApi | Extension-only StorefrontAPI | Migrated | 1.1.0 | — | (extension-only) | | ServicePointCartsRestApi | Extension-only StorefrontAPI | Migrated | 1.1.0 | CheckoutRestApi | (extension-only) | | ServicePointsRestApi | StorefrontAPI | Migrated | 1.2.0 | — | GET /service-points
GET /service-points/{id}
GET /service-points/{id}/service-point-addresses/{id} | | SharedCartsRestApi | StorefrontAPI | Migrated | 1.4.0 | — | POST /carts/{id}/shared-carts
PATCH,DELETE /shared-carts/{id} | | ShipmentTypeServicePointsRestApi | Extension-only StorefrontAPI | Migrated | 1.1.0 | CheckoutRestApi, ServicePointsRestApi, ShipmentTypesRestApi, ShipmentsRestApi | (extension-only) | | ShipmentTypesRestApi | StorefrontAPI | Migrated | 1.2.0 | — | GET /shipment-types
GET /shipment-types/{id} | | ShipmentsRestApi | Extension-only StorefrontAPI | Migrated | 1.16.0 | CheckoutRestApi, OrdersRestApi, QuoteRequestsRestApi | (extension-only) | | ShoppingListsRestApi | StorefrontAPI | Migrated | 1.5.0 | — | GET,POST /shopping-lists
GET,PATCH,DELETE /shopping-lists/{id}
POST /shopping-lists/{id}/shopping-list-items
PATCH,DELETE /shopping-lists/{id}/shopping-list-items/{id} | | UpSellingProductsRestApi | StorefrontAPI | Migrated | 1.4.0 | CartsRestApi, ProductsRestApi | GET /carts/{id}/up-selling-products
GET /guest-carts/{id}/up-selling-products | | UrlsRestApi | StorefrontAPI | Migrated | 1.2.0 | — | GET /url-resolver | | Vertex | StorefrontAPI | Migrated | 1.2.0 | — | POST /tax-id-validate | | WishlistsRestApi | StorefrontAPI | Migrated | 1.8.0 | — | GET,POST /wishlists
GET,PATCH,DELETE /wishlists/{id}
POST /wishlists/{id}/wishlist-items
PATCH,DELETE /wishlists/{id}/wishlist-items/{id} | ### Backward-compatible extension modules (no migration required) The following modules are not migrated to API Platform and do not need to be. They expose no API resource of their own — they only contribute plugins (mappers and expanders) that are consumed in a backward-compatible way by both the legacy Glue REST API and the API Platform resources of the host module they extend. Because they carry no standalone resource, they have no "Released In" version. | Module | Plugin provided | Consumed by | |---|---|---| | DiscountsRestApi | DiscountsRestQuoteRequestAttributesExpanderPlugin | QuoteRequestsRestApi | | MerchantRelationshipProductListsRestApi | CustomerProductListCustomerExpanderPlugin | CustomersRestApi | | OmsRestApi | OmsRestOrderItemsAttributesMapperPlugin | OrdersRestApi | ## Backend API modules All BackendAPI modules tracked in the migration scope. | Module | Category | Status | Released In | Requires | Key endpoints | |---|---|---|---|---|---| | CartNotesBackendApi | Extension-Only BackendAPI | Planned | — | SalesOrdersBackendApi | (extension-only) | | CategoriesBackendApi | BackendAPI | Planned | — | — | GET,POST /categories
GET,PATCH /categories/{id} | | DynamicEntityBackendApi | BackendAPI | Planned | — | — | GET,POST,PATCH,PUT /dynamic-entity/{entity-name} (~62 auto-generated entity endpoints) | | OauthBackendApi | BackendAPI | Planned | — | — | POST /token | | PickingListsBackendApi | BackendAPI | Planned | — | — | GET /picking-lists
GET /picking-lists/{id}
PATCH /picking-lists/{id}/picking-list-items/{id}
POST /start-picking | | PickingListsUsersBackendApi | Extension-Only BackendAPI | Planned | — | PickingListsBackendApi, UsersBackendApi | (extension-only) | | PickingListsWarehousesBackendApi | Extension-Only BackendAPI | Planned | — | PickingListsBackendApi, WarehousesBackendApi | (extension-only) | | ProductAttributesBackendApi | BackendAPI | Planned | — | — | GET,POST /product-attributes
GET,PATCH /product-attributes/{id} | | ProductImageSetsBackendApi | BackendAPI | Planned | — | — | GET /concrete-product-image-sets | | ProductPackagingUnitsBackendApi | Extension-Only BackendAPI | Planned | — | PickingListsBackendApi | (extension-only) | | ProductsBackendApi | BackendAPI | Planned | — | — | GET,POST /product-abstract
DELETE,GET,PATCH /product-abstract/{id} | | PushNotificationsBackendApi | BackendAPI | Planned | — | — | GET,POST /push-notification-providers
PATCH,DELETE /push-notification-providers/{id}
POST /push-notification-subscriptions | | SalesOrdersBackendApi | BackendAPI | Planned | — | — | GET /sales-orders | | ServicePointsBackendApi | BackendAPI | Planned | — | — | GET,POST /service-points
GET,PATCH /service-points/{id}
GET,POST /service-point-addresses
PATCH /service-points/{id}/service-point-addresses/{id}
GET,POST /service-types
GET,PATCH /service-types/{id}
GET,POST /services
GET,PATCH /services/{id} | | ShipmentTypesBackendApi | BackendAPI | Planned | — | — | GET,POST /shipment-types
GET,PATCH /shipment-types/{id} | | ShipmentsBackendApi | BackendAPI | Planned | — | — | GET /sales-shipments | | StoresBackendApi | BackendAPI | Planned | — | — | GET,POST,PATCH /stores | | UsersBackendApi | BackendAPI | Planned | — | — | GET /users | | WarehouseOauthBackendApi | BackendAPI | Planned | — | — | POST /warehouse-tokens | | WarehouseUsersBackendApi | BackendAPI | Planned | — | — | GET,POST /warehouse-user-assignments
GET,PATCH,DELETE /warehouse-user-assignments/{id} | | WarehousesBackendApi | BackendAPI | Planned | — | — | GET /warehouses |

API Platform migration overview

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

This document walks through migrating an existing Spryker shop from Glue REST to API Platform. It covers the order to do things in: upgrade the migrated modules, confirm project configuration, batch-migrate, verify, then clean up. Module-by-module mechanics live in the [per-module guide](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform.html); project-level setup lives in the [integration guide](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html). ## What you're migrating to API Platform replaces the internal infrastructure that Glue REST uses to serve API endpoints. Externally, contracts remain backward-compatible — clients keep working. Internally: - **No more Controllers, Readers, or RestResourceBuilders.** Endpoint behavior is defined in YAML resource schemas plus a Provider (reads) and a Processor (writes). - **Routing happens via API Platform**, served through `SymfonyFrameworkRouterPlugin`. The `GlueRouterPlugin` continues to serve any modules that haven't been migrated yet — they coexist by router order. {% info_block infoBox "Migrated modules no longer rely on Controllers/Readers" %} Once a module is migrated, its endpoint wiring is the API Platform resource schema and the Provider/Processor pair — not a `*ResourceRoutePlugin` plus a `*Reader`. If you find both, you're mid-migration; finish the switch (Step 3) before considering that module done. {% endinfo_block %} {% info_block warningBox "One client-visible behavior change: the Accept header" %} Backward compatibility has one exception. Legacy Glue REST accepted requests that omitted the `Accept` header (or sent `*/*`) and answered with `application/vnd.api+json`. API Platform's content negotiation does not, so such clients can receive `406 Not Acceptable` or a response in a different format. `spryker/api-platform` **1.15.0+** restores the legacy fallback. See [Requests without an Accept header](/docs/dg/dev/architecture/api-platform/troubleshooting.html#requests-without-an-accept-header-are-rejected-or-return-the-wrong-format) in troubleshooting. {% endinfo_block %} ## Prerequisites Before starting the migration, confirm: - **Symfony Dependency Injection is in place.** See [How to upgrade to Symfony Dependency Injection](/docs/dg/dev/upgrade-and-migrate/upgrade-to-symfony-dependency-injection.html). - **API Platform is integrated** at the project level (bundles registered, project configuration applied, Symfony container compiled). See [How to integrate API Platform](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html). - **PHP 8.3+ and Symfony 6.4+.** - **You know which modules you're migrating.** The [Glue API to API Platform migration status page](/docs/dg/dev/architecture/api-platform/migrate-to-api-platform-status.html) lists every module, its migration status, and its prerequisites. - **Existing Glue API tests pass** on your current shop before you start changing anything. The cleanest signal that the migration is working is that those tests keep passing through every step. ## Step 1 — Upgrade the migrated modules A shop already lists its `spryker/*-rest-api` modules in the project `composer.json`, so upgrading them to versions that ship the API Platform schemas is a single pattern update: ```bash composer update "spryker/*-rest-api" --with-dependencies ``` {% info_block warningBox "Endpoints are NOT yet routed after Step 1" %} Updating the modules ships the API Platform resource schemas and the new Providers/Processors, but **all traffic still goes through the Glue plugins**. You will not see new behavior at this point — that's expected. Routing flips in Step 3, after the project configuration is in place and the Glue plugins are removed. {% endinfo_block %} ## Step 2 — Confirm project configuration API Platform must be integrated at the project level before any module can be served through it. This is the integration step, not part of the migration itself — follow [How to integrate API Platform](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html), which covers: - Registering the bundles in `config//bundles.php`. - The `spryker_api_platform.php` config (including `excludedPathFragments` for the modules you keep on Glue). - Wiring the router so `GlueRouterPlugin` and `SymfonyFrameworkRouterPlugin` coexist in the correct order. For the per-setting `api_platform.php` reference, see [API Platform Configuration](/docs/dg/dev/architecture/api-platform/configuration.html). For authentication and authorization, see [How to integrate API Platform Security](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform-security.html). ## Step 3 — Batch migration (default) The actual switch from Glue REST to API Platform for a given module is **removing that module's `*ResourceRoutePlugin` from the project-level dependency provider**. This is the single edit that flips routing. Edit the dependency provider for the stack the module belongs to: - Storefront API: `src/Pyz/Glue/GlueStorefrontApiApplication/GlueStorefrontApiApplicationDependencyProvider::getResourcePlugins()` - Backend API: `src/Pyz/Glue/GlueBackendApiApplication/GlueBackendApiApplicationDependencyProvider::getResourcePlugins()` - Combined Glue: `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider::getResourceRoutePlugins()` Remove the line that registers the migrated module's `*ResourceRoutePlugin`. Once removed, `GlueRouterPlugin` no longer finds a match for that resource and the request falls through to `SymfonyFrameworkRouterPlugin`, which serves it via API Platform. {% info_block warningBox "Plugin removal is the switch — not excludedPathFragments" %} `excludedPathFragments` in `spryker_api_platform.php` controls what the schema generator emits. It does **not** flip routing. A module stays on Glue as long as its `*ResourceRoutePlugin` is still registered in the project dependency provider, regardless of what `excludedPathFragments` says. The `spryker/-rest-api` composer package stays installed after you remove the plugin — it just no longer serves routes. {% endinfo_block %} ### Module dependency order Some modules cannot be migrated before their dependencies. The prerequisites for each module are tracked in the **Requires** column of the [migration status page](/docs/dg/dev/architecture/api-platform/migrate-to-api-platform-status.html) — migrate the listed prerequisites first (or in the same batch). For example, `ProductPricesRestApi` requires `ProductsRestApi`, so `ProductsRestApi` must be migrated first. ## Step 4 — Verify After the plugins are removed and the project configuration is in place, verify each migrated endpoint end-to-end. **Now** all migrated endpoints should work via API Platform. 1. **List API Platform resources** per stack: ```bash docker/sdk cli glue api:debug --list docker/sdk cli GLUE_APPLICATION=GLUE_STOREFRONT glue api:debug --list docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:debug --list ``` Expected: every resource belonging to a module you removed a `*ResourceRoutePlugin` for appears here under its corresponding stack. The list shows resource names, not module names. 2. **Run the existing Glue API test suite**. All tests should still pass — both the migrated endpoints (now served via API Platform) and any modules still on Glue: ```bash docker/sdk testing codecept run ``` 3. **Confirm OpenAPI is generated** at the root URL of each stack: - `https://glue./` - `https://glue-storefront./` - `https://glue-backend./` Each should render the interactive OpenAPI documentation, including the migrated resources. ## Step 5 — Cleanup Once a module is migrated and Step 4 is green, clean up the remaining Glue artifacts for it. 1. **Remove the module's `*ResourceRoutePlugin` registration** (done in Step 3) and any project-level Glue overrides for that module under `src/Pyz/Glue/RestApi/`. Many projects have no such directory; only remove what your project actually added. The migration itself lives in the `spryker/-rest-api` vendor package, which stays installed. 2. **Drop `GlueRouterPlugin`** from the router dependency provider — only when **every** module in the stack is migrated: `src/Pyz/Glue/Router/RouterDependencyProvider.php` ```php protected function getRouterPlugins(): array { return [ // new GlueRouterPlugin(), // ← Remove once no modules remain on Glue new SymfonyFrameworkRouterPlugin(), ]; } ``` 3. **Remove Glue-specific tests** that are no longer relevant. Replace with API Platform tests if coverage gaps remain. The endpoint URLs do not change — the migration is fully backward-compatible — so existing API consumers and integrations keep working without updates.

How to integrate API Platform

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

This document describes how to integrate API Platform into your Spryker application to enable schema-based API resource generation. If you're migrating an existing Spryker shop from the Glue REST stack, read the [API Platform migration overview](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform-overview.html) first. This integration guide is one step inside that larger flow. ## Prerequisites Before integrating API Platform, ensure you have: - Upgraded to Symfony Dependency Injection as described in [How to upgrade to Symfony Dependency Injection](/docs/dg/dev/upgrade-and-migrate/upgrade-to-symfony-dependency-injection.html) - PHP 8.3 or higher - Symfony 6.4 or higher components ## 1. Install the required modules To integrate API Platform, install the following modules: ```bash composer require spryker/api-platform:"^1.0.0" --update-with-dependencies ``` {% info_block infoBox "Target versions" %} For the list of currently migrated modules and their status, see the [Glue API to API Platform migration status page](/docs/dg/dev/architecture/api-platform/migrate-to-api-platform-status.html). Update your `spryker/*-rest-api` modules to a version that ships the endpoints you migrate. {% endinfo_block %} ## 2. Register bundles Register the required bundles in each application's bundle file — `config/Glue/bundles.php`, `config/GlueStorefront/bundles.php`, and `config/GlueBackend/bundles.php` are identical: ```php ['all' => true], SecurityBundle::class => ['all' => true], TwigBundle::class => ['all' => true], ApiPlatformBundle::class => ['all' => true], SprykerApiPlatformBundle::class => ['all' => true], ]; ``` {% info_block infoBox "SecurityBundle" %} The `SecurityBundle` enables authentication and authorization for API Platform resources using Bearer token (JWT) validation and security expressions. For detailed setup including firewall configuration, see [How to integrate API Platform Security](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform-security.html). {% endinfo_block %} ## 3. Configure API Platform Create a `spryker_api_platform.php` and an `api_platform.php` file in each application layer where you enable API Platform — `config/Glue/packages/`, `config/GlueStorefront/packages/`, and `config/GlueBackend/packages/`. At minimum, `spryker_api_platform.php` must set the application's `apiTypes()` — `['storefront']` for the Glue and GlueStorefront applications, `['backend']` for the GlueBackend application. For the full reference of both configuration files, every available setting, and links to the released demo-shop configurations, see [API Platform Configuration](/docs/dg/dev/architecture/api-platform/configuration.html). ## 4. Update Router Configuration Update the router dependency provider for each application where you want to enable API Platform routes. ### For Glue application `src/Pyz/Glue/Router/RouterDependencyProvider.php` ```php */ protected function getRouterPlugins(): array { return [ new GlueRouterPlugin(), // Existing Glue API router new SymfonyFrameworkRouterPlugin(), // Add this for API Platform routes ]; } } ``` {% info_block infoBox "Router order matters" %} The order of router plugins matters. The `SymfonyFrameworkRouterPlugin` must be added after existing router plugins to ensure the correct routing priority. The `GlueRouterPlugin` should remain the first in the list to handle existing and not yet migrated Glue API endpoints. When migrating existing Glue API endpoints to API Platform, you need to remove endpoints from the `GlueRouterPlugin` so that the `SymfonyFrameworkRouterPlugin` is used to resolve the route. To remove routes from the `GlueRouterPlugin` update the corresponding `GlueApplicationDependencyProvider`, `GlueBackendApiApplicationDependencyProvider`, or `GlueStorefrontApiApplicationDependencyProvider` and remove the resource route plugin for the route you currently migrate. {% endinfo_block %} ## 5. Generate API resources After configuration, generate your API resources from the schema files: ```bash # Generate resources for all configured API types docker/sdk cli glue api:generate ``` Target a specific application by prefixing with `GLUE_APPLICATION=GLUE_STOREFRONT` or `GLUE_APPLICATION=GLUE_BACKEND`. For the full set of generation and debug commands (single API type, `--dry-run`, `--validate-only`, schema inspection), see [Resource generation](/docs/dg/dev/architecture/api-platform.html#resource-generation) in the architecture guide. The generated resources are created in `src/Generated/Api/{ApiType}/`. ## 6. Install assets for the API Platform documentation interface Install the necessary assets for API Platform to function correctly: ### 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 ``` {% info_block warningBox "Required step" %} The `assets:install` command is required to copy the necessary assets (CSS, JavaScript, images) for the API Platform documentation interface. Without this step, the API documentation UI will not display correctly. {% endinfo_block %} ## 7. Clear caches After generation and asset installation, clear application caches: ```bash # Clear all caches console cache:clear # Build Symfony container cache console container:build ``` ## Verification To verify your integration: 1. **Debug available resources:** ```bash # List all API resources docker/sdk cli glue api:debug --list # Inspect specific resource docker/sdk cli glue api:debug access-tokens --api-type=storefront ``` 2. **Access API documentation:** - Glue: `https://glue.your-domain/` - GlueStorefront: `https://glue-storefront.your-domain/` - GlueBackend: `https://glue-backend.your-domain/` The interactive OpenAPI documentation interface will be displayed at the root URL of each application. Depending on the environment of the application (development or production), the documentation interface may be enabled or disabled by default. Currently, it is only enabled in development (docker.dev) environments. You can enable/disable this interface by configuring the settings in your `api_platform.php` configuration files. ## Next steps - [API Platform](/docs/dg/dev/architecture/api-platform.html) - Overview and concepts - [How to integrate API Platform Security](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform-security.html) - Authentication and authorization setup - [API Platform migration overview](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform-overview.html) - End-to-end migration walk-through - [Enablement](/docs/dg/dev/architecture/api-platform/enablement.html) - Create your first API resource - [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 - [Native API Platform Resources](/docs/dg/dev/architecture/api-platform/native-api-platform-resources.html) - Using native PHP attributes

API Platform Configuration

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

This page is the canonical reference for all API Platform configuration in Spryker. API Platform is configured through two PHP config files per application: the native api_platform.php (API Platform’s own options, with Spryker adaptations for PHP-based configuration and environment control) and Spryker’s spryker_api_platform.php (which drives schema generation). Both are documented below.

Configuration file locations

Each application layer carries two configuration files:

Application	Native API Platform config	Spryker generator config
Glue	`config/Glue/packages/api_platform.php`	`config/Glue/packages/spryker_api_platform.php`
GlueStorefront	`config/GlueStorefront/packages/api_platform.php`	`config/GlueStorefront/packages/spryker_api_platform.php`
GlueBackend	`config/GlueBackend/packages/api_platform.php`	`config/GlueBackend/packages/spryker_api_platform.php`

api_platform.php configures API Platform itself (Swagger, formats, pagination defaults, resource mapping paths). Documented under Native API Platform configuration below.
spryker_api_platform.php configures Spryker’s schema generator (which API types an application serves, where schemas are scanned, which modules stay on Glue). Documented under Resource generation configuration below.

Released configuration reference

The simplest starting point is a real, released configuration. The links below point to the B2B Demo Marketplace at the latest release (release-202604.0); check newer releases for updates.

Application	`api_platform.php`	`spryker_api_platform.php`
Glue	api_platform.php	spryker_api_platform.php
GlueStorefront	api_platform.php	spryker_api_platform.php
GlueBackend	api_platform.php	spryker_api_platform.php

Resource generation configuration (spryker_api_platform.php)

spryker_api_platform.php controls Spryker’s API Platform schema generator — it is separate from the native api_platform.php. Create one in each application layer where you enable API Platform. The files share the same shape; they differ only in apiTypes() and in the modules each application still serves via Glue.

Three settings:

apiTypes() — the API types this application serves: ['storefront'] for the Glue and GlueStorefront applications, ['backend'] for the GlueBackend application.
sourceDirectories() — where the generator scans for API Platform schemas. Optional; defaults to src/Spryker, src/SprykerFeature, and src/Pyz. Set it only if your schemas live somewhere else.
excludedPathFragments() — schema paths the generator skips. Use it to keep a module’s API Platform schemas hidden from the generator (for example, a module the project still serves via Glue). Each entry is matched as a substring of the full schema path.

excludedPathFragments does not switch routing

excludedPathFragments controls only what the schema generator emits. It does not flip routing. A module stays on Glue as long as its *ResourceRoutePlugin is registered in the project dependency provider. See Step 3 — Batch migration in the migration overview.

config/Glue/packages/spryker_api_platform.php (storefront example):

<?php

declare(strict_types = 1);

use Symfony\Config\SprykerApiPlatformConfig;

return static function (SprykerApiPlatformConfig $sprykerApiPlatform): void {
    $sprykerApiPlatform->apiTypes(['storefront']);

    // Keep these modules on the Glue REST stack by hiding their API Platform schemas from the generator.
    $sprykerApiPlatform->excludedPathFragments([
        'vendor/spryker/customer/src/Spryker/Customer/resources/api/',
        'vendor/spryker/store/src/Spryker/Store/resources/api/',
        'vendor/spryker/authentication/src/Spryker/Authentication/resources/api/',
    ]);
};

For the GlueBackend application, set apiTypes(['backend']) and list the modules that application still serves via Glue in excludedPathFragments().

Native API Platform configuration (api_platform.php)

api_platform.php configures API Platform itself. Spryker ships working defaults, so most projects only adjust a few options. The sections below cover the Spryker-specific adaptations and the settings you are most likely to change.

Spryker-specific differences

PHP configuration instead of YAML

Spryker uses PHP configuration with Symfony’s type-safe configuration objects instead of YAML files:

use Symfony\Config\ApiPlatformConfig;

return static function (ApiPlatformConfig $apiPlatform, string $env): void {
    // Configuration here
};

Environment variable for conditional settings

The configuration function receives an $env parameter for environment-specific behavior:

return static function (ApiPlatformConfig $apiPlatform, string $env): void {
    // Enable developer tools only in development
    if ($env === 'dockerdev') {
        $apiPlatform->enableSwagger(true);
        $apiPlatform->enableSwaggerUi(true);
        $apiPlatform->enableReDoc(true);
        $apiPlatform->enableDocs(true);
    }
};

Common environment values: prod, dev, dockerdev, test

Configuration examples

Disable SwaggerUI in production

Spryker shows the SwaggerUI only in development environments by default. This can be configured with:

if ($env === 'dockerdev') {
        $apiPlatform->enableSwagger(true);
        $apiPlatform->enableSwaggerUi(true);
        $apiPlatform->enableReDoc(true);
        $apiPlatform->enableDocs(true);
    }

Disable Doctrine integration

Spryker does not use Doctrine with API Platform:

$apiPlatform->doctrine()->enabled(false);
$apiPlatform->doctrineMongodbOdm()->enabled(false);

Configure resource mapping paths

Specify where API Platform discovers resource classes. By default, only the generated resource directory is configured:

$apiPlatform->mapping()->paths([
    '%kernel.project_dir%/src/Generated/Api/Backend'
]);

Add custom resource paths

To use native API Platform resources alongside generated resources, add your directories to the mapping paths:

$apiPlatform->mapping()->paths([
    '%kernel.project_dir%/src/Generated/Api/Backend',
    '%kernel.project_dir%/src/Pyz/Glue/*/Api/Backend/Resource',
]);

API Platform scans all configured paths for PHP classes with #[ApiResource] attributes. Generated and manually created resources coexist without conflict.

Keep the generated path

Always keep the src/Generated/Api/{ApiType} path in the list. Removing it disables all YAML-generated resources.

For a complete guide on creating native resources, see Native API Platform Resources.

Set pagination defaults

$apiPlatform->defaults()->paginationItemsPerPage(10);

$apiPlatform->collection()
    ->pagination()
        ->pageParameterName('page')
        ->itemsPerPageParameterName('itemsPerPage');

These global defaults apply to all resources. Individual resources can override pagination behavior using per-resource options such as paginationEnabled, paginationItemsPerPage, paginationMaximumItemsPerPage, paginationClientEnabled, and paginationClientItemsPerPage in their YAML schema files. See Resource Schemas — Pagination for details.

Configure supported formats

$apiPlatform->formats('jsonapi', ['mime_types' => ['application/vnd.api+json']]);
$apiPlatform->formats('jsonld', ['mime_types' => ['application/ld+json']]);
$apiPlatform->formats('xml', ['mime_types' => ['application/xml']]);

Configure security

Security is configured in a separate security.php file. For details, see How to integrate API Platform Security.

Complete configuration reference

For all available configuration options and their details, refer to the API Platform Symfony Configuration documentation.

The PHP method names in ApiPlatformConfig correspond directly to the YAML keys in the official documentation.

API Platform

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

Spryker’s API Platform integration provides schema-based API resource generation with automatic OpenAPI documentation. This allows you to define your API resources using YAML schemas and automatically generate fully functional API endpoints with validation, pagination, and serialization.

This document describes the API Platform architecture and how it integrates with Spryker.

What is API Platform

API Platform is a framework for building modern APIs based on web standards and best practices. In Spryker, it complements the existing Glue API infrastructure by providing:

Schema-based resource generation: Define resources in YAML, generate PHP classes automatically
Automatic OpenAPI documentation: Interactive API documentation generated from schemas
Built-in validation: Symfony Validator integration with operation-specific rules
Pagination support: Standardized pagination with configurable defaults
State management: Separate providers (read) and processors (write) for clean architecture

Read more about the API Platform project at api-platform.com.

Why Spryker is moving to API Platform

API Platform replaces Spryker-specific patterns for routing, authentication, and resource definition with industry-standard Symfony conventions, automatic OpenAPI schema generation, and a clean separation between resource schema, provider, and validation.

Aspect	Previous infrastructure	API Platform
Bootstrap	Spryker-specific application bootstrap	Symfony Kernel-based routing
Resource registration	Manual plugin registration in `GlueApplicationDependencyProvider`	Declarative YAML resource definitions (`*.resource.yml`)
Authentication	Custom flows per module	Standard OAuth2 / Symfony Security
Coupling	Tight coupling between resource and routing logic	Clean separation: provider + resource schema + validation
Testability	Complex to test and extend	Symfony-native, testable with standard PHPUnit patterns
OpenAPI	Manual / partial	Automatic OpenAPI schema generation

Architecture overview

Resource generation workflow

>Schema Files (YAML)
    ↓
Schema Discovery & Validation
    ↓
Multi-layer Schema Merging (Core → Feature → Project → [Code Buckets])
    ↓
Resource Class Generation
    ↓
API Platform Resource (with attributes)
    ↓
API Endpoints

Core components

1. Schema files

Resources are defined in YAML files located in module directories:

>src/Spryker/{Module}/resources/api/{api-type}/{resource-name}.resources.yml
src/Spryker/{Module}/resources/api/{api-type}/{resource-name}.validation.yml

Example resource schema src/Spryker/{Module}/resources/api/{api-type}/{resource-name}.resources.yml:

resource:
  name: Customers
  shortName: customers
  description: "Customer resource for backend API"

  provider: "Pyz\\Glue\\Customer\\Api\\Backend\\Provider\\CustomerBackendProvider"
  processor: "Pyz\\Glue\\Customer\\Api\\Backend\\Processor\\CustomerBackendProcessor"

  paginationEnabled: true

  operations:
    - type: Post
    - type: Get
    - type: GetCollection
    - type: Patch
    - type: Delete

  properties:
    email:
      type: string
      description: "Customer email address"
    customerReference:
      type: string
      identifier: true
      writable: false

Example validation schema src/Spryker/{Module}/resources/api/{api-type}/{resource-name}.validation.yml:

post:
  name:
    - NotBlank:
        message: First name is required
    - Length:
        min: 2
        max: 64
        minMessage: First name must be at least 2 characters
        maxMessage: First name cannot exceed 64 characters

patch:
  name:
    - Optional:
        constraints:
          - Length:
              min: 2
              max: 64
              minMessage: First name must be at least 2 characters
              maxMessage: First name cannot exceed 64 characters

2. Generated resources

The generator creates PHP classes with API Platform attributes:

src/Generated/Api/Backend/CustomersBackendResource.php

<?php

namespace Generated\Api\Backend;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\ApiProperty;
use Symfony\Component\Validator\Constraints as Assert;

#[ApiResource(
    operations: [new Post(), new Get(), new GetCollection(), new Patch(), new Delete()],
    shortName: 'customers',
    provider: CustomerBackendProvider::class,
    processor: CustomerBackendProcessor::class
)]
final class CustomersBackendResource
{
    #[ApiProperty(identifier: true, writable: false)]
    public ?string $customerReference = null;

    #[ApiProperty]
    #[Assert\NotBlank(groups: ['customers:create'])]
    #[Assert\Email(groups: ['customers:create'])]
    public ?string $email = null;

    // Getters, setters, toArray(), fromArray()...
}

3. State providers and processors

Detailed information about the API-Platform Provider and Resources can be found on the public docs:

Provider (read operations):

class CustomerBackendProvider implements ProviderInterface
{
    public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null
    {
        // Fetch and return data from your business layer
        return $customerResource;
    }
}

Processor (write operations):

class CustomerBackendProcessor implements ProcessorInterface
{
    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed
    {
        // Persist changes through your business layer
        return $updatedResource;
    }
}

API types

Any of the existing APIs can be extended using API Platform.

Spryker supports multiple API types for different use cases:

Glue API

This API is configured to serve the JSON:API format by default, which can be configured per project. Projects migrating their APIs can provide new APIs as well as supporting the existing ones while migrating.

API Type: storefront
Application: Glue
Base URL: http://glue.eu.spryker.local/ - Configurable per project
Use cases: Customer-facing APIs, mobile apps, PWAs

GlueStorefront API

Thie API is configured to serve the JSON+LD format by default, which can be configured per project.

API Type: storefront
Application: Glue
Base URL: http://glue-storefront.eu.spryker.local/ - Configurable per project
Use cases: Customer-facing APIs, mobile apps, PWAs

GlueBackend API

API Type: backend
Application: Zed
Base URL: http://glue-backend.eu.spryker.local/
Use cases: Admin panels, internal tools, ERP integrations

Merchant Portal API

API Type: merchant-portal
Application: MerchantPortal
Base URL: http://mp.glue.eu.spryker.local/
Use cases: Marketplace merchant interfaces
Example: /products

Multi-layer schema merging

One of the key features is support for multi-layer schema definitions that automatically merge:

Core layer (vendor/spryker):

resource:
  name: Customers
  properties:
    email:
      type: string

Feature layer (src/SprykerFeature):

resource:
  name: Customers
  properties:
    loyaltyPoints:
      type: integer

Project layer (src/Pyz):

resource:
  name: Customers
  properties:
    email:
      required: true  # Override core
    customField:
      type: string    # Project-specific

Result: A single merged resource with all properties, project code-bucket layer taking precedence.

Integration with Spryker architecture

Dependency Injection

API Platform fully integrates with Symfony Dependency Injection:

// config/Zed/ApplicationServices.php
$services->load('Pyz\\Zed\\', '../../../src/Pyz/Zed/');

Providers and Processors are automatically discovered and can use constructor injection:

class CustomerBackendProvider implements ProviderInterface
{
    public function __construct(
        private CustomerFacadeInterface $customerFacade,
        private CustomerRepositoryInterface $customerRepository,
    ) {}
}

Facade integration

Resources can leverage existing Spryker facades:

class CustomerBackendProcessor implements ProcessorInterface
{
    public function __construct(
        private CustomerFacadeInterface $customerFacade,
    ) {}

    public function process(mixed $data, Operation $operation, ...): mixed
    {
        $customerTransfer = $this->mapToTransfer($data);
        $response = $this->customerFacade->createCustomer($customerTransfer);
        return $this->mapToResource($response->getCustomerTransfer());
    }
}

Resource generation

Console commands

All the following commands can be used with a specific GLUE_APPLICATION by prefixing them with GLUE_APPLICATION=GLUE_BACKEND environment variable. For example: docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:debug --list

# Generate resource classes for all configured API types at once. Usually used during deployment/installation.
docker/sdk cli glue api:generate

# Generate API type specific resource classes. Usually used during development.
docker/sdk cli glue api:generate backend

# Validate schemas only to see if there is any issue in the definitions
docker/sdk cli glue api:generate --validate-only

Debug commands

# List all resources to see which ones are defined in the schema files.
docker/sdk cli glue  api:debug --list

# Inspect specific resource and print details about properties and operations
docker/sdk cli glue  api:debug customers --api-type=backend

# Show merged schema
docker/sdk cli glue  api:debug customers --api-type=backend --show-merged

# Show contributing files for a resource
docker/sdk cli glue  api:debug customers --api-type=backend --show-sources

Features

Automatic OpenAPI documentation

API Platform generates interactive OpenAPI documentation:

Swagger UI at the root URL / for example http://glue-backend.eu.spryker.local/

You can disable this interface in production environments by configuring the settings in your api_platform.php configuration file. For details, see Disable Swagger UI.

Built-in validation

Validation rules from *.validation.yml files are converted to Symfony Validator constraints:

post:
  email:
    - NotBlank
    - Email

Becomes:

#[Assert\NotBlank(groups: ['customers:create'])]
#[Assert\Email(groups: ['customers:create'])]
public ?string $email = null;

Pagination support

Standardized pagination with query parameters:

>GET /customers?page=2&itemsPerPage=20

Provider returns PaginatorInterface:

return new TraversablePaginator(
    new \ArrayObject($results),
    $currentPage,
    $itemsPerPage,
    $totalItems
);

Operation-specific behavior

Define different validation and behavior per operation:

operations:
  - type: Post            # Create
  - type: Get             # Read one
  - type: GetCollection   # Read many
  - type: Patch           # Update
  - type: Delete          # Delete

Each operation can have specific validation rules and security settings.

Relationships

Include related resources via the ?include= query parameter:

includes:
  - relationshipName: addresses
    targetResource: CustomersAddresses
    uriVariableMappings:
      customerReference: customerReference

Request:

GET /customers/customer--35?include=addresses

Response includes both the customer and related addresses in JSON:API format. No provider code changes required - relationships work automatically through decoration.

For detailed information, see Relationships.

Sparse fieldsets

Request only the attributes you need using the fields query parameter:

GET /stores?fields[stores]=name,locale

This returns only name and locale in the response attributes, reducing payload size. Sparse fieldsets work with relationships too — filter attributes on both the main resource and included resources.

For detailed information, see Sparse Fieldsets.

Performance

Cache warming

Pre-generate resources during deployment:

docker/sdk cli glue  api:generate

docker/sdk cli glue  cache:warmup

Property-level access control

properties:
  password:
    writable: true   # Can be written
    readable: false  # Not in responses

Comparison with Glue API

Feature	API Platform	Glue API
Definition	Schema-based (YAML)	Code-based (PHP)
Documentation	Auto-generated OpenAPI	Manual
Validation	Declarative	Programmatic
Standards	JSON-LD, Hydra	JSON API
Learning curve	Lower	Higher
Flexibility	High	Very high
Use cases	Standard CRUD	Complex business logic

Both can coexist in the same application. For further migration guidance, see How to migrate to API Platform.

For detailed implementation guides:

How to integrate API Platform - Setup and configuration
How to integrate API Platform Security - Authentication and authorization setup
How to migrate to API Platform - Migrate endpoints from Glue API
API Platform Configuration - Configure API Platform settings
Security - Authentication and authorization
API Platform Enablement - Creating your first resource
Resource Schemas - Resource Schemas
Validation Schemas - Validation Schemas
Native API Platform Resources - Using native PHP attributes
CodeBucket Support - Region-specific resources
Sparse Fieldsets - Request only needed attributes
Serialization - How requests and responses are serialized
Troubleshooting API Platform - Common issues

Spryker Documentation

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

Migration status - Glue API to API Platform

API Platform migration overview

How to integrate API Platform

API Platform Configuration

Configuration file locations

Released configuration reference

Resource generation configuration (spryker_api_platform.php)

Native API Platform configuration (api_platform.php)

Spryker-specific differences

PHP configuration instead of YAML

Environment variable for conditional settings

Configuration examples

Disable SwaggerUI in production

Disable Doctrine integration

Configure resource mapping paths

Add custom resource paths

Set pagination defaults

Configure supported formats

Configure security

Complete configuration reference

API Platform

What is API Platform

Why Spryker is moving to API Platform

Architecture overview

Resource generation workflow

Core components

1. Schema files

2. Generated resources

3. State providers and processors

API types

Glue API

GlueStorefront API

GlueBackend API

Merchant Portal API

Multi-layer schema merging

Integration with Spryker architecture

Dependency Injection

Facade integration

Resource generation

Console commands