Spryker Documentation

Thu, 09 Jul 2026 07:31:56 +0000

# Integrate the Sass module-system migration into the Demo Shop This guide explains how to integrate the **Sass module-system migration** into the **Spryker Demo Shop**. The update replaces: - the legacy Sass build flow based on `@import` and implicit global injections (historically through `sass-resources-loader`) - the **Sass module system** that uses `@use` and `@forward`, aligned with the **ShopUi vendor builder** Run the migration by using the provided codemod script (`migrate-sass.mjs`), which performs most of the required changes automatically. ## Scope This guide covers: - running the migration script and its phases - frontend builder file changes (bootstrap and project settings override) - TypeScript `tsconfig` path aliases required by the new style imports - Sass module-system rules that you must follow after the migration - verification and troubleshooting ## Audience Use this guide if you maintain an **existing, customized** B2B Demo Shop with local SCSS overrides. ## Prerequisites Before you start, make sure that you have: - a clean Git working tree (commit or stash your changes) - Node.js installed and available because the migration is a Node.js script - updated Composer dependencies that include the ShopUi builder and module-system styles {% info_block infoBox "Info" %} The migration script validates the prerequisites during its preflight phase and stops if your installed vendor packages are not compatible. {% endinfo_block %} ## 1. Update Composer dependencies The migration requires a ShopUi version that provides: - the frontend builder entry point: `vendor/.../ShopUi/builder/build.mjs` - the module-system shared hub: `vendor/.../ShopUi/Theme/default/styles/shared.scss`, which contains `@forward` Update your project dependencies by updating the relevant Spryker packages and then running `composer update` or `composer install`, as appropriate. {% info_block warningBox "Warning" %} Do not run the codemod before updating the vendor packages. The migration relies on the new builder and the new vendor styles. {% endinfo_block %} ## 2. Run the migration script Run the migration from the Demo Shop repository root: ```bash node migrate-sass.mjs ``` The script is **idempotent**. You can rerun it after manual fixes or partial runs. ### 2.1 Run a dry run To preview the changes without writing any files: ```bash node migrate-sass.mjs --dry-run ``` ### 2.2 Run only specific phases To limit the migration scope: ```bash node migrate-sass.mjs --phase=frontend,tsconfig,hub,components ``` ### 2.3 Skip verification If you want to apply the structural changes first and verify them later, run: ```bash node migrate-sass.mjs --skip-verify ``` ### 2.4 Run in modernize-only mode If your project has already been migrated structurally and you only want to fix Sass deprecations (for example, global built-in functions or invalid selectors), run: ```bash node migrate-sass.mjs --modernize-only ``` ## 3. Install updated frontend dependencies The frontend phase updates the `package.json` scripts and development dependencies. After you run the script, install the Node.js dependencies: ```bash npm install ``` {% info_block infoBox "Info" %} The verification phase uses `sass-embedded`. If you skip `npm install`, the verification fails even if your SCSS changes are correct. {% endinfo_block %} ## 4. Review the migration changes ### 4.1 Frontend builder integration The script removes the legacy frontend build files and creates a new builder bootstrap. After the migration, the following files are available: - `frontend/build.mjs` — Builder bootstrap that calls the vendor builder `run()`. - `frontend/settings.override.mjs` — Project-level builder settings override. - `frontend/configs/asset-blacklist.mjs` — Project asset compilation blacklist. - `frontend/libs/stylelint.mjs` — Stylelint runner. - `frontend/libs/design-tokens.mjs` — Optional design token build hook. The `package.json` scripts are updated to call `node ./frontend/build.mjs`, including `yves`, `yves:watch`, and `yves:production`. The script also replaces `sass` with `sass-embedded` in `devDependencies` and removes `sass-resources-loader`, if it is present. {% info_block infoBox "Info" %} The legacy webpack-based image optimization integration described in [Implement Image Optimization](/docs/dg/dev/frontend-development/latest/yves/implement-image-optimization.html) has been removed from the Demo Shop builder flow. This behavior is intentional: - Spryker projects typically **serve images from third-party resources**, such as CDNs, DAM systems, or other external media services, instead of relying on build-time image processing in the storefront repository. - In this setup, image transformations such as compression, resizing, and format conversion are handled closer to the delivery edge, while the storefront build remains focused on compiling CSS and JavaScript assets consistently. If you still require build-time optimization for locally stored images, reintroduce it as a project-specific build step, such as a dedicated builder hook, so that it remains explicit and maintainable. {% endinfo_block %} #### Migrate component exclusions from `$setting-import-blacklist` to `asset-blacklist.mjs` If your project previously excluded component styles by using the legacy Sass blacklist variable, migrate that configuration to the new builder configuration. - **Legacy approach:** Add component patterns to the `$setting-import-blacklist` Sass variable, which is used by the legacy `helper-import` mechanism. This excludes **only SCSS** from the build. Component JavaScript can still be discovered and bundled. - **Current approach:** Use `frontend/configs/asset-blacklist.mjs` to exclude **both SCSS and JavaScript** entry points from the Yves build. **To migrate your configuration:** 1. Locate your `$setting-import-blacklist` configuration and any project documentation about excluded components. 2. Copy the same component patterns into `frontend/configs/asset-blacklist.mjs` as glob patterns. 3. If an excluded component also contains JavaScript entry points, exclude those as well. This is the primary behavioral difference from the legacy approach. **Why this matters** With the legacy approach, you could exclude a component's styles while still shipping its JavaScript. With `asset-blacklist.mjs`, you can exclude both styles and scripts consistently during the build. {% info_block infoBox "Info" %} The ShopUi frontend builder evaluates `asset-blacklist.mjs` by using the source roots configured in `frontend/settings.override.mjs`. {% endinfo_block %} {% info_block warningBox "Warning" %} If you maintain custom frontend build logic under `frontend/`, review `frontend/settings.override.mjs` carefully. The migration overwrites only known legacy files. It does not remove arbitrary project-specific scripts. {% endinfo_block %} ### 4.2 TypeScript path aliases (`tsconfig`) The script ensures that the following path aliases exist in your Yves TypeScript configuration: - `ShopUi/*` resolves to the vendor ShopUi theme. - `src/ShopUi/*` resolves to the project ShopUi theme. These aliases are required because the migrated SCSS uses imports such as: - `@use 'ShopUi/styles/...';` for vendor modules - `@use 'src/ShopUi/styles/...';` for project modules ## 5. Follow the Sass module-system rules after the migration ### 5.1 Treat `shared.scss` as a forward-only hub The migration rewrites the project hub at `src/Pyz/Yves/ShopUi/Theme/default/styles/shared.scss` as a **forward-only hub**. Follow these rules: - Do not emit CSS from `shared.scss`. - Keep the declarations in the following order: 1. Settings 2. Helpers **Reason:** Components `@use` the shared hub. If `shared.scss` emits CSS, each component that loads it emits duplicate CSS. ### 5.2 Configure vendor settings through `src/ShopUi/...` Project settings files under `src/Pyz/Yves/ShopUi/Theme/default/styles/settings/` configure vendor settings by using: ```scss @forward 'ShopUi/styles/settings/' with (...); ``` After the migration: - Do not load vendor settings directly by using `@use 'ShopUi/styles/settings/'` from project code. - Always load the project wrapper instead: ```scss @use 'src/ShopUi/styles/settings/' as *; ``` **Reason:** Sass modules are loaded only once. If a vendor settings module is loaded before it is configured with `with (...)`, you cannot configure it later, and the compilation fails. ### 5.3 Use the standard component SCSS entry point For components, templates, and views, the migration prepends: ```scss @use 'src/ShopUi/styles/shared' as *; ``` This ensures that your component has access to the configured settings and the shared helper mixins and functions. ### 5.4 Move top-level `@include` statements into `style.scss` when required If a component SCSS file contains trailing top-level `@include` statements (for example, a legacy pattern in which a mixin emits the final CSS), the script can: - Move the `@include` statements into a sibling `style.scss` file. - Update the component's `.ts` file to import `./style.scss`. This approach keeps the base SCSS file reusable as a module while `style.scss` serves as the CSS entry point. ### 5.5 Modernize deprecated built-in functions and invalid selectors The script modernizes deprecated Sass patterns, including: - deprecated global built-in functions, for example: - `map-get(...)` → `map.get(...)`, and adds `@use 'sass:map';` - invalid selectors with leading combinators, for example: - `+ & { ... }` → `& + & { ... }` {% info_block warningBox "Warning" %} Rewriting `+ &` to `& + &` can activate CSS rules that browsers previously ignored because the original selector was invalid. Verify the affected components visually after the migration. {% endinfo_block %} ### 5.6 Replace `readyCallback()` with `init()` The `readyCallback()` method has been removed from the core and replaced with `init()`. After the migration, check whether any of your project-level scripts define or call this method and update them accordingly: - Replace `readyCallback()` with `init()`. - Replace `super.readyCallback();` with `super.init();`. {% info_block warningBox "Warning" %} If your project-level scripts still use `readyCallback()` or `super.readyCallback();`, they do not run after the migration because the method no longer exists in the core. {% endinfo_block %} ## 6. Verify the migration ### 6.1 Run a frontend build Run the standard Yves build for your project: ```bash npm run yves ``` Also verify the production build: ```bash npm run yves:production ``` ### 6.2 Verify SCSS compilation By default, `node migrate-sass.mjs` ends with a verification phase that compiles the migrated stylesheets by using `sass-embedded` and the same alias resolution rules. If you ran the script with `--skip-verify`, rerun it later without that flag to perform the verification. ## 7. Troubleshooting ### 7.1 Preflight error: ShopUi builder is missing **Symptom:** The script fails during the preflight phase and reports that the ShopUi builder entry does not exist. **Cause:** Your vendor packages do not include a ShopUi version that provides the frontend builder. **Fix:** Update your Composer dependencies so that ShopUi provides `builder/build.mjs`, then rerun the script. ### 7.2 Preflight error: Vendor `shared.scss` is not `@forward`-based **Symptom:** The script reports that the vendor `styles/shared.scss` file is not based on `@forward`. **Cause:** Your ShopUi styles still use the legacy `@import` approach. **Fix:** Update your vendor dependencies to a version that supports the Sass module system. ### 7.3 Sass error: "This module was already loaded, so it cannot be configured using with" **Symptom:** Sass compilation fails with an error similar to the following: - `This module was already loaded, so it cannot be configured using with`. **Cause:** A vendor settings module was loaded directly (for example, `@use 'ShopUi/styles/settings/colors'`) before the project wrapper configured it. **Fix:** - Replace direct vendor settings imports with: ```scss @use 'src/ShopUi/styles/settings/' as *; ``` - Ensure that `src/ShopUi/styles/shared` is loaded before any vendor helper or utility module that depends on settings. ### 7.4 Sass error: Missing TypeScript alias or unresolved import **Symptom:** Sass cannot resolve imports such as `src/ShopUi/...` or `/...`. **Cause:** The required `tsconfig` path aliases are missing. **Fix:** Rerun the script with `--phase=tsconfig`, then commit the updated `tsconfig.json` file. ### 7.5 Visual regressions after the combinator fix **Symptom:** Visual changes appear in components whose SCSS contains selectors such as `+ &`. **Cause:** The migration rewrites `+ &` to `& + &`, which changes previously invalid CSS into valid CSS. **Fix:** Review the affected selectors and confirm that they produce the intended behavior. {% info_block infoBox "Info" %} If you need to rerun only the deprecation fixes across the entire project, use: ```bash node migrate-sass.mjs --modernize-only ``` {% endinfo_block %} ## 8. Commit strategy To simplify code reviews, apply and commit the migration in separate commits: 1. Update the Composer dependencies (ShopUi builder and styles). 2. Commit the frontend builder and `package.json` changes. 3. Commit the `tsconfig` alias changes. 4. Commit the ShopUi styles hub migration. 5. Commit the component, template, and view migration. 6. Commit the manual fixes and visual regression adjustments.

Add variables in the Parameter Store

Fri, 03 Jul 2026 15:04:00 +0000

Variables, such as parameters and secrets, are used for multiple purposes, like storing mail server details or providing Composer authentication details to the build and deploy process securely.

This feature is part of a gradual rollout and will be available to everyone eventually. We will notify your team once your project is onboarded.

For complex or system-critical changes to variables, we recommend consulting with our support to prevent unexpected issues.

Customer-owned and Spryker-owned variables

There are two types of environment variables: customer-owned and Spryker-owned.

Spryker-owned variables are managed and can be updated only with the help of Spryker Cloud or support teams. To request a variable change, in Support Portal, create the following request: Infrastructure Change Request > Change to existing parameter store variable.

Customer-owned variables are created and managed by you or implementation partner. You have full control over these variables and can add or edit them according to your needs. Changes to these variables don’t automatically propagate into a running environment. To apply changes made to your environment variables, you need to run an ECS-updater-* pipeline to bring them to the containers or run a full redeploy. You can do this whole process without creating support tickets.

Customer-owned variables with limited access

The following customer-owned variables can be updated only with the help of Spryker Cloud or support teams:

/{project}/{environment}/secret/scheduler/limited/{variable_name}
/{project}/{environment}/secret/pipeline/limited/{variable_name}
/{project}/{environment}/secret/common/limited/{variable_name}
/{project}/{environment}/secret/app/limited/{variable_name}
/{project}/{environment}/config/scheduler/limited/{variable_name}
/{project}/{environment}/config/pipeline/limited/{variable_name}
/{project}/{environment}/config/common/limited/{variable_name}
/{project}/{environment}/config/app/limited/{variable_name}

Naming convention for variables

Variables must follow this naming convention: /{project}/{environment}/{type}/{bucket}/{grant}/{variable_name}.

Placeholder description:

type: defines the type of a variable. Possible values:
- config: parameter
- secret: secret
bucket: defines what services a variable is used for. Possible values:
- common: used by all the buckets.
- app: used only by application services.
- scheduler: used by the scheduler.
grant: Defines access permissions to variables. Possible values:
- public: readable and writable
- limited: readable

Path examples:

/fashion_club_store/staging/config/common/limited/composer_pass
/deans_jeans/prod/config/app/public/mail_host

Reserved variables

Reserved variables are reserved in Spryker for dedicated functions. These names can’t be used to create more variables. If you’re already using reserved variables in your code, you need to change their names to avoid any service issues.

Reserved variables:

SPRYKER_*: Every variable name with this prefix
ALLOWED_IP
BLACKFIRE_AGENT_SOCKET
BLACKFIRE_SERVER_ID
BLACKFIRE_SERVER_TOKEN
DATA_IMPORT_S3_BUCKET
DATA_IMPORT_S3_KEY
DATA_IMPORT_S3_SECRET
DUMMY_INIT
ENABLE_NRI_ECS
JAVA_OPTS
JENKINS_URL
NEWRELIC_APPNAME
NEWRELIC_ENABLED
NEWRELIC_LICENSE
NRIA_CUSTOM_ATTRIBUTES
NRIA_LICENSE_KEY
NRIA_OVERRIDE_HOST_ROOT
NRIA_PASSTHROUGH_ENVIRONMENT
NRIA_VERBOSE
ONEAGENT_INSTALLER_DOWNLOAD_TOKEN
ONEAGENT_INSTALLER_SCRIPT_URL
RABBITMQ_DEFAULT_PASS
RABBITMQ_DEFAULT_USER
RABBITMQ_DEFAULT_VHOST
RABBITMQ_ENDPOINT
RABBITMQ_EXCHANGE_REGEXES
RABBITMQ_INTEGRATIONS_INTERVAL
RABBITMQ_NODENAME
RABBITMQ_PASSWORD
RABBITMQ_PORT
RABBITMQ_QUEUES_REGEXES
RABBITMQ_USE_SSL
RABBITMQ_USERNAME
TIDEWAYS_APIKEY
TIDEWAYS_CLI_ENABLED
TIDEWAYS_DAEMON_URI
TIDEWAYS_ENVIRONMENT

Variable path hierarchy

Path hierarchy is needed to cover the cases when several variables with the same name are declared. If several variables with the same name are declared, the variable with a higher priority applies. The following rules define the priority of variables:

For any type and bucket, the priority is public > limited.
Foy any bucket, the priority is bucket > common.
For any variable with the same name, the priority is secret > config.

The following variables are arranged from lower to higher priority:

/{project}/{environment}/config/common/limited/{variable_name}
/{project}/{environment}/config/common/public/{variable_name}
/{project}/{environment}/config/{app | scheduler}/limited/{variable_name}
/{project}/{environment}/config/{app | scheduler}/public/{variable_name}
/{project}/{environment}/secret/common/limited/{variable_name}
/{project}/{environment}/secret/common/public/{variable_name}
/{project}/{environment}/secret/{app | scheduler}/limited/{variable_name}
/{project}/{environment}/secret/{app | scheduler}/public/{variable_name}

Add variables

The following sections describe how to add parameters and secrets for different resources.

Add parameters to all resource types

In the AWS Management Console, go to Services > Parameter Store.
In the My parameters pane, click Create parameter. This opens the Create parameter page.
For Name, enter /{project}/{environment}/config/common/public/{variable_name}. Make sure to replace the placeholders based on your requirements.
Optional: For Description, enter a description of the variable. This may be a note about what this variable is used for.
For Type, select a type of the variable based on your requirements.
For Value, enter the value of the variable.
Click Create parameter. This opens the Parameter Store page with a success message displayed.
Go to Services > CodePipeline.
On the Pipelines page, select the NORMAL_Deploy_Spryker_{project}-{environment} pipeline.
On the pipeline’s page, click Release change.
In the Release change window, click Release. After the pipeline finishes running, the variable gets available for your application.

Add secrets to all resource types

In the AWS Management Console, go to Services > Parameter Store.
In the My parameters pane, click Create parameter. This opens the Create parameter page.
For Name, enter /{project}/{environment}/secret/common/public/{variable_name}. Make sure to replace the placeholders based on your requirements.
Optional: For Description, enter a description of the variable. This may be a note about what this variable is used for. This may be a note about what this variable is used for.
For Type, select SecureString.
For Value, enter the value of the variable.
Click Create parameter. This opens the Parameter Store page with a success message displayed.
Go to Services > CodePipeline.
On the Pipelines page, select the NORMAL_Deploy_Spryker_{project}-{environment} pipeline.
On the pipeline’s page, click Release change.
In the Release change window, click Release. After the pipeline finishes running, the variable gets available for your application.

Add parameters to ECS applications

In the AWS Management Console, go to Services > Parameter Store.
In the My parameters pane, click Create parameter. This opens the Create parameter page.
For Name, enter /{project}/{environment}/config/app/public/{variable_name}. Make sure to replace the placeholders based on your requirements.
Optional: For Description, enter a description of the variable. This may be a note about what this variable is used for. This may be a note about what this variable is used for.
For Type, select a type of the variable based on your requirements.
For Value, enter the value of the variable.
Click Create parameter. This opens the Parameter Store page with a success message displayed.
Go to Services > CodePipeline.
On the Pipelines page, select the ECS-updater-{project}-{environment} pipeline.
On the pipeline’s page, click Release change.
In the Release change window, click Release. After the pipeline finishes running, the variable gets available for your application.

Adding secrets to ECS applications

In the AWS Management Console, go to Services > Parameter Store.
In the My parameters pane, click Create parameter. This opens the Create parameter page.
For Name, enter /{project}/{environment}/secret/app/public/{variable_name}. Make sure to replace the placeholders based on your requirements.
Optional: For Description, enter a description of the variable. This may be a note about what this variable is used for. This may be a note about what this variable is used for.
For Type, select SecureString.
For Value, enter the value of the variable.
Click Create parameter. This opens the Parameter Store page with a success message displayed.
Go to Services > CodePipeline.
On the Pipelines page, select the ECS-updater-{project}-{environment} pipeline.
On the pipeline’s page, click Release change.
In the Release change window, click Release. After the pipeline finishes running, the variable gets available for your application.

Add parameters and secrets to Scheduler

In the AWS Management Console, go to Services > Parameter Store.
In the My parameters pane, click Create parameter. This opens the Create parameter page.
For Name, enter one of the following:
- Variable: /{project}/{environment}/config/scheduler/public/{variable_name}
- Secret: /{project}/{environment}/secret/scheduler/public/{variable_name} Make sure to replace the placeholders based on your requirements.
Optional: For Description, enter a description of the variable. This may be a note about what this variable is used for. This may be a note about what this variable is used for.
For Type, select SecureString.
For Value, enter the value of the variable.
Click Create parameter. This opens the Parameter Store page with a success message displayed.
Go to Services > CodePipeline.
On the Pipelines page, select the Rollout_Scheduler_{project}-{environment} pipeline.
On the pipeline’s page, click Release change.
In the Release change window, click Release. After the pipeline finishes running, the variable gets available for your application.

Recurring Orders feature overview

Tue, 30 Jun 2026 14:54:21 +0000

{% info_block warningBox "Early Access" %} This feature is in Early Access. We'd love for you to try it out and share feedback as we work toward general availability. {% endinfo_block %} The *Recurring Orders* feature lets B2B buyers set up automated repeat purchases directly from the checkout. Once configured, the system places orders automatically at the chosen interval, sends notifications before each execution, and pauses for buyer review when prices change or products become unavailable. ![Recurring order list](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Recurring+Orders/RecurringOrders_1.png) ![Recurring order detail](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Recurring+Orders/RecurringOrders_2.png) ## Concepts | TERM | DESCRIPTION | | --- | --- | | Recurring schedule | The configuration record that drives automated order placement. Stores the cadence, the serialized quote snapshot, and the state machine state. | | Cadence | The interval at which the order is placed. One of: weekly, bi-weekly, monthly, or every N weeks. | | Trigger date | The date on which the state machine attempts to place the next order. | | Notification window | The number of hours before the trigger date when the pre-trigger notification is sent to the buyer. | | Review Required | A state the schedule enters when price increases or product issues are detected at pre-placement validation. The buyer must accept or adjust the order before it is placed. | ## Setting up a recurring order At checkout, an eligible buyer can enable the recurring order setup widget. The buyer selects a cadence (for example, weekly or monthly) and optionally sets a schedule name and an interval value for the *every N weeks* cadence. When the order is placed, the system: 1. Saves a serialized snapshot of the quote — including products, quantities, prices, shipment method, and payment method. 2. Creates a recurring schedule record in `spy_recurring_schedule` with the first trigger date calculated from the cadence. 3. Registers the schedule with the `RecurringOrder` state machine in the `draft` state and immediately activates it. A recurring schedule is **only available** for quotes that meet all of the following conditions: - The quote is not locked (not sent for approval). - The quote does not originate from a Request for Quote (RFQ). - The customer is not a guest. - The payment method is invoice-based (`invoice`, `purchaseOnAccount`, or a configured equivalent). ## Cadence types | CADENCE | DESCRIPTION | | --- | --- | | Weekly | Places an order every 7 days. | | Bi-weekly | Places an order every 14 days. | | Monthly | Places an order on the same calendar day each month. If the scheduled day does not exist in the target month, the date overflows: for example, a schedule anchored to January 31 next fires on March 3 (not February 28), and all subsequent executions are anchored to the 3rd of each month. To avoid drift, use a start date on the 28th or earlier. | | Every N weeks | Places an order every N weeks. Requires a positive integer value for N. | ![Recurring order setup at checkout](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Recurring+Orders/RecurringOrders_3.png) ## Schedule lifecycle The recurring schedule moves through states managed by the `RecurringOrder` state machine. The following diagram describes the full lifecycle: | STATE | DESCRIPTION | | --- | --- | | `draft` | Newly created. Transitions to `active` immediately after checkout. | | `active` | Running. The state machine checks the trigger date on every cron run. | | `notifying` | The trigger date is within the notification window. The system sends a pre-trigger notification to the buyer. | | `pre_trigger_notified` | The buyer has been notified. The schedule waits for the placement window to open or for a manual action (skip or cancel). | | `validation` | Pre-placement validation is running. Price and availability are checked. | | `confirmed` | Validation passed. The order is ready for placement. | | `order_placed` | The checkout has been initiated. The system waits for confirmation. | | `completing` | The order was successfully placed. The next trigger date is calculated and the schedule returns to `active`. | | `skipped` | The buyer skipped the current execution. The next trigger date is advanced by one full cadence interval. | | `review_required` | Validation detected an issue (price increase or product unavailability). The buyer must review before placement can proceed. | | `paused` | The buyer manually paused the schedule. No orders are placed until it is resumed. | | `failed` | The last order placement attempt failed. The buyer can retry, which moves the schedule to `review_required`. | | `cancelled` | The schedule has been permanently stopped. This is a terminal state. | ### Buyer actions Buyers can perform the following manual actions from the recurring order detail page on the storefront: | ACTION | AVAILABLE FROM STATES | DESCRIPTION | | --- | --- | --- | | Pause | `active` | Temporarily stops order placement. The schedule can be resumed at any time with an optional custom resume date. | | Resume | `paused` | Reactivates the schedule. The buyer can set a new next trigger date or keep the existing one. | | Skip | `active`, `pre_trigger_notified`, `review_required` | Skips the next scheduled execution. The new trigger date is calculated by advancing the current trigger date by one cadence interval. If the current trigger date is already in the past due to processing lag, the recalculated date may also fall in the past and the schedule will process on the next cron run. | | Cancel | `active`, `paused`, `pre_trigger_notified`, `review_required`, `failed`, `draft` | Permanently cancels the schedule. This action cannot be undone. The `draft` state is transient and is normally activated synchronously at checkout; cancellation from `draft` is a safety fallback. | | Review | `review_required` | Opens the Review Required page where the buyer can accept price changes, remove unavailable items, and place the order. | | Retry | `failed` | Moves the schedule to `review_required` so the buyer can review and re-attempt placement. | ![Recurring order list with attention banner](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Recurring+Orders/RecurringOrders_4.png) ## Pre-trigger notification Before each order placement, the system sends an email to the buyer within the configured **Schedule Grace Period** (default: 48 hours before the trigger date). The notification includes: - The schedule name and the upcoming execution date. - A link to the schedule detail page where the buyer can skip, pause, or cancel before the order is placed. The Schedule Grace Period is configured globally in the Back Office under **Configuration > Recurring Orders > General > Schedule**. ## Review Required flow Before placing each order, the system validates the stored quote snapshot against current product and pricing data. If issues are detected, the schedule moves to the `review_required` state and the buyer receives a review notification email. The buyer reviews the flagged items on the **Review Required** page. The following table lists common issue types. The full set of checkout error types that map to each group is configurable via `getReviewReasonGroupMap()` in `OrderExperienceManagementConfig`. | ISSUE | DESCRIPTION | | --- | --- | | Price increased | The current unit price is higher than the reference price stored on the schedule item. | | Unavailable | The product is out of stock, inactive, or blocked by a merchant or product approval rule. | | Packaging unit unavailable | The product packaging unit constraints cannot be satisfied — for example, the required minimum or lead quantity is not available. | | Discontinued | The product has been discontinued. | | Substituted | The product has been replaced by another product. | | Not approved | The product is pending approval and cannot be purchased. | | Price unavailable | No current price could be resolved for the product. | | Configurable bundle unavailable | A member of a configurable bundle is unpurchasable, so the entire bundle is dropped. | Items flagged as **unavailable** or **not approved** are non-purchasable and must be removed before the order can proceed. Items with a price increase can be accepted or removed. The buyer confirms the changes, which updates the stored quote snapshot and places the order. ![Review Required page](https://spryker.s3.eu-central-1.amazonaws.com/docs/Features/Recurring+Orders/RecurringOrders_5.png) ## Execution history Each recurring schedule maintains a full execution history. Every significant event is recorded: | EVENT | DESCRIPTION | | --- | --- | | Placed | An order was successfully placed. The history entry links to the resulting sales order. | | Failed | An order placement attempt failed. The entry includes the failure reason. | | Skipped | The execution was skipped by the buyer. | | Paused | The schedule was paused. | | Resumed | The schedule was resumed. | | Cancelled | The schedule was permanently cancelled. | ## Storefront pages | PAGE | PATH | DESCRIPTION | | --- | --- | --- | | Recurring order list | `/recurring-orders` | Lists all recurring schedules for the current buyer, with status, cadence, and trigger date. Company users with the appropriate permission can filter by scope (own, company, or business unit). | | Recurring order detail | `/recurring-orders/{uuid}` | Shows the full schedule configuration, the items and quantities, the next execution date, and the full execution history. | | Review Required | `/recurring-orders/{uuid}/review-required` | Shows flagged items with issue reasons and price comparisons. The buyer accepts changes and places the order from this page. | ## B2B visibility and permissions By default, a buyer can only view their own recurring schedules. Company users with additional permissions can view schedules across their organization: | PERMISSION | DESCRIPTION | | --- | --- | | `SeeCompanyOrdersPermissionPlugin` | Grants visibility over all recurring schedules within the company. | | `SeeBusinessUnitOrdersPermissionPlugin` | Grants visibility over all recurring schedules within the buyer's business unit. | These permissions are registered as company role permissions and assigned in the Back Office under **Customers > Company Roles**. ## Attention banner When a buyer has schedules in the `paused`, `review_required`, or `failed` states, an attention banner is displayed on the storefront. The banner shows the count of schedules requiring attention and provides quick-access links to filter the recurring order list by each status. ## Related documents - [Install the Recurring Orders feature](/docs/pbc/all/order-experience-management/latest/base-shop/install-and-upgrade/install-features/install-the-recurring-orders-feature.html)

Install the Recurring Orders feature

Tue, 30 Jun 2026 14:54:21 +0000

{% info_block warningBox "Early Access" %} This feature is in Early Access. We'd love for you to try it out and share feedback as we work toward general availability. {% endinfo_block %} This document describes how to install the Recurring Orders feature. ## Install feature core Follow the steps below to install the Recurring Orders feature core. ### Prerequisites To start feature integration, review and install the necessary features: | NAME | VERSION | INSTALLATION GUIDE | | --- | --- | --- | | Spryker Core | {{page.release_tag}} | [Install the Spryker Core feature](/docs/pbc/all/miscellaneous/latest/install-and-upgrade/install-features/install-the-spryker-core-feature.html) | | Company Account | {{page.release_tag}} | [Install the Company Account feature](/docs/pbc/all/customer-relationship-management/latest/base-shop/install-and-upgrade/install-features/install-the-company-account-feature.html) | | Checkout | {{page.release_tag}} | [Install the Checkout feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-checkout-feature.html) | ### 1) Install the required modules {% info_block infoBox "Required modules" %} ```bash composer require spryker-feature/order-experience-management:"^0.1.4" --update-with-dependencies composer update \ spryker/availability:"^9.32.0" \ spryker/merchant:"^3.20.0" \ spryker/merchant-product-option:"^1.4.0" \ spryker/merchant-switcher:"^0.6.8" \ spryker/product-approval:"^1.5.0" \ spryker/product-bundle:"^7.28.0" \ spryker/product-cart-connector:"^4.15.0" \ spryker/product-configuration-cart:"^1.1.0" \ spryker/product-discontinued:"^1.15.0" \ spryker/product-offer:"^1.18.0" \ spryker/product-packaging-unit:"^4.14.0" \ spryker/product-quantity:"^3.8.0" \ spryker-feature/purchasing-control:"^1.1.1" \ spryker-shop/checkout-page:"^3.42.0" \ spryker-shop/customer-page:"^2.80.0" \ --with-dependencies ``` {% endinfo_block %} ### 2) Set up database schema and transfer objects Apply database changes and generate entity and transfer changes: ```bash console propel:install console transfer:generate ``` {% info_block warningBox "Verification" %} Make sure the following changes have been applied in the database: | DATABASE ENTITY | TYPE | EVENT | | --- | --- | --- | | spy_recurring_schedule | table | created | | spy_recurring_schedule_item | table | created | | spy_recurring_schedule_history | table | created | Make sure the following changes have been applied in transfer objects: | TRANSFER | TYPE | EVENT | PATH | | --- | --- | --- | --- | | RecurringSchedule | class | created | src/Generated/Shared/Transfer/RecurringScheduleTransfer.php | | RecurringScheduleCollection | class | created | src/Generated/Shared/Transfer/RecurringScheduleCollectionTransfer.php | | RecurringScheduleCriteria | class | created | src/Generated/Shared/Transfer/RecurringScheduleCriteriaTransfer.php | | RecurringScheduleConditions | class | created | src/Generated/Shared/Transfer/RecurringScheduleConditionsTransfer.php | | RecurringScheduleCollectionRequest | class | created | src/Generated/Shared/Transfer/RecurringScheduleCollectionRequestTransfer.php | | RecurringScheduleCollectionResponse | class | created | src/Generated/Shared/Transfer/RecurringScheduleCollectionResponseTransfer.php | | RecurringScheduleItem | class | created | src/Generated/Shared/Transfer/RecurringScheduleItemTransfer.php | | RecurringScheduleHistory | class | created | src/Generated/Shared/Transfer/RecurringScheduleHistoryTransfer.php | | RecurringScheduleValidationResult | class | created | src/Generated/Shared/Transfer/RecurringScheduleValidationResultTransfer.php | | RecurringScheduleItemReview | class | created | src/Generated/Shared/Transfer/RecurringScheduleItemReviewTransfer.php | | RecurringScheduleReviewResponse | class | created | src/Generated/Shared/Transfer/RecurringScheduleReviewResponseTransfer.php | | RecurringScheduleEventRequest | class | created | src/Generated/Shared/Transfer/RecurringScheduleEventRequestTransfer.php | | RecurringScheduleEventResponse | class | created | src/Generated/Shared/Transfer/RecurringScheduleEventResponseTransfer.php | | RecurringScheduleStatusCountCollection | class | created | src/Generated/Shared/Transfer/RecurringScheduleStatusCountCollectionTransfer.php | | RecurringOrderSettings | class | created | src/Generated/Shared/Transfer/RecurringOrderSettingsTransfer.php | | RecurringOrderQuoteUpdateRequest | class | created | src/Generated/Shared/Transfer/RecurringOrderQuoteUpdateRequestTransfer.php | | RecurringOrderQuoteUpdateResponse | class | created | src/Generated/Shared/Transfer/RecurringOrderQuoteUpdateResponseTransfer.php | | Quote.recurringOrderSettings | property | created | src/Generated/Shared/Transfer/QuoteTransfer.php | {% endinfo_block %} ### 3) Set up data import Import the CMS blocks that provide the HTML and text templates for recurring order notification emails. The CMS block definitions are provided in the module at `src/SprykerFeature/OrderExperienceManagement/data/import/cms_block.csv`. Copy the contents of that file and add them to **data/import/common/common/cms_block.csv**. For each store you want to enable the email notifications in, add the corresponding block keys to **data/import/common/{store}/cms_block_store.csv**. Import the data: ```bash console data:import:cms-block console data:import:cms-block-store ``` {% info_block warningBox "Verification" %} In the Back Office, under **Content > Blocks**, make sure the CMS blocks from the module file are present and active. {% endinfo_block %} ### 4) Set up behavior Enable the following behaviors by registering the plugins. #### Set up Checkout plugins | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | RecurringOrderCheckoutPreConditionPlugin | Validates the quote is eligible for a recurring order before checkout proceeds. Checks that the quote is not locked, not from an RFQ, not a guest session, the payment method is invoice-based, and the cadence type is registered and valid. | None | SprykerFeature\Zed\OrderExperienceManagement\Communication\Plugin\Checkout | | RecurringOrdersCheckoutPostSavePlugin | Creates a recurring schedule and registers it with the state machine after the order is successfully saved. Does nothing when `recurringOrderSettings` is not set on the quote. | None | SprykerFeature\Zed\OrderExperienceManagement\Communication\Plugin\Checkout | **src/Pyz/Zed/Checkout/CheckoutDependencyProvider.php** ```php */ protected function getCheckoutPreConditions(Container $container): array { return [ // ... new RecurringOrderCheckoutPreConditionPlugin(), #RecurringOrdersFeature ]; } /** * @param \Spryker\Zed\Kernel\Container $container * * @return list<\Spryker\Zed\CheckoutExtension\Dependency\Plugin\CheckoutPostSaveInterface> */ protected function getCheckoutPostHooks(Container $container): array { return [ // ... new RecurringOrdersCheckoutPostSavePlugin(), #RecurringOrdersFeature ]; } } ``` {% info_block warningBox "Verification" %} 1. Add a product to the cart, set a recurring order cadence on the quote, and complete checkout. Make sure a recurring schedule is created in `spy_recurring_schedule`. 2. Attempt to place a recurring order with a non-invoice payment method. Make sure checkout is blocked. 3. Attempt to place a recurring order with an invalid cadence type. Make sure checkout is blocked. {% endinfo_block %} #### Set up the Subscription dependency provider Register the built-in cadence type and schedule validator plugins: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | WeeklyCadenceTypePlugin | Calculates the next trigger date 7 days after the current trigger date. | None | SprykerFeature\Zed\OrderExperienceManagement\Communication\Plugin\Cadence | | BiWeeklyCadenceTypePlugin | Calculates the next trigger date 14 days after the current trigger date. | None | SprykerFeature\Zed\OrderExperienceManagement\Communication\Plugin\Cadence | | MonthlyCadenceTypePlugin | Calculates the next trigger date on the same day of the following month. | None | SprykerFeature\Zed\OrderExperienceManagement\Communication\Plugin\Cadence | | EveryNWeeksCadenceTypePlugin | Calculates the next trigger date every N weeks. Requires `cadenceValue` to be set on the schedule. | None | SprykerFeature\Zed\OrderExperienceManagement\Communication\Plugin\Cadence | | PriceScheduleValidatorPlugin | Detects price increases on recurring schedule items compared to their stored reference prices before order placement. | None | SprykerFeature\Zed\OrderExperienceManagement\Communication\Plugin\ScheduleValidator | | CheckoutPlaceabilityScheduleValidatorPlugin | Simulates a checkout to detect availability or product approval issues on recurring schedule items before order placement. | None | SprykerFeature\Zed\OrderExperienceManagement\Communication\Plugin\ScheduleValidator | **src/Pyz/Zed/OrderExperienceManagement/OrderExperienceManagementDependencyProvider.php** ```php */ protected function getCadenceTypePlugins(): array { return [ new WeeklyCadenceTypePlugin(), #RecurringOrdersFeature new BiWeeklyCadenceTypePlugin(), #RecurringOrdersFeature new MonthlyCadenceTypePlugin(), #RecurringOrdersFeature new EveryNWeeksCadenceTypePlugin(), #RecurringOrdersFeature ]; } /** * @return array<\SprykerFeature\Zed\OrderExperienceManagement\Dependency\Plugin\ScheduleValidatorPluginInterface> */ protected function getScheduleValidatorPlugins(): array { return [ new PriceScheduleValidatorPlugin(), #RecurringOrdersFeature new CheckoutPlaceabilityScheduleValidatorPlugin(), #RecurringOrdersFeature ]; } } ``` {% info_block warningBox "Verification" %} Make sure all four cadence types (weekly, bi-weekly, monthly, every N weeks) are available when setting up a recurring order on the storefront. {% endinfo_block %} #### Set up the state machine handler Register the recurring orders state machine handler: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | RecurringOrdersStateMachineHandlerPlugin | Registers the `RecurringOrder` state machine process, maps commands and conditions to plugins, updates the state machine item state on each transition, and returns schedule items by state IDs. | None | SprykerFeature\Zed\OrderExperienceManagement\Communication\Plugin\StateMachine | **src/Pyz/Zed/StateMachine/StateMachineDependencyProvider.php** ```php */ protected function getStateMachineHandlers(): array { return [ // ... new RecurringOrdersStateMachineHandlerPlugin(), #RecurringOrdersFeature ]; } } ``` Copy the state machine process XML from the module into your project. The example file is located at `src/SprykerFeature/OrderExperienceManagement/config/Zed/StateMachine/RecurringOrder/RecurringOrderStateMachine.xml` in the module. Add it to your project at the following path: **config/Zed/StateMachine/RecurringOrder/RecurringOrderStateMachine.xml** {% info_block warningBox "Verification" %} In the Back Office, under **Maintenance > State Machine**, make sure the `RecurringOrderStateMachine` process is listed and the diagram renders correctly. {% endinfo_block %} #### Set up Mail plugins Register the following mail type builder plugins: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | RecurringOrderUpcomingNotificationMailTypeBuilderPlugin | Builds the pre-trigger notification email sent to the buyer a configurable number of hours before the scheduled order is placed. | None | SprykerFeature\Zed\OrderExperienceManagement\Communication\Plugin\Mail | | RecurringOrderValidationFailedMailTypeBuilderPlugin | Builds the review-required notification email sent to the buyer when a price increase or product availability issue is detected. | None | SprykerFeature\Zed\OrderExperienceManagement\Communication\Plugin\Mail | | RecurringOrderFailureMailTypeBuilderPlugin | Builds the order placement failure notification email sent to the buyer when order placement fails. | None | SprykerFeature\Zed\OrderExperienceManagement\Communication\Plugin\Mail | **src/Pyz/Zed/Mail/MailDependencyProvider.php** ```php */ protected function getMailTypeBuilderPlugins(): array { return [ // ... new RecurringOrderUpcomingNotificationMailTypeBuilderPlugin(), #RecurringOrdersFeature new RecurringOrderValidationFailedMailTypeBuilderPlugin(), #RecurringOrdersFeature new RecurringOrderFailureMailTypeBuilderPlugin(), #RecurringOrdersFeature ]; } } ``` {% info_block warningBox "Verification" %} Trigger a recurring order cycle and verify the following: - A pre-trigger notification email is sent to the buyer within the configured notification window hours. - When a price increase or product availability issue is detected, a review-required email is sent. - When order placement fails, a failure notification email is sent. {% endinfo_block %} #### Set up permissions By default, a company user can only see their own recurring orders. To allow users to view recurring orders across their company or business unit, register the following permission plugins: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | SeeCompanyOrdersPermissionPlugin | Grants permission to view all recurring orders within the company. Assign to company roles that should have company-wide visibility. | None | Spryker\Zed\CompanySalesConnector\Communication\Plugin\Permission | | SeeBusinessUnitOrdersPermissionPlugin | Grants permission to view all recurring orders within the company business unit. Assign to company roles that should have business-unit-wide visibility. | None | Spryker\Zed\CompanyBusinessUnitSalesConnector\Communication\Plugin\Permission | **src/Pyz/Zed/Permission/PermissionDependencyProvider.php** ```php */ protected function getPermissionPlugins(): array { return [ // ... new SeeCompanyOrdersPermissionPlugin(), #RecurringOrdersFeature new SeeBusinessUnitOrdersPermissionPlugin(), #RecurringOrdersFeature ]; } } ``` **src/Pyz/Client/Permission/PermissionDependencyProvider.php** ```php */ protected function getPermissionPlugins(): array { return [ // ... new SeeCompanyOrdersPermissionPlugin(), #RecurringOrdersFeature new SeeBusinessUnitOrdersPermissionPlugin(), #RecurringOrdersFeature ]; } } ``` {% info_block warningBox "Verification" %} In the Back Office, under **Customers > Company Roles**, assign `SeeCompanyOrdersPermissionPlugin` to a company role. Make sure company users with that role can see all recurring orders within their company on the storefront. Assign `SeeBusinessUnitOrdersPermissionPlugin` to a role. Make sure users with that role can see all recurring orders within their business unit. {% endinfo_block %} #### Set up cron jobs The recurring orders state machine relies on a cron job to evaluate condition transitions. Register the job in your Jenkins configuration: **config/Zed/cronjobs/jenkins.php** ```php /* RecurringOrder StateMachine */ $jobs[] = [ 'name' => 'recurring-order-check-conditions', 'command' => '$PHP_BIN vendor/bin/console state-machine:check-condition RecurringOrder', 'schedule' => '* * * * *', 'enable' => true, ]; ``` {% info_block infoBox "Scheduling recommendation" %} To have recurring orders placed before the business day starts, set trigger dates to an early morning time (for example, 01:00) and configure `DEFAULT_NOTIFICATION_WINDOW_HOURS` to `18` (for example) or more. With an 18-hour window, the pre-trigger notification is sent the previous afternoon (after 12:00), allowing the buyer to review or skip before the order is placed overnight. {% endinfo_block %} If your project uses Symfony Scheduler instead of Jenkins, register the equivalent job in your scheduler config: **src/Pyz/Zed/SymfonyScheduler/SymfonySchedulerConfig.php** ```php 'recurring-orders-check-condition' => [ 'command' => '$PHP_BIN vendor/bin/console state-machine:check-condition RecurringOrder', 'schedule' => '* * * * *', ], 'recurring-orders-clear-locks' => [ 'command' => '$PHP_BIN vendor/bin/console state-machine:clear-locks', 'schedule' => '0 6 * * *', ], ``` {% info_block warningBox "Verification" %} Activate a recurring schedule. Make sure the state machine condition check job runs and the schedule transitions from `draft` to `active` within one minute. {% endinfo_block %} #### Optional: Register the trigger console command `RecurringOrderTriggerConsole` lets you manually trigger order placement for a specific recurring schedule from the CLI. It runs the same placement logic as the state machine `PlaceOrderCommand`, which makes it useful for development, debugging, and one-off operational tasks. To enable it, register the command in your console dependency provider: **src/Pyz/Zed/Console/ConsoleDependencyProvider.php** ```php */ protected function getConsoleCommands(Container $container): array { return [ // ... new RecurringOrderTriggerConsole(), #RecurringOrdersFeature ]; } } ``` Usage: ```bash # Trigger placement by numeric ID console recurring-orders:trigger-placement 42 # Trigger placement by UUID console recurring-orders:trigger-placement 550e8400-e29b-41d4-a716-446655440000 # Run pre-placement validation first; aborts if validation fails console recurring-orders:trigger-placement 42 --validate ``` The `--validate` flag runs all registered `ScheduleValidatorPlugin` implementations (for example, `PriceScheduleValidatorPlugin` and `CheckoutPlaceabilityScheduleValidatorPlugin`) before attempting placement. If any validator reports a failure, the command exits with an error and does not place the order. {% info_block warningBox "Development use only" %} This command is intended for development and debugging. Do not use it in production automated pipelines — the state machine cron job is the intended trigger for production order placement. {% endinfo_block %} #### Configure product bundle field copying {% info_block infoBox "Product Bundles feature" %} This step is only required if your project uses the [Product Bundles feature](/docs/pbc/all/product-information-management/latest/base-shop/feature-overviews/product-bundles-feature-overview.html). {% endinfo_block %} Override the allowed fields to copy so that shipment information is preserved when recurring orders re-create bundle items: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | `getAllowedBundleItemFieldsToCopy()` | Returns the list of `ItemTransfer` fields copied from bundle items when they are duplicated during order re-creation. Adding `ItemTransfer::SHIPMENT` ensures the shipment is preserved on each recurring order placement. | None | Pyz\Zed\ProductBundle | **src/Pyz/Zed/ProductBundle/ProductBundleConfig.php** ```php */ public function getAllowedBundleItemFieldsToCopy(): array { return [ ItemTransfer::SHIPMENT, ]; } } ``` {% info_block warningBox "Verification" %} Add a product bundle to the cart, set up a recurring order, and complete checkout. On the next scheduled order placement, make sure the bundle items are re-created with the correct shipment assignment. {% endinfo_block %} ### 5) Configure module behavior Override the following configuration methods in your project (if needed) to adjust the default behavior: **src/Pyz/Zed/OrderExperienceManagement/OrderExperienceManagementConfig.php** ```php > */ public function getReviewReasonGroupMap(): array { return array_merge_recursive(parent::getReviewReasonGroupMap(), [ SharedOrderExperienceManagementConfig::REVIEW_REASON_GROUP_UNAVAILABLE => [ // Add project-specific checkout error types here. ], ]); } /** * Specification: * - Returns the review reason groups whose items are treated as non-purchasable. * - Items in these groups block order placement and must be removed before the order can proceed. * - Default: [REVIEW_REASON_GROUP_UNAVAILABLE]. * - Override to add REVIEW_REASON_GROUP_DISCONTINUED if discontinued items should also block placement. * * @api * * @return array */ public function getNonPurchasableReviewReasonGroups(): array { return [ SharedOrderExperienceManagementConfig::REVIEW_REASON_GROUP_UNAVAILABLE, SharedOrderExperienceManagementConfig::REVIEW_REASON_GROUP_DISCONTINUED, ]; } } ``` | CONFIGURATION METHOD | DEFAULT | DESCRIPTION | | --- | --- | --- | | `getDefaultNotificationWindowHours()` | `48` | Number of hours before the trigger date when the pre-trigger notification is sent. | | `getReviewReasonGroupMap()` | See `OrderExperienceManagementConfig` | Maps review reason groups to checkout error types. Extend to map project-specific error types to the appropriate review group. | | `getNonPurchasableReviewReasonGroups()` | `[REVIEW_REASON_GROUP_UNAVAILABLE]` | Review reason groups whose items block order placement and must be removed before the order can proceed. Override to also block on `REVIEW_REASON_GROUP_DISCONTINUED`. | ## Install feature frontend Follow the steps below to install the Recurring Orders feature frontend. ### 1) Set up routes Register the following route provider plugin: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | RecurringOrderRouteProviderPlugin | Adds storefront routes for the recurring order list, detail, create, clear, pause, resume, skip, cancel, confirm, review, and approve-review actions. | None | SprykerFeature\Yves\OrderExperienceManagement\Plugin\Router | **src/Pyz/Yves/Router/RouterDependencyProvider.php** ```php */ protected function getRouteProvider(): array { return [ // ... new RecurringOrderRouteProviderPlugin(), #RecurringOrdersFeature ]; } } ``` After registering the plugin, warm up the router caches: ```bash vendor/bin/yves router:cache:warm-up vendor/bin/console router:cache:warm-up vendor/bin/console router:cache:warm-up:backend-gateway ``` {% info_block warningBox "Verification" %} Make sure the following storefront routes are accessible: - `/recurring-orders` — recurring order list page. - `/recurring-orders/{uuid}` — recurring order detail page. - `/recurring-orders/{uuid}/review-required` — review required page. - POST `/recurring-order/save` — saves recurring order settings on the quote. - POST `/recurring-order/clear` — removes recurring order settings from the quote. {% endinfo_block %} ### 2) Set up widgets Register the following global widgets: | WIDGET | DESCRIPTION | NAMESPACE | | --- | --- | --- | | RecurringOrderSelectorWidget | Renders the recurring order setup form at checkout. Visible only when the quote is eligible for a recurring order (invoice payment, not locked, not from RFQ, not guest). | SprykerFeature\Yves\OrderExperienceManagement\Widget | | RecurringOrderMenuItemWidget | Renders the Recurring Orders navigation menu item in the storefront company menu. | SprykerFeature\Yves\OrderExperienceManagement\Widget | | CostCenterDetailWidget | Displays the selected cost center and budget on the cart page. Takes a `QuoteTransfer` as input. Requires the [Purchasing Control feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-purchasing-control-feature.html). | SprykerFeature\Yves\PurchasingControl\Widget | **src/Pyz/Yves/ShopApplication/ShopApplicationDependencyProvider.php** ```php */ protected function getGlobalWidgets(): array { return [ // ... RecurringOrderSelectorWidget::class, #RecurringOrdersFeature RecurringOrderMenuItemWidget::class, #RecurringOrdersFeature CostCenterDetailWidget::class, #RecurringOrdersFeature ]; } } ``` ### 3) Add the recurring order selector to the checkout summary page The `RecurringOrderSelectorWidget` is not rendered automatically — it must be explicitly called from the checkout summary template. Add it after any cost center or voucher sections, before the order form. **src/Pyz/Yves/CheckoutPage/Theme/default/views/summary/summary.twig** ```twig {% raw %}{% widget 'RecurringOrderSelectorWidget' args [data.cart] only %}{% endwidget %}{% endraw %} ``` {% info_block warningBox "Verification" %} On the checkout summary page with an invoice-based payment method, make sure the **Set up as recurring order** checkbox and description are displayed. {% endinfo_block %} {% info_block warningBox "Verification" %} - On the cart page, make sure the selected cost center and budget names are displayed. {% endinfo_block %} ### 4) Add the menu item to the customer navigation sidebar To make the **Recurring Orders** menu item appear in the customer account sidebar, add a plain data entry to the `data.items` array in your project's customer navigation sidebar template. Place it after the Order History item. **src/Pyz/Yves/CustomerPage/Theme/default/components/molecules/navigation-sidebar/navigation-sidebar.twig** ```twig {% raw %} {% define data = { items: [ {# ... existing items ... #} { name: 'order', url: path('customer/order'), label: 'customer.account.order_history' | trans, icon: 'history', }, { name: 'recurring-orders', url: path('recurring-orders'), label: 'recurring_orders.menu_item' | trans, icon: 'calendar', }, {# ... remaining items ... #} ] } %} {% endraw %} ``` {% info_block warningBox "Verification" %} In the storefront customer account, make sure the **Recurring Orders** menu item appears directly below **Order History** in the left sidebar navigation and links to `/recurring-orders`. {% endinfo_block %} {% info_block infoBox "Alternative: widget-based menu item" %} If your project's navigation sidebar template doesn't use a plain `data.items` array — for example, it's built from a custom navigation plugin or uses a different template structure — you can render the menu item via `RecurringOrderMenuItemWidget` instead. Make sure the widget is registered in `ShopApplicationDependencyProvider` (see [Set up widgets](#2-set-up-widgets)), then call it from the `postContent` block of your sidebar template: ```twig {% raw %} {% block postContent %} {# ... existing widget calls ... #} {% widget 'RecurringOrderMenuItemWidget' args [data.activePage] only %}{% endwidget %} {% endblock %} {% endraw %} ``` The widget renders an `

` element and must be placed inside a `

` context. {% endinfo_block %} ### 5) Build the frontend After making changes to Twig templates and registering new widgets, rebuild the Yves frontend assets: ```bash npm run yves ``` {% info_block warningBox "Verification" %} Reload the checkout summary page and make sure the recurring order selector renders without console errors. {% endinfo_block %} ### 7) Import glossary data The full list of glossary keys is provided in the module at `src/SprykerFeature/OrderExperienceManagement/data/import/glossary.csv`. Copy the contents of that file and add them to **data/import/common/common/glossary.csv**. Import data: ```bash console data:import:glossary ``` {% info_block warningBox "Verification" %} Make sure that, in the database, the configured data has been added to the `spy_glossary_key` and `spy_glossary_translation` tables. {% endinfo_block %} ### 8) Configure the Back Office settings Sync the recurring orders configuration settings to the database to make them editable in the Back Office: ```bash console configuration:sync ``` {% info_block warningBox "Verification" %} In the Back Office, go to **Configuration > Recurring Orders > General > Schedule**. Make sure the **Schedule Grace Period** field is displayed with a default value of `48`. {% endinfo_block %} {% info_block infoBox "Configurable settings" %} | SETTING | DEFAULT | DESCRIPTION | | --- | --- | --- | | Schedule Grace Period | `48` | Number of hours before the trigger date when the pre-trigger notification email is sent to the buyer. Per-schedule overrides stored in `spy_recurring_schedule.notification_window_hours` take precedence over this global value. | {% endinfo_block %}

Install the Purchasing Control feature

Tue, 30 Jun 2026 11:01:37 +0000

{% info_block warningBox "Experimental feature" %} Experimental feature - not recommended for production use. {% endinfo_block %} This document describes how to install the [Purchasing Control feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/feature-overviews/purchasing-control-feature-overview.html). ## Install feature core Follow the steps below to install the Purchasing Control feature core. ### Prerequisites To start feature integration, review and install the necessary features: | NAME | VERSION | INSTALLATION GUIDE | | --- | --- | --- | | Spryker Core | {{page.release_tag}} | [Install the Spryker Core feature](/docs/pbc/all/miscellaneous/latest/install-and-upgrade/install-features/install-the-spryker-core-feature.html) | | Company Account | {{page.release_tag}} | [Install the Company Account feature](/docs/pbc/all/customer-relationship-management/latest/base-shop/install-and-upgrade/install-features/install-the-company-account-feature.html) | | Checkout | {{page.release_tag}} | [Install the Checkout feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-checkout-feature.html) | | Approval Process | {{page.release_tag}} | [Install the Approval Process feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-approval-process-feature.html) | ### 1) Install the required modules ```bash composer require spryker-feature/purchasing-control:"^1.0.0" spryker/sales:"^11.83.0" spryker/sales-extension:"^1.15.0" spryker-shop/checkout-page:"^3.40.0" spryker-shop/company-page:"^2.36.0" spryker-shop/customer-page:"^2.77.0" spryker-shop/shop-ui:"^1.108.0" --update-with-dependencies --ignore-platform-req=ext-grpc ``` ### 2) Set up database schema and transfer objects Apply database changes and generate entity and transfer changes: ```bash console propel:install console transfer:generate ``` {% info_block warningBox "Verification" %} Make sure the following changes have been applied in the database: | DATABASE ENTITY | TYPE | EVENT | | --- | --- | --- | | spy_cost_center | table | created | | spy_cost_center_to_company_business_unit | table | created | | spy_budget | table | created | | spy_budget_consumption | table | created | | spy_quote.fk_cost_center | column | created | | spy_quote.fk_budget | column | created | | spy_sales_order.fk_cost_center | column | created | | spy_sales_order.fk_budget | column | created | Make sure the following changes have been applied in transfer objects: | TRANSFER | TYPE | EVENT | PATH | | --- | --- | --- | --- | | CostCenter | class | created | src/Generated/Shared/Transfer/CostCenterTransfer.php | | CostCenterCollection | class | created | src/Generated/Shared/Transfer/CostCenterCollectionTransfer.php | | CostCenterCriteria | class | created | src/Generated/Shared/Transfer/CostCenterCriteriaTransfer.php | | CostCenterConditions | class | created | src/Generated/Shared/Transfer/CostCenterConditionsTransfer.php | | CostCenterCollectionRequest | class | created | src/Generated/Shared/Transfer/CostCenterCollectionRequestTransfer.php | | CostCenterCollectionResponse | class | created | src/Generated/Shared/Transfer/CostCenterCollectionResponseTransfer.php | | CostCenterResponse | class | created | src/Generated/Shared/Transfer/CostCenterResponseTransfer.php | | CostCenterQuoteUpdateRequest | class | created | src/Generated/Shared/Transfer/CostCenterQuoteUpdateRequestTransfer.php | | CostCenterQuoteUpdateResponse | class | created | src/Generated/Shared/Transfer/CostCenterQuoteUpdateResponseTransfer.php | | Budget | class | created | src/Generated/Shared/Transfer/BudgetTransfer.php | | BudgetCollection | class | created | src/Generated/Shared/Transfer/BudgetCollectionTransfer.php | | BudgetCriteria | class | created | src/Generated/Shared/Transfer/BudgetCriteriaTransfer.php | | BudgetConditions | class | created | src/Generated/Shared/Transfer/BudgetConditionsTransfer.php | | BudgetCollectionRequest | class | created | src/Generated/Shared/Transfer/BudgetCollectionRequestTransfer.php | | BudgetCollectionResponse | class | created | src/Generated/Shared/Transfer/BudgetCollectionResponseTransfer.php | | BudgetResponse | class | created | src/Generated/Shared/Transfer/BudgetResponseTransfer.php | | BudgetConsumption | class | created | src/Generated/Shared/Transfer/BudgetConsumptionTransfer.php | | BudgetConsumptionCollection | class | created | src/Generated/Shared/Transfer/BudgetConsumptionCollectionTransfer.php | | BudgetConsumptionCriteria | class | created | src/Generated/Shared/Transfer/BudgetConsumptionCriteriaTransfer.php | | BudgetConsumptionConditions | class | created | src/Generated/Shared/Transfer/BudgetConsumptionConditionsTransfer.php | | Quote.idCostCenter | property | created | src/Generated/Shared/Transfer/QuoteTransfer.php | | Quote.idBudget | property | created | src/Generated/Shared/Transfer/QuoteTransfer.php | | Quote.costCenter | property | created | src/Generated/Shared/Transfer/QuoteTransfer.php | | Quote.budget | property | created | src/Generated/Shared/Transfer/QuoteTransfer.php | | Order.fkCostCenter | property | created | src/Generated/Shared/Transfer/OrderTransfer.php | | Order.fkBudget | property | created | src/Generated/Shared/Transfer/OrderTransfer.php | | Order.costCenter | property | created | src/Generated/Shared/Transfer/OrderTransfer.php | | Order.budget | property | created | src/Generated/Shared/Transfer/OrderTransfer.php | | OrderTableCriteria.costCenterIds | property | created | src/Generated/Shared/Transfer/OrderTableCriteriaTransfer.php | | OrderTableCriteria.budgetIds | property | created | src/Generated/Shared/Transfer/OrderTableCriteriaTransfer.php | {% endinfo_block %} ### 3) Set up data import Register the following data import plugins: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | CostCenterDataImportPlugin | Imports cost centers from `cost_center.csv`. Creates or updates cost centers by key, name, description, and active status. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\DataImport | | BudgetDataImportPlugin | Imports budgets from `budget.csv`. Resolves the cost center by key and creates or updates budgets by cost center and name. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\DataImport | | CostCenterToCompanyBusinessUnitDataImportPlugin | Imports cost center to company business unit relations from `cost_center_company_business_unit.csv`. Skips already existing relations. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\DataImport | **src/Pyz/Zed/DataImport/DataImportDependencyProvider.php** ```php */ protected function getDataImporterPlugins(): array { return [ // ... new CostCenterDataImportPlugin(), #PurchasingControlFeature new BudgetDataImportPlugin(), #PurchasingControlFeature new CostCenterToCompanyBusinessUnitDataImportPlugin(), #PurchasingControlFeature ]; } } ``` Create the CSV import files: **data/import/common/common/cost_center.csv** ```csv key,name,description,is_active cc-marketing,Marketing,Marketing and communications expenses,1 cc-it,IT & Operations,IT infrastructure and software licenses,1 ``` **data/import/common/common/budget.csv** ```csv cost_center_key,name,amount,currency_iso_code,starts_at,ends_at,enforcement_rule,is_active cc-marketing,Marketing Q2 2026,50000,EUR,2026-04-01,2026-06-30,warn,1 cc-it,IT Software Licenses 2026,100000,EUR,2026-01-01,2026-12-31,block,1 cc-it,IT Hardware Approvals 2026,200000,EUR,2026-01-01,2026-12-31,require_approval,1 ``` **data/import/common/common/cost_center_company_business_unit.csv** ```csv cost_center_key,business_unit_key cc-marketing,spryker_systems_berlin cc-it,spryker_systems_berlin ``` Import the data: ```bash console data:import purchasing-control-cost-center console data:import purchasing-control-budget console data:import purchasing-control-cost-center-to-company-business-unit ``` {% info_block warningBox "Verification" %} In the Back Office, under **Customers > Cost Centers**, make sure the imported cost centers and budgets are displayed. Make sure the cost centers are assigned to the expected business units. {% endinfo_block %} ### 4) Set up behavior Enable the following behaviors by registering the plugins. #### Set up Zed plugins | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | ManageCostCentersPermissionPlugin | Grants permission to create, update, and manage cost centers. Assign this permission to company roles that should have access to Purchasing Control management pages. | None | SprykerFeature\Shared\PurchasingControl\Plugin\Permission | | BudgetCheckoutPreConditionPlugin | Validates the cart grand total against the remaining budget before checkout proceeds. Blocks checkout or triggers the approval flow depending on the budget enforcement rule. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Checkout | | CostCenterOrderSaverPlugin | Saves the selected cost center and budget references to the sales order during checkout. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Checkout | | ConsumeBudgetCheckoutPostSavePlugin | Records budget consumption immediately after the order is saved so the remaining budget balance is accurate for concurrent buyers. Does nothing when no budget is selected on the quote. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Checkout | | CostCenterQuoteExpanderPlugin | Expands the quote with the default cost center assigned to the buyer's business unit when no cost center is already set. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Quote | | CostCenterQuoteFieldsAllowedForSavingProviderPlugin | Adds `idCostCenter` and `idBudget` to the list of quote fields persisted to the database. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Quote | | RestoreBudgetOnCancelOmsCommandPlugin | Restores the budget balance by deducting the amount of the canceled order items. Also deducts the shipment group total if all items in the group are canceled. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Oms | | RestoreBudgetOnRefundOmsCommandPlugin | Restores the budget balance by deducting the refundable amount of the refunded order items. When refund with shipment is enabled, also deducts the shipment group expense refundable amount if all items in the group are refunded. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Oms | | CostCenterOrderExpanderPlugin | Expands `OrderTransfer` with the assigned cost center and company name, and with the assigned budget when present. Does nothing when no cost center is assigned to the order. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Sales | | CostCenterSearchOrderExpanderPlugin | Expands each `OrderTransfer` in a list with `CostCenterTransfer` and `BudgetTransfer` when assigned. Used for order search results. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Sales | | CostCenterOrderSearchQueryExpanderPlugin | Expands `QueryJoinCollectionTransfer` with `WHERE` conditions for `fk_cost_center` and `fk_budget` when filter fields of type `costCenter` or `budget` are present. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Sales | | CostCenterOrdersTableQueryExpanderPlugin | Adds a `LEFT JOIN` from `spy_sales_order.fk_cost_center` to `spy_cost_center.id_cost_center` and exposes `cost_center_name` as a virtual column on the Back Office orders table query. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Sales | | CostCenterOrdersTableHeaderExpanderPlugin | Inserts a **Cost Center** column before the **Actions** column in the Back Office orders table. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Sales | | CostCenterOrdersTableFilterFormExpanderPlugin | Adds cost center and budget multi-select filter fields to the Back Office orders table filter form. Budget choices are loaded via AJAX filtered by the selected cost centers. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Sales | | CostCenterOrdersTableCriteriaFilterExpanderPlugin | Filters the Back Office orders table by `costCenterIds` and `budgetIds` when present on `OrderTableCriteriaTransfer`. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Sales | | CostCenterSalesTablePlugin | Normalizes the `cost_center_name` column to `-` for orders that have no cost center assigned. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Sales | #### Set up permissions **src/Pyz/Zed/Permission/PermissionDependencyProvider.php** ```php */ protected function getPermissionPlugins(): array { return [ // ... new ManageCostCentersPermissionPlugin(), #PurchasingControlFeature ]; } } ``` **src/Pyz/Client/Permission/PermissionDependencyProvider.php** ```php */ protected function getPermissionPlugins(): array { return [ // ... new ManageCostCentersPermissionPlugin(), #PurchasingControlFeature ]; } } ``` Sync the permission plugins to the database: ```bash console sync:data permission ``` {% info_block warningBox "Verification" %} In the Back Office, under **Customers > Company Roles**, assign the **ManageCostCentersPermissionPlugin** permission to a company role. Make sure company users with that role can access the cost center management pages on the Storefront. {% endinfo_block %} {% info_block infoBox "Require Approval enforcement rule" %} If you configure budgets with the **Require Approval** enforcement rule, the following [Approval Process](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-approval-process-feature.html) permissions must be registered and assigned to company roles for the approval workflow to function: | PERMISSION | REQUIRES | | --- | --- | | Buy up to grand total (`PlaceOrderPermissionPlugin`) | Send cart for approval | | Send cart for approval (`RequestQuoteApprovalPermissionPlugin`) | Buy up to grand total | | Approve up to grand total (`ApproveQuotePermissionPlugin`) | None | For plugin registration details, see [Install the Approval Process feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-approval-process-feature.html). {% endinfo_block %} #### Set up Checkout plugins **src/Pyz/Zed/Checkout/CheckoutDependencyProvider.php** ```php */ protected function getCheckoutPreConditions(Container $container): array { return [ // ... new BudgetCheckoutPreConditionPlugin(), #PurchasingControlFeature ]; } /** * @param \Spryker\Zed\Kernel\Container $container * * @return list<\Spryker\Zed\Checkout\Dependency\Plugin\CheckoutSaveOrderInterface|\Spryker\Zed\CheckoutExtension\Dependency\Plugin\CheckoutDoSaveOrderInterface> */ protected function getCheckoutOrderSavers(Container $container): array { return [ // ... new CostCenterOrderSaverPlugin(), #PurchasingControlFeature ]; } /** * @param \Spryker\Zed\Kernel\Container $container * * @return list<\Spryker\Zed\CheckoutExtension\Dependency\Plugin\CheckoutPostSaveInterface> */ protected function getCheckoutPostHooks(Container $container): array { return [ // ... new ConsumeBudgetCheckoutPostSavePlugin(), #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} When a buyer places an order with a budget selected, verify the following: - Checkout is blocked when the order exceeds a budget with the **Block** enforcement rule. - An approval request is triggered when the order exceeds a budget with the **Require Approval** rule. - A warning is displayed when the order exceeds a budget with the **Warn** rule. - A `spy_budget_consumption` record is created after the order is successfully placed. - The cost center and budget IDs are saved on the `spy_sales_order` record. {% endinfo_block %} #### Set up Quote plugins **src/Pyz/Zed/Quote/QuoteDependencyProvider.php** ```php */ protected function getQuoteExpanderPlugins(): array { return [ // ... new CostCenterQuoteExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\Spryker\Zed\QuoteExtension\Dependency\Plugin\QuoteFieldsAllowedForSavingProviderPluginInterface> */ protected function getQuoteFieldsAllowedForSavingProviderPlugins(): array { return [ // ... new CostCenterQuoteFieldsAllowedForSavingProviderPlugin(), #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} When a buyer with an assigned business unit opens a cart, make sure the quote is automatically expanded with the default cost center of their business unit. Make sure `idCostCenter` and `idBudget` are persisted to the `spy_quote` table when the quote is saved. {% endinfo_block %} #### Set up Sales plugins **src/Pyz/Zed/Sales/SalesDependencyProvider.php** ```php */ protected function getOrderHydrationPlugins(): array { return [ // ... new CostCenterOrderExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\Spryker\Zed\SalesExtension\Dependency\Plugin\SearchOrderExpanderPluginInterface> */ protected function getSearchOrderExpanderPlugins(): array { return [ // ... new CostCenterSearchOrderExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\Spryker\Zed\SalesExtension\Dependency\Plugin\SearchOrderQueryExpanderPluginInterface> */ protected function getOrderSearchQueryExpanderPlugins(): array { return [ // ... new CostCenterOrderSearchQueryExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\Spryker\Zed\SalesExtension\Dependency\Plugin\OrdersTableQueryExpanderPluginInterface> */ protected function getOrdersTableQueryExpanderPlugins(): array { return [ // ... new CostCenterOrdersTableQueryExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\Spryker\Zed\SalesExtension\Dependency\Plugin\OrdersTableHeaderExpanderPluginInterface> */ protected function getOrdersTableHeaderExpanderPlugins(): array { return [ // ... new CostCenterOrdersTableHeaderExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\Spryker\Zed\SalesExtension\Dependency\Plugin\OrdersTableFilterFormExpanderPluginInterface> */ protected function getOrdersTableFilterFormExpanderPlugins(): array { return [ // ... new CostCenterOrdersTableFilterFormExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\Spryker\Zed\SalesExtension\Dependency\Plugin\OrdersTableCriteriaFilterExpanderPluginInterface> */ protected function getOrdersTableCriteriaFilterExpanderPlugins(): array { return [ // ... new CostCenterOrdersTableCriteriaFilterExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\Spryker\Zed\SalesExtension\Dependency\Plugin\SalesTablePluginInterface> */ protected function getSalesTablePlugins(): array { return [ // ... new CostCenterSalesTablePlugin(), #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} - In the Back Office, open **Sales > Orders**. Make sure the **Cost Center** column is displayed in the orders table. - Make sure the orders table filter form includes cost center and budget multi-select fields. - Open an individual order. Make sure the cost center and budget names are displayed on the order detail page. - In the storefront, open **My Account > Orders**. Make sure the cost center and budget data appear on completed orders. {% endinfo_block %} ### 5) Configure Back Office navigation Add the Purchasing Control section to the Back Office navigation: **config/Zed/navigation.xml** ```xml ... ... Cost Centers Cost Centers purchasing-control cost-center index ``` Rebuild the navigation cache: ```bash console navigation:build-cache ``` {% info_block warningBox "Verification" %} In the Back Office, under **Customers**, make sure the **Cost Centers** menu item is displayed and links to the cost center list page. {% endinfo_block %} ### 6) Configure the OMS process Register the OMS command plugins and configure the OMS process XML. #### Register OMS command plugins **src/Pyz/Zed/Oms/OmsDependencyProvider.php** ```php extend(self::COMMAND_PLUGINS, function (CommandCollectionInterface $commandCollection) { // ... $commandCollection->add(new RestoreBudgetOnCancelOmsCommandPlugin(), 'CostCenter/RestoreBudgetOnCancel'); #PurchasingControlFeature $commandCollection->add(new RestoreBudgetOnRefundOmsCommandPlugin(), 'CostCenter/RestoreBudgetOnRefund'); #PurchasingControlFeature return $commandCollection; }); return $container; } } ``` #### Configure the OMS process XML Add the `CostCenter/RestoreBudgetOnCancel` and `CostCenter/RestoreBudgetOnRefund` commands to the relevant events in your OMS process XML. The following example uses `DummyPayment01`: **config/Zed/oms/DummyPayment01.xml** ```xml ... ... ``` #### Configure budget restoration behavior By default, shipment costs are not included when restoring the budget on refund. To include shipment costs, override `isRefundWithShipmentEnabled()` in your project config: **src/Pyz/Zed/PurchasingControl/PurchasingControlConfig.php** ```php */ protected function getGlobalWidgets(): array { return [ // ... CostCenterMenuItemWidget::class, #PurchasingControlFeature PurchasingControlSummaryWidget::class, #PurchasingControlFeature CostCenterSelectorWidget::class, #PurchasingControlFeature CostCenterDetailWidget::class, #PurchasingControlFeature CostCenterOrderDetailWidget::class, #PurchasingControlFeature CostCenterBudgetFilterWidget::class, #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} - Make sure all six widgets are available in Twig templates. - On the storefront company dashboard, make sure the **Purchasing Control** summary widget displays cost center and budget data. - On the checkout summary page, make sure the cost center and budget selector is displayed. - On the order detail page, make sure the assigned cost center and budget names are displayed. - On the order history page, make sure the cost center and budget filter controls are displayed. {% endinfo_block %} ### 3) Extend the ShopUi select component Extend the ShopUi `select` atom to render HTML attributes for the cost center and budget selectors: **src/Pyz/Yves/ShopUi/Theme/default/components/atoms/select/select.twig** ```twig {% raw %}{% block attributes %} {%- for attrname, attrvalue in attr | default({}) -%} {%- if attrvalue is same as(true) -%} {{ attrname }}="{{ attrname }}" {%- elseif attrvalue is not same as(false) -%} {{ attrname }}="{{ attrvalue }}" {%- endif -%} {%- endfor -%} {% endblock %}{% endraw %} ``` {% info_block warningBox "Verification" %} Make sure the cost center and budget dropdowns correctly disable unavailable options. {% endinfo_block %} ### 4) Extend the checkout summary template Add the `CostCenterSelectorWidget` to the checkout summary page, placing it directly above the `QuoteApprovalWidget` call: **src/SprykerShop/CheckoutPage/src/SprykerShop/Yves/CheckoutPage/Theme/default/views/summary/summary.twig** ```twig

{% raw %}{% widget 'CostCenterSelectorWidget' args [data.cart] only %}{% endwidget %}{% endraw %} {% raw %}{% widget 'QuoteApprovalWidget' args [data.cart] only %}{% endwidget %}{% endraw %}

``` {% info_block warningBox "Verification" %} On the checkout summary page, make sure the cost center and budget selector is displayed above the approval widget. {% endinfo_block %} ### 5) Set up routes Register the following route provider plugins: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | CostCenterRouteProviderPlugin | Adds storefront routes for cost center list, create, update, and quote update actions. | None | SprykerFeature\Yves\PurchasingControl\Plugin\Router | | BudgetRouteProviderPlugin | Adds storefront routes for budget list, create, and update actions. | None | SprykerFeature\Yves\PurchasingControl\Plugin\Router | **src/Pyz/Yves/Router/RouterDependencyProvider.php** ```php */ protected function getRouteProvider(): array { return [ // ... new CostCenterRouteProviderPlugin(), #PurchasingControlFeature new BudgetRouteProviderPlugin(), #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} - Make sure the cost center list, create, and update pages are accessible under `/company/cost-center`. - Make sure submitting the cost center selector form in the cart updates the quote with the selected cost center and budget. - Make sure the budget list, create, and update pages are accessible. {% endinfo_block %} ### 6) Extend the order search form Register the following plugins to add cost center and budget filter fields to the storefront order history search form: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | CostCenterOrderSearchFormExpanderPlugin | Adds cost center and budget filter dropdowns to the order history search form. Only adds fields when the current customer is a company user. | None | SprykerFeature\Yves\PurchasingControl\Plugin\CustomerPage | | CostCenterOrderSearchFormHandlerPlugin | Maps selected cost center and budget IDs from the filter form to `FilterFieldTransfer` entries on `OrderListTransfer`. | None | SprykerFeature\Yves\PurchasingControl\Plugin\CustomerPage | **src/Pyz/Yves/CustomerPage/CustomerPageDependencyProvider.php** ```php */ protected function getOrderSearchFormExpanderPlugins(): array { return [ // ... new CostCenterOrderSearchFormExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\SprykerShop\Yves\CustomerPageExtension\Dependency\Plugin\OrderSearchFormHandlerPluginInterface> */ protected function getOrderSearchFormHandlerPlugins(): array { return [ // ... new CostCenterOrderSearchFormHandlerPlugin(), #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} On the storefront **My Account > Orders** page, make sure company users see cost center and budget filter dropdowns. Make sure filtering by cost center or budget returns the expected orders. {% endinfo_block %}

Security release notes 202606.0

Mon, 29 Jun 2026 13:23:46 +0000

This document describes the security-related issues that have been recently resolved. For additional support with this content, [contact our support](https://support.spryker.com/). If you found a new security vulnerability, contact us at [security@spryker.com](mailto:security@spryker.com). ## Information disclosure via phpinfo() method {% info_block warningBox "Prerequisite" %} This security update requires [Spryker 202604.0](/docs/about/all/releases/release-notes-202604.0.html) or later. Ensure your project is upgraded to this version before applying the fix. {% endinfo_block %} Instances of phpinfo() were identified in the codebase, which could potentially expose sensitive configuration details and environment variables to unauthorized parties. Such an instance was found to be part of the default Back Office setup. ### Affected modules - `spryker/setup`: < 4.8.0 - `spryker/maintenance`: < 3.6.0 ### Fix the vulnerability Update the `spryker/setup` package to version 4.8.0 or higher: ```bash composer update spryker/setup:"^4.8.0" composer show spryker/setup # Verify the version ``` Update the `spryker/maintenance` package to version 4.0.0 or higher: ```bash composer update spryker/maintenance:"^4.0.0" composer show spryker/maintenance # Verify the version ``` ## Possible brute force attack in adding discount voucher / gift card codes An automated attack could attempt to guess valid strings by using every possible combination and/or pre-defined dictionaries. In the site frontend, there is the possibility to use a discount code (voucher) or a gift card code, which is a predefined or randomized string. ### Affected modules - `spryker-shop/cart-code-widget`: < 1.6.0 ### Fix the vulnerability Update the `spryker-shop/cart-code-widget` package to version 1.7.0 or higher: ```bash composer update spryker-shop/cart-code-widget:"^1.7.0" composer show spryker-shop/cart-code-widget # Verify the version ``` Enable `SecurityBlockerCartCodeEventDispatcherPlugin` plugin: **src/Pyz/Yves/EventDispatcher/EventDispatcherDependencyProvider.php** ```php */ protected function getEventDispatcherPlugins(): array { return [ new SecurityBlockerCartCodeEventDispatcherPlugin(), ]; } } ``` {% info_block warningBox "Verification" %} 1. From the cart page, submit an invalid voucher or gift card code multiple times. 2. After exceeding the configured number of attempts, make sure the request is blocked and the `cart_code_widget.error.too_many_requests` error message is displayed. {% endinfo_block %} Add glossary translations for the message `cart_code_widget.error.too_many_requests`. ## File enumeration via predictable file IDs in File Manager Files stored through the File Manager module were referenced using sequential numeric IDs, making it possible to enumerate and access files by guessing IDs. Introducing UUID-based identifiers for file entities prevents unauthorized enumeration of file resources. ### Affected modules - `spryker/file-manager`: < 2.9.0 - `spryker/file-manager-storage`: < 2.7.0 - `spryker-shop/content-file-widget`: < 2.1.0 - `spryker-shop/file-manager-widget`: < 2.1.0 - `spryker/synchronization-behavior`: < 1.15.0 - `spryker/propel`: < 3.50.1 ### Fix the vulnerability Update the affected packages: ```bash composer update spryker/file-manager:"^2.9.0" spryker/file-manager-storage:"^2.7.0" spryker-shop/content-file-widget:"^2.1.0" spryker-shop/file-manager-widget:"^2.1.0" spryker/synchronization-behavior:"^1.15.0" spryker/propel:"^3.50.1" --update-with-dependencies ``` ### Activate UUID for file entities 1. Enable UUID generation by overriding `FileManagerConfig::isUuidEnabled()` in your project configuration. By default, UUID generation is disabled. **src/Pyz/Zed/FileManager/FileManagerConfig.php** ```php

How to integrate API Platform

Mon, 29 Jun 2026 11:21:50 +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 ``` ## 8. Warm the API Platform router cache API Platform registers its operations as routes in the standard Symfony router. With debug disabled (production), the compiled router dump is written once and then frozen for the life of the container, so it **must** be built against the fully generated resource collection. After generating resources (step 5), warm the cache for each Glue application: ```bash docker/sdk cli GLUE_APPLICATION=GLUE_STOREFRONT glue cache:warmup docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue cache:warmup ``` {% info_block warningBox "Required on AWS and any multi-container deployment" %} This step is mandatory in cloud (AWS ECS) and any split build/runtime topology. If the router dump is built before resources are generated—or never warmed in the runtime container—every API request returns HTTP 404 and the empty dump stays frozen for the life of the container. Use `cache:warmup` (or `cache:clear`), **not** `api:router:cache:warm-up`, which warms only the legacy Glue router and does not build the API Platform router dump. For the full explanation, multi-container guidance, and recovery steps, see [Cache warming](/docs/dg/dev/architecture/api-platform.html#cache-warming) and [Multi-container and cloud deployments](/docs/dg/dev/architecture/api-platform.html#multi-container-and-cloud-deployments) in the architecture guide. {% endinfo_block %} ## 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

Mon, 29 Jun 2026 11:21:50 +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

API Platform deployment requires two sequential steps, not alternatives:

Generate the API resource classes from the schema files:

docker/sdk cli glue api:generate

Warm the application cache—including the router cache—once the resources from step 1 exist. Run it per Glue application:

docker/sdk cli GLUE_APPLICATION=GLUE_STOREFRONT glue cache:warmup
docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue cache:warmup

API Platform registers its operations as routes in the standard Symfony router, whose compiled matcher and generator are dumped to data/cache/Glue<Storefront|Backend>/<environment>/url_matching_routes.php and url_generating_routes.php. cache:warmup builds these dumps from the resource collection produced in step 1. Add both steps to your deployment and installation recipes for every API Platform application.

Use cache:warmup, not api:router:cache:warm-up

api:router:cache:warm-up warms only the legacy Glue (GlueApplication) custom-route router—it does not build the API Platform router dump. Use cache:warmup (or cache:clear) to warm the API Platform router.

Multi-container and cloud deployments

In production, applications run with debug disabled. The router dump is then written once and never revalidated—whatever route set it was first built from is frozen for the life of the container.

In a single-container setup this is harmless: the cache is warmed in the same place that serves requests, with the full route set. In a multi-container topology where resource generation runs in a build container and requests are served by a separate runtime container (for example, AWS ECS), you must guarantee the router dump is built against the complete resource collection for the runtime container—either warmed in the runtime container after deployment, or baked at build time only if data/cache is shipped to every runtime replica with the full route set.

If the dump is built before resources are generated (an empty or incomplete collection), the runtime container freezes that empty dump and:

every API request returns HTTP 404 (Glue code 007, legacy fallthrough) because the route is absent from the matcher;
once the matcher is partially rebuilt, data endpoints return HTTP 500 from IRI generation (RouteNotFoundException), because the URL generator dump is also empty;
/docs.json returns 0 paths, even though api:debug --list shows the resources resolving correctly.

To recover a frozen container, clear and re-warm the cache (cache:clear) with the full resource collection present.

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

Next steps

Spryker API roadmap and adoption

Thu, 25 Jun 2026 13:34:37 +0000

This page continues the Spryker API Strategy. It covers the API types on the roadmap, how to choose one, why API Platform integration, your migration decision, and the rollout timeline.

What’s on the roadmap

Planned API types, listed so you can plan ahead. Availability is announced per type; treat these as direction, not a build target.

API type	Application	Caller (actor)	Use it when
Merchant API	Backend	Marketplace merchant (single-merchant scope)	A merchant manages their own catalog, offers, orders, or payouts record-by-record through a UI or tool
Merchant Data Exchange API	Backend	Merchant-side integration system	A merchant bulk-imports or bulk-exports their own data between their systems and the marketplace
Data Exchange API	Backend	Platform-operator integration system	The operator moves large datasets in or out at platform level (PIM, ERP, OMS, BI)
Async Event API	Backend	Event subscriber (broker or webhook)	An external system needs to react to Spryker events instead of polling

Choosing an API type

Pick by who is calling and the shape of the data flow (one record at a time, bulk, or event-driven).

Your situation	Use
A customer browses, shops, and checks out	Storefront API
An administrator manages catalog, orders, or customers	Back Office API
A merchant manages their own data through a UI, record by record	Merchant API
A merchant bulk-imports or bulk-exports their own data	Merchant Data Exchange API
The platform operator moves large datasets (PIM, ERP, OMS)	Data Exchange API
An external system reacts to events (order placed, stock changed)	Async Event API

Each API type has its own actor and authentication, so a token for one type does not grant access to another. Storefront uses customer authentication; Back Office uses administrator authentication; Merchant uses merchant-scoped authentication that restricts every call to a single merchant’s data; the data and event types use system credentials issued by the platform operator.

Why API Platform integration

What you get, in developer terms:

Contract-first APIs → the contract is the source of truth, so you can generate typed clients and catch breaking changes before they ship.
Versioning and content negotiation → platform upgrades stop silently breaking your integration; you opt into changes.
application/csv, application/xml, application/ld+json → your ERP or PIM integration can drop its custom transformation layer and exchange the format it already speaks.
Built for large data exchange → bulk import/export is a first-class path, not a workaround.
Standardized integration patterns → the same conventions across every API type, so a second integration is faster than the first.
Runs alongside Glue → adopt it per endpoint, with no flag day and nothing to switch off.

Before and after: your migration decision

You only have a decision to make if you’re on Glue and weighing a move. Here’s the whole picture:

	On Glue today	After moving to API Platform integration
Existing endpoints	Keep working, supported, no EOL	Unchanged — migrate only what you choose
New endpoints you build	Possible, but no new Spryker features land here	Recommended path; new features available
Breaking changes on upgrade	Possible	Controlled through versioning
Data format handling	Custom transformation in your code	Native CSV / XML / JSON-LD
Effort to adopt	—	Incremental, endpoint by endpoint

You should consider moving when you’re building a new integration, exchanging large datasets, connecting an external system (ERP, PIM, OMS), or you want upgrade-safe versioning. You can stay on Glue indefinitely for everything that already works.

Spryker supports the move with documentation of behavioral differences, endpoint-by-endpoint migration, and conversion tools and reference implementations.

Timeline

API Platform integration is generally available. The rollout ran as follows:

Milestone	When	What it means
Early access	Through Q1 2026	Available for new features ahead of GA, with a limited support scope; native features (authentication, codebuckets, full JSON:API) not yet fully integrated
Glue feature freeze	From Q1 2026	New Spryker features target API Platform integration only. Glue gets bugfixes, security, and compatibility — no new endpoints
General availability	Apr 30, 2026	Full support; recommended for all new integrations
Glue REST module migration	In progress	Spryker-provided modules move to API Platform. Check the migration status page

The Q1 feature freeze and the April GA work together: from Q1, new features were built on API Platform integration and shipped through the early-access window, reaching full support at GA. Feature freeze means no new Glue functionality — it is not deprecation, and there is no End-of-Life.

FAQ

These cover the edge cases the tables above don’t.

How is the Merchant API different from the Back Office API? Back Office serves Spryker administrators with platform-wide scope. Merchant serves a single marketplace merchant — every call is restricted to that merchant’s own data.

How is the Merchant API different from the Merchant Data Exchange API? Both are merchant-scoped. Merchant API is for record-by-record operations through interfaces and tools. Merchant Data Exchange API is for bulk, file-based, or queue-based flows between a merchant’s systems and the marketplace.

How is the Data Exchange API different from the Merchant Data Exchange API? Same capabilities, different scope. Data Exchange operates at platform level with operator credentials. Merchant Data Exchange is restricted to one merchant’s data with per-merchant credentials.

How is the Data Exchange API different from the Async Event API? Data Exchange is request-driven — your system calls Spryker to import, export, or read. Async Event is event-driven — Spryker notifies your system when something happens. Choose by whether you poll or react.

Spryker API Strategy

Thu, 25 Jun 2026 11:07:26 +0000

What this means for you

On Glue today? Nothing breaks. Glue is fully supported, there is no End-of-Life, and you don’t have to migrate existing features.
Building something new? Build it on API Platform integration. It is generally available and is where all new Spryker features ship.
Need a Spryker Core feature released after Q1 2026? It will be available through API Platform integration only.

Everything below is supporting detail.

Glue keeps working and isn’t going away. New features are built on API Platform integration. Migration is optional.

How the pieces fit

Spryker’s APIs are described by three independent axes. They are easy to confuse because some names repeat across axes, so read them as orthogonal:

Application — where the API lives. Two of them: Storefront API and Backend API.
API type — what you call and who the caller is (a customer, an administrator, a merchant, a system). Several types live under each application.
Foundation — how it’s built underneath: Glue or API Platform integration. This is a foundation beneath the API, not something you call directly.

API type	Application (where)	Foundation (how it’s built)
Storefront API	Storefront API	Glue or API Platform integration
Back Office API	Backend API	Glue or API Platform integration
Merchant API	Backend API	API Platform integration
Merchant Data Exchange API	Backend API	API Platform integration
Data Exchange API	Backend API	API Platform integration
Async Event API	Backend API	API Platform integration

Read the table across, not down: each API type belongs to one application and is built on one foundation, and those two facts are independent of each other. “Storefront API” names both an application and the type it hosts; “API Platform integration” is a foundation, not an endpoint you target. During the transition, an existing type can be served by either foundation.

Naming watch-out

The Backend API application is not the same as the Back Office API type. The Backend API application hosts several types of API, one of which is Back Office API.

What you can build on today

These are callable now:

API type	Application	Caller (actor)	Use it when
Storefront API	Storefront	Customer (authenticated or guest)	You’re building any customer-facing shopping experience
Back Office API	Backend	Back Office administrator or trusted internal service	You’re automating or replacing Back Office administration

For the API types on the roadmap, guidance on choosing between them, why API Platform integration, your migration decision, and the rollout timeline, see Spryker API roadmap and adoption.

FAQ

These cover the edge cases the tables above don’t.

Is API Platform integration something I call, or something underneath what I call? Underneath. You call an API type (Storefront, Back Office, and so on). API Platform integration is the foundation it’s built on, replacing Glue for new work.

How is the Backend API application different from the Back Office API type? The Backend API is the application that hosts several types. Back Office is one of those types, for administrator-level operations. Same word root, different axis.

Do I have to migrate my existing Glue APIs? No. Migration is optional and there is no End-of-Life.

Spryker Documentation

Add variables in the Parameter Store

Customer-owned and Spryker-owned variables

Customer-owned variables with limited access

Naming convention for variables

Reserved variables

Variable path hierarchy

Add variables

Add parameters to all resource types

Add secrets to all resource types

Add parameters to ECS applications

Adding secrets to ECS applications

Add parameters and secrets to Scheduler

Recurring Orders feature overview

Install the Recurring Orders feature

Install the Purchasing Control feature

Security release notes 202606.0

How to integrate API Platform

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

Debug commands

Features

Automatic OpenAPI documentation

Built-in validation

Pagination support

Operation-specific behavior

Relationships

Sparse fieldsets

Performance

Cache warming

Multi-container and cloud deployments

Property-level access control

Comparison with Glue API

Related documentation

Next steps

Spryker API roadmap and adoption

What’s on the roadmap

Choosing an API type

Why API Platform integration

Before and after: your migration decision

Timeline

FAQ

Spryker API Strategy

What this means for you

How the pieces fit

What you can build on today

FAQ