Spryker Documentation

Enable and disable maintenance mode

Wed, 22 Apr 2026 07:07:32 +0000

Maintenance mode is used many cases, like deploying a new application version or fixing an unexpected error. To automate the process, we created dedicated pipelines for enabling and disabling maintenance mode. The following sections describe how to run maintenance mode pipelines. After you update the maintenance page, rebuild the images by running a normal or destructive deployment pipeline.

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.

Prerequisites

When you enable maintenance mode, the landing pages of your applications, like the Back Office or Storefront, are replaced with maintenance pages in public//maintenance/index.html. Adjust the pages to match the design of your application and fulfill business requirements.

Per-store and per-region maintenance pages

Per-store and per-region maintenance pages require Docker SDK version 1.75.0 or higher.

By default, all endpoints of an application share the same maintenance page located at public/{application}/maintenance/index.html—for example, public/Yves/maintenance/index.html.

You can customize the maintenance page per store or per region by placing an index.html file in a subdirectory named after the store or region code:

public/Yves/maintenance/
├── index.html          # Default maintenance page (fallback)
├── EU/
│   └── index.html      # Maintenance page for EU region
├── US/
│   └── index.html      # Maintenance page for US region
├── DE/
│   └── index.html      # Maintenance page for DE store (legacy store mode)
└── AT/
    └── index.html      # Maintenance page for AT store (legacy store mode)

The same structure applies to all applications, such as Backoffice, MerchantPortal, and Zed.

Nginx resolves the maintenance page using the following fallback order.

Dynamic store mode (region-based endpoints):

maintenance/{region}/index.html—region-specific page
maintenance/index.html—default page

Legacy store mode (store-based endpoints):

maintenance/{store}/index.html—store-specific page
maintenance/{region}/index.html—region-specific page
maintenance/index.html—default page

If no store-specific or region-specific page exists, the default maintenance/index.html is served. The default maintenance page is required and must always be present.

Enable maintenance mode

In the AWS Management Console, go to Services > CodePipeline.
On the Pipelines pane, click Maintenance_Enable_{ENVIRONMENT_NAME}.
On the pipeline’s page, click Release change.

The deployment time depends on the application’s complexity. Once the deployment is finished, Storefront and Back Office visitors should see the maintenance page. To get access to the frontend applications in maintenance mode, you can allowlist the needed IP addresses. For instructions, see Configure access to applications in maintenance mode.

Disable maintenance mode

In the AWS Management Console, go to Services > CodePipeline.
On the Pipelines pane, click Maintenance_Disable_{ENVIRONMENT_NAME}.
On the pipeline’s page, click Release change.

The deployment time depends on the application’s complexity. Once the deployment is finished, Storefront and Back Office visitors will be able to access the application.

Integrate Vertex

Tue, 21 Apr 2026 13:03:28 +0000

This document describes how to integrate [Vertex](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/vertex.html) into a Spryker shop. ## Prerequisites Before integrating Vertex, ensure the following prerequisites are met: - Make sure that your deployment pipeline executes database migrations. ## 1. Install the module Install the Vertex module using Composer: ```bash composer require spryker-eco/vertex ``` ## 2. Configure the module Add the following configuration to `config/Shared/config_default.php`: ```php use SprykerEco\Shared\Vertex\VertexConstants; $config[VertexConstants::IS_ACTIVE] = getenv('VERTEX_IS_ACTIVE'); $config[VertexConstants::CLIENT_ID] = getenv('VERTEX_CLIENT_ID'); $config[VertexConstants::CLIENT_SECRET] = getenv('VERTEX_CLIENT_SECRET'); $config[VertexConstants::SECURITY_URI] = getenv('VERTEX_SECURITY_URI'); $config[VertexConstants::TRANSACTION_CALLS_URI] = getenv('VERTEX_TRANSACTION_CALLS_URI'); // Optional: Tax ID Validator (requires Vertex Validator, previously known as Taxamo, see https://developer.vertexinc.com/vertex-e-commerce/docs/stand-alone-deployments) $config[VertexConstants::TAXAMO_API_URL] = getenv('TAXAMO_API_URL'); $config[VertexConstants::TAXAMO_TOKEN] = getenv('TAXAMO_TOKEN'); // Optional: Vendor Code $config[VertexConstants::VENDOR_CODE] = ''; ``` ### Required configuration constants | Constant | Description | Where to get the value | |----------|-------------|------------------------| | `IS_ACTIVE` | Enables or disables Vertex tax calculation. | Set to `true` to enable. | | `CLIENT_ID` | OAuth client ID for the Vertex API. | Obtain from your Vertex account. For details, see [Vertex documentation](https://tax-calc-api.vertexcloud.com/resources/index.html). | | `CLIENT_SECRET` | OAuth client secret for the Vertex API. | Obtain from your Vertex account. For details, see [Vertex documentation](https://tax-calc-api.vertexcloud.com/resources/index.html). | | `SECURITY_URI` | Vertex OAuth security endpoint. | Obtain from your Vertex platform. For details, see [Vertex documentation](https://tax-calc-api.vertexcloud.com/resources/index.html). | | `TRANSACTION_CALLS_URI` | Vertex transaction calls endpoint. | Obtain from your Vertex platform. For details, see [Vertex documentation](https://tax-calc-api.vertexcloud.com/resources/index.html). | ### Optional configuration constants | Constant | Description | Where to get the value | |----------|-------------|------------------------| | `TAXAMO_API_URL` | Vertex Validator API URL for tax ID validation. | Obtain from your Vertex Validator environment. For details, see [Standalone Vertex Validator](https://developer.vertexinc.com/vertex-e-commerce/docs/stand-alone-deployments). | | `TAXAMO_TOKEN` | Vertex Validator API authentication token. | Obtain from your Vertex Validator account. For details, see [Accessing the APIs](https://developer.vertexinc.com/vertex-marketplaces/docs/getting-started-1). | | `VENDOR_CODE` | Vendor code for Vertex tax calculations. | Set in your Vertex account. | | `DEFAULT_TAXPAYER_COMPANY_CODE` | Default taxpayer company code. | The company code you set in your Vertex account. | ## 3. Override feature flags The `isTaxIdValidatorEnabled`, `isTaxAssistEnabled`, and `isInvoicingEnabled` methods default to `false` and are not driven by constants. To enable them, override `src/Pyz/Zed/Vertex/VertexConfig.php`: ```php namespace Pyz\Zed\Vertex; use SprykerEco\Zed\Vertex\VertexConfig as SprykerEcoVertexConfig; class VertexConfig extends SprykerEcoVertexConfig { public function isTaxIdValidatorEnabled(): bool { return true; } public function isTaxAssistEnabled(): bool { return true; } public function isInvoicingEnabled(): bool { return true; } } ``` ### Config methods The following methods must be overridden in `src/Pyz/Zed/Vertex/VertexConfig.php` to enable the respective features: | Method | Default | Description | |--------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `isTaxIdValidatorEnabled()` | `false` | Enables tax ID validation via [Vertex Validator](https://developer.vertexinc.com/vertex-e-commerce/docs/stand-alone-deployments). Requires `TAXAMO_API_URL` and `TAXAMO_TOKEN` to be set. | | `isTaxAssistEnabled()` | `false` | Enables the tax assist feature. Return Assisted Parameters in the response that will provide more details about the calculation. The logs can be checked in the Vertex Dashboard. | | `isInvoicingEnabled()` | `false` | Enables invoicing functionality. Requires OMS plugins to be registered. See [Register OMS plugins](#register-oms-plugins). | | `getSellerCountryCode()` | `''` | Overrides the default seller country code (2-letter ISO code, for example, `US`). Defaults to the first country of the store. | | `getCustomerCountryCode()` | `''` | Overrides the default customer country code (applied only when no customer billing address is provided). Defaults to the first country of the store. | ## 4. Set up the database schema Install the database schema: ```bash vendor/bin/console propel:install ``` ## 5. Generate transfer objects Generate transfer objects for the module: ```bash vendor/bin/console transfer:generate ``` ## 6. Import glossary data The module provides translation data for tax validation messages. **Option 1: Import using the module's configuration file** ```bash vendor/bin/console data:import --config=vendor/spryker-eco/vertex/data/import/vertex.yml ``` **Option 2: Copy file content and import individually** Copy content from `vendor/spryker-eco/vertex/data/import/*.csv` to the corresponding files in `data/import/common/common/`. Then run: ```bash vendor/bin/console data:import glossary ``` **Option 3: Add to the project's main import configuration** Add the import actions to your project's main data import configuration file and include them in your regular import pipeline. ## 7. Register plugins ### Register the tax calculation plugin Add the Vertex calculation plugin to `src/Pyz/Zed/Calculation/CalculationDependencyProvider.php`: ```php use SprykerEco\Zed\Vertex\Communication\Plugin\Calculation\VertexCalculationPlugin; protected function getQuoteCalculatorPluginStack(Container $container): array { return [ //... # Suggested plugins order is shown. new ItemDiscountAmountFullAggregatorPlugin(), # This plugin is replacing other tax calculation plugins in the stack and will use them as a fallback. # No other tax calculation plugins except for VertexCalculationPlugin should be present in the stack. new VertexCalculationPlugin(), new PriceToPayAggregatorPlugin(), //... ]; } protected function getOrderCalculatorPluginStack(Container $container): array { return [ //... # Suggested plugins order is shown. new ItemDiscountAmountFullAggregatorPlugin(), # This plugin is replacing other tax calculation plugins in the stack and will use them as a fallback. # No other tax calculation plugins except for VertexCalculationPlugin should be present in the stack. new VertexCalculationPlugin(), new PriceToPayAggregatorPlugin(), //... ]; } ``` #### Register Fallback Calculation Plugins Add order and quote Fallback Calculation Plugins to `src/Pyz/Zed/Vertex/VertexDependencyProvider.php`: ```php use Spryker\Zed\Calculation\Communication\Plugin\Calculator\ItemTaxAmountFullAggregatorPlugin; use Spryker\Zed\Calculation\Communication\Plugin\Calculator\PriceToPayAggregatorPlugin; use Spryker\Zed\Tax\Communication\Plugin\Calculator\TaxAmountAfterCancellationCalculatorPlugin; use Spryker\Zed\Tax\Communication\Plugin\Calculator\TaxAmountCalculatorPlugin; use Spryker\Zed\Tax\Communication\Plugin\Calculator\TaxRateAverageAggregatorPlugin; /** * {@inheritDoc} * * @return array<\Spryker\Zed\CalculationExtension\Dependency\Plugin\CalculationPluginInterface> */ protected function getFallbackQuoteCalculationPlugins(): array { return [ # These plugins will be called if Vertex configuration is missing or Vertex is disabled. # Please note that this list includes PriceToPayAggregatorPlugin - this plugin isn't a part of tax calculation logic but it's required by TaxRateAverageAggregatorPlugin. new TaxAmountCalculatorPlugin(), new ItemTaxAmountFullAggregatorPlugin(), new PriceToPayAggregatorPlugin(), new TaxRateAverageAggregatorPlugin(), ]; } /** * {@inheritDoc} * * @return array<\Spryker\Zed\CalculationExtension\Dependency\Plugin\CalculationPluginInterface> */ protected function getFallbackOrderCalculationPlugins(): array { return [ # These plugins will be called if Vertex configuration is missing or Vertex is disabled. # Please note that this list includes PriceToPayAggregatorPlugin - this plugin isn't a part of tax calculation logic but it's required by TaxAmountAfterCancellationCalculatorPlugin. new TaxAmountCalculatorPlugin(), new ItemTaxAmountFullAggregatorPlugin(), new PriceToPayAggregatorPlugin(), new TaxAmountAfterCancellationCalculatorPlugin(), ]; } ``` In general, `getFallbackQuoteCalculationPlugins()` and `getFallbackOrderCalculationPlugins()` methods should contain the tax calculation plugins, which are replaced by `VertexCalculationPlugin` in `\Pyz\Zed\Calculation\CalculationDependencyProvider`. The code snippet above is an example of such configuration based on the Spryker default tax calculation plugins. Tax calculation plugins moved: - from `getQuoteCalculatorPluginStack` method: `TaxAmountCalculatorPlugin`, `ItemTaxAmountFullAggregatorPlugin`, `PriceToPayAggregatorPlugin`, `TaxRateAverageAggregatorPlugin` - from `getOrderCalculatorPluginStack` method: `TaxAmountCalculatorPlugin`, `ItemTaxAmountFullAggregatorPlugin`, `PriceToPayAggregatorPlugin`, `TaxAmountAfterCancellationCalculatorPlugin` {% info_block infoBox "Fallback behavior" %} There are three different failure scenarios where `VertexCalculationPlugin` might need to use a fallback logic: 1. Vertex isn't connected: fallback plugins defined in `getFallbackQuoteCalculationPlugins()` and `getFallbackOrderCalculationPlugins()` will be used to calculate taxes. 2. Vertex is disabled: fallback plugins defined in `getFallbackQuoteCalculationPlugins()` and `getFallbackOrderCalculationPlugins()` will be used to calculate taxes. 3. Vertex is not responding or is responding with an error: tax value will be set to zero, and the customer will be able to proceed with the checkout. {% endinfo_block %} ### Register CalculableObject and order expander plugins Add order and CalculableObject expander plugins to `src/Pyz/Zed/Vertex/VertexDependencyProvider.php`. The proposed plugins are examples, you can select which ones to register based on your requirements or create custom ones if needed. ```php use SprykerEco\Zed\Vertex\Communication\Plugin\Order\OrderCustomerWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Order\OrderExpensesWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Order\OrderItemProductOptionWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Order\OrderItemWithVertexSpecificFieldsExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Quote\CalculableObjectCustomerWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Quote\CalculableObjectExpensesWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Quote\CalculableObjectItemProductOptionWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Quote\CalculableObjectItemWithVertexSpecificFieldsExpanderPlugin; protected function getCalculableObjectVertexExpanderPlugins(): array { return [ // ... other plugins new CalculableObjectCustomerWithVertexCodeExpanderPlugin(), new CalculableObjectExpensesWithVertexCodeExpanderPlugin(), new CalculableObjectItemProductOptionWithVertexCodeExpanderPlugin(), new CalculableObjectItemWithVertexSpecificFieldsExpanderPlugin(), ]; } protected function getOrderVertexExpanderPlugins(): array { return [ // ... other plugins new OrderCustomerWithVertexCodeExpanderPlugin(), new OrderExpensesWithVertexCodeExpanderPlugin(), new OrderItemProductOptionWithVertexCodeExpanderPlugin(), new OrderItemWithVertexSpecificFieldsExpanderPlugin(), ]; } ``` ## 8. Configure the Shop Application dependency provider Add the following code to `src/Pyz/Yves/ShopApplication/ShopApplicationDependencyProvider.php`: ```php namespace Pyz\Yves\ShopApplication; use SprykerShop\Yves\ShopApplication\ShopApplicationDependencyProvider as SprykerShopApplicationDependencyProvider; use SprykerShop\Yves\CartPage\Widget\CartSummaryHideTaxAmountWidget; class ShopApplicationDependencyProvider extends SprykerShopApplicationDependencyProvider { /** * @phpstan-return array> * * @return array */ protected function getGlobalWidgets(): array { return [ //... # This widget is replacing Spryker default tax display in cart summary page with text stating that tax amount will be calculated during checkout process. CartSummaryHideTaxAmountWidget::class, ]; } } ``` If you have custom Yves templates or make your own Frontend, add `CartSummaryHideTaxAmountWidget` to your template. The core template is located at `SprykerShop/Yves/CartPage/Theme/default/components/molecules/cart-summary/cart-summary.twig`. Here is an example with `CartSummaryHideTaxAmountWidget`: ```html {% raw %}

{{ 'cart.total.tax_total' | trans }} {% widget 'CartSummaryHideTaxAmountWidget' args [data.cart] only %} {% nowidget %} {{ data.cart.totals.taxTotal.amount | money(true, data.cart.currency.code) }} {% endwidget %}

{% endraw %} ``` ## 9. Optional: Sending tax invoices to Vertex and handling refunds Configure payment `config/Zed/oms/{your_payment_oms}.xml`as in the following example: ```xml paid tax invoice submitted submit tax invoice tax invoice submitted ``` ### Register OMS plugins {% info_block infoBox "Optional" %} This step is required only if you want to use invoicing functionality. Make sure `isInvoicingEnabled()` is set to `true` in `VertexConfig.php`. {% endinfo_block %} Add OMS plugins to `src/Pyz/Zed/Oms/OmsDependencyProvider.php`: ```php use SprykerEco\Zed\Vertex\Communication\Plugin\Oms\Command\VertexSubmitPaymentTaxInvoicePlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Oms\VertexOrderRefundedEventListenerPlugin; # This configuration is necessary for Invoice functionality protected function extendCommandPlugins(Container $container): Container { $container->extend(self::COMMAND_PLUGINS, function (CommandCollectionInterface $commandCollection) { // ... other command plugins $commandCollection->add(new VertexSubmitPaymentTaxInvoicePlugin(), 'Vertex/SubmitPaymentTaxInvoice'); return $commandCollection; }); return $container; } # This configuration is necessary for Refund functionality protected function getOmsEventTriggeredListenerPlugins(Container $container): array { return [ // ... other plugins new VertexOrderRefundedEventListenerPlugin(), ]; } ``` This configuration of `getOmsEventTriggeredListenerPlugins` method is required to ensure that the correct tax amount will be used during the refund process. {% info_block infoBox "OMS configuration requirement" %} The refund functionality will only work if the OMS event is called `refund`. {% endinfo_block %} ## Next steps - [Configure Vertex-specific metadata](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/configure-vertex-specific-metadata.html) - [Migrate from the ACP Vertex app](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/migrate-from-acp-to-vertex.html)

Enable Dynamic Multistore

Mon, 20 Apr 2026 14:20:29 +0000

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

Prerequisites

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

Enable Dynamic Multistore

Staging environment

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

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

Back Office
Merchant Portal
Console Commands
Gateway
BackendAPI

Update custom console commands to meet the following rules:

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

After enabling DMS, the basic domain structure must change from store to region for all the applications. For example, https://yves.de.mysprykershop.com will change to https://yves.eu.mysprykershop.com. To prevent negative SEO effects, set up the needed redirects. If your target domain doesn’t change, for example it doesn’t contain a region name - yves.mysprykershop.com - you may skip this step.
DMS changes the structure of RabbitMQ messages. When you’re ready for the migration, wait for all the remaining messages in the queue to be processed. When the queue is empty, enable the maintenance mode. The downtime associated with the maintenance mode is limited to the deployment time, which usually takes up to an hour.
Update AWS deployment files to DMS mode using the example:

Original environment variables section:

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

Updated environment variables section:

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

Original regions section:

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

Updated regions section:

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

Run a normal deploy for your server pipeline.

Verification

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

Your shop is now running in DMS mode.

Check if Dynamic Multistore is enabled

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

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

Disable Dynamic Multistore

Staging environment

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

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

Original environment variables section:

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

Updated environment variables section:

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

Original regions section:

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

Updated regions section:

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

Run a normal deploy for your server pipeline.

Verification

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

Install and configure Stripe prerequisites for Marketplace

Mon, 20 Apr 2026 12:40:12 +0000

This document covers marketplace-specific additions to the base shop Stripe integration. Before following the steps below, complete [Integrate Stripe](/docs/pbc/all/payment-service-provider/latest/base-shop/third-party-integrations/stripe/install-and-configure-stripe-prerequisites.html), making sure to apply all steps marked as **marketplace only**. {% info_block infoBox "OMS process" %} In Step 3 of the base shop guide, use `StripeManualMarketplace01` instead of `StripeManual01`. {% endinfo_block %} ## Add Merchant Portal navigation Update `config/Zed/navigation-main-merchant-portal.xml` to add the Payment Settings entry for merchants: ```xml ... Payment Settings Payment Settings payment merchant-app-merchant-portal-gui payment-settings index Onboarding Onboarding payment merchant-app-merchant-portal-gui payment-settings onboarding 0 ``` ## Register ACL plugins Add the following plugins to the listed methods: | PLUGIN | METHOD | |--------|--------| | `\Spryker\Zed\MerchantAppMerchantPortalGui\Communication\Plugin\AclMerchantPortal\MerchantAppMerchantPortalGuiMerchantAclRuleExpanderPlugin` | `\Pyz\Zed\AclMerchantPortal\AclMerchantPortalDependencyProvider::getMerchantAclRuleExpanderPlugins()` | | `\Spryker\Zed\MerchantAppMerchantPortalGui\Communication\Plugin\AclMerchantPortal\MerchantAppAclEntityConfigurationExpanderPlugin` | `\Pyz\Zed\AclMerchantPortal\AclMerchantPortalDependencyProvider::getAclEntityConfigurationExpanderPlugins()` | | `\Spryker\Zed\Payment\Communication\Plugin\AclMerchantPortal\PaymentAclEntityConfigurationExpanderPlugin` | `\Pyz\Zed\AclMerchantPortal\AclMerchantPortalDependencyProvider::getAclEntityConfigurationExpanderPlugins()` | | `\Spryker\Zed\SalesPaymentMerchant\Communication\Plugin\AclMerchantPortal\SalesPaymentMerchantAclEntityConfigurationExpanderPlugin` | `\Pyz\Zed\AclMerchantPortal\AclMerchantPortalDependencyProvider::getAclEntityConfigurationExpanderPlugins()` | ## Configure ACL installer rules Add `merchant-app-merchant-portal-gui` to the Merchant Portal ACL deny rules:

\Pyz\Zed\Acl\AclConfig::addMerchantPortalInstallerRules()

```php > */ public function getInstallerRules(): array { $installerRules = $this->addMerchantPortalInstallerRules($installerRules); return $installerRules; } /** * @param array> $installerRules * * @return array> */ protected function addMerchantPortalInstallerRules(array $installerRules): array { $bundleNames = [ 'merchant-app-merchant-portal-gui', ]; foreach ($bundleNames as $bundleName) { $installerRules[] = [ 'bundle' => $bundleName, 'controller' => AclConstants::VALIDATOR_WILDCARD, 'action' => AclConstants::VALIDATOR_WILDCARD, 'type' => static::RULE_TYPE_DENY, 'role' => AclConstants::ROOT_ROLE, ]; } return $installerRules; } } ```

## Enable redirect from third-party websites To enable merchants to be redirected to the Merchant Portal from third-party websites, add `redirect.php` to the public folder of your Merchant Portal: [/public/MerchantPortal/redirect.php](https://github.com/spryker-shop/b2c-demo-marketplace/blob/master/public/MerchantPortal/redirect.php). ## Enable merchant commissions To enable merchant commissions for payout calculation, [install the Marketplace Merchant Commission feature](/docs/pbc/all/merchant-management/latest/marketplace/install-and-upgrade/install-features/install-the-marketplace-merchant-commission-feature.html). ## Next step [Configure merchant transfers for Stripe](/docs/pbc/all/payment-service-provider/latest/marketplace/stripe-third-party-integration/configure-merchant-transfers-for-stripe.html)

AI Dev SDK

Mon, 20 Apr 2026 06:17:01 +0000

Warning

Before you use AI-related tools, consult your legal department.

Overview

When you use AI tools to write code, they rely on general patterns, which leads to mistakes and requires you to repeatedly explain your project structure.

The AI Dev SDK provides an MCP server, which is a console command that your AI tool runs in your project’s Docker container and helps it to increase Spryker-context awareness. MCP (Model Context Protocol) is a standard protocol that lets AI tools request specific information from external sources, similar to how a browser requests data from an API.

How it works

After you install the SDK, add a simple configuration to your AI tool. When your Spryker project is running, your AI tool can access Spryker-specific information and prompts through the MCP server.

Result

AI generates better code faster and with fewer errors. You spend less time correcting mistakes and explaining Spryker concepts.

Key capabilities

Faster Spryker-specific answers

AI can search Spryker documentation instead of requiring you to explain basic concepts or guessing how features work.

Smarter code generation

AI can look up your actual transfer objects, module dependencies, and interface methods so that the generated code matches your project structure instead of relying on assumptions.

OMS debugging made easy

AI can analyze your OMS flows to find possible next states, transitions, conditions, and timeouts for any order or state. This capability is especially helpful when you work with complex OMS schemas. You no longer need to manually follow arrows in large diagrams.

Working with complex data imports

AI can analyze, modify, and transform multi-column CSV files correctly. This task normally requires significant manual effort.

The SDK includes access to the Spryker prompt library, and you can add your own project-specific prompts. This means your team can reuse effective prompts instead of everyone writing their own.

Database queries

AI can execute read-only database queries to inspect data when debugging issues.

Extensible for your project

You can extend the MCP server by creating custom plugins (to add new tools) and custom prompts.

Install the AI Dev SDK

Prerequisites

Ensure that you have a Spryker project with Composer installed.

Installation steps

Require the package as a development dependency:
```
composer require spryker-sdk/ai-dev --dev
```
Generate the transfer objects:
```
console transfer:generate
```

use SprykerSdk\Zed\AiDev\Communication\Console\GenerateAgentsFileConsole;
use SprykerSdk\Zed\AiDev\Communication\Console\GeneratePromptsConsole;
use SprykerSdk\Zed\AiDev\Communication\Console\GenerateSkillsConsole;
use SprykerSdk\Zed\AiDev\Communication\Console\McpServerConsole;

protected function getConsoleCommands(Container $container): array
{
    ...
    if (class_exists(McpServerConsole::class)) {
        $commands[] = new McpServerConsole();
    }

    if (class_exists(GenerateAgentsFileConsole::class)) {
        $commands[] = new GenerateAgentsFileConsole();
    }

    if (class_exists(GenerateSkillsConsole::class)) {
        $commands[] = new GenerateSkillsConsole();
    }

    if (class_exists(GeneratePromptsConsole::class)) {
        $commands[] = new GeneratePromptsConsole();
    }
    ...
}

Connect the AI Dev SDK to your AI agent. For detailed configuration instructions, see Configure the AiDev MCP server.

Next steps

Configure the AiDev MCP server - Set up the connection to your AI tool
AI Dev SDK Overview - Learn more about the AI Dev SDK features and capabilities

AI Dev SDK Overview

Mon, 20 Apr 2026 06:17:01 +0000

Experimental module

The AiDev module is experimental and not stable. There is no backward compatibility promise for this module. We welcome your feedback and contributions as we continue to develop and improve this module.

Prerequisites

This module requires ^1.71.0 version of docker/sdk for proper usage. Make sure your development environment is up to date before installing the AiDev module.

This document describes how to integrate and use the AiDev module to connect your Spryker application to AI development tools through the Model Context Protocol (MCP).

Overview

The AiDev module provides an MCP server that enables AI assistants to interact with your Spryker application. It exposes Spryker-specific information through MCP tools and prompts, allowing AI assistants to better understand and work with your codebase.

The module includes:

MCP Server: A console command that runs an MCP server to communicate with AI assistants
Extension Points: Plugin interfaces for adding custom MCP tools and prompts
Built-in Tools: Pre-configured tools for accessing Spryker transfers, interfaces, and OMS information
Prompt Generation: Automatic generation of context-aware prompts from documentation

Console commands

The AiDev module provides the following console commands:

MCP Server Command

The ai-dev:mcp-server command starts an MCP server that allows AI assistants to interact with your Spryker application.

docker/sdk console ai-dev:mcp-server -q

This command:

Starts an MCP server using stdio transport
Registers all configured MCP tool and prompt plugins
Automatically generates prompts if they don’t exist
Listens for requests from AI assistants

Usage: This command is typically configured in AI assistant tools (like Claude Desktop) to enable them to access Spryker-specific information.

Generate Agents File Command

The ai-dev:generate-agents-file command generates an example AI context file (AGENTS.md or CLAUDE.md) for your Spryker project. This file provides AI agents with project-specific context, architectural rules, and coding conventions.

docker/sdk console ai-dev:generate-agents-file

When you run the command, you are prompted to select the output format:

Format	Supported tools
`AGENTS.md`	Universal format. Supported by Codex, OpenCode, Cursor, GitHub Copilot, Windsurf, VS Code, and more.
`CLAUDE.md`	Claude Code CLI (Anthropic).

The command generates a <format>.example.md file in your project root. Rename it to AGENTS.md or CLAUDE.md when ready to use.

Usage: Run this command once when setting up AI tooling for a project to give your AI agent Spryker-specific context.

Generate Skills Command

The ai-dev:generate-skills command generates example AI coding skill files for Spryker project development.

docker/sdk console ai-dev:generate-skills

When you run the command, you are prompted to select the target AI tool. The command copies example skills into the tool-specific directory:

AI tool	Output directory
Claude Code	`.claude/skills/`
Windsurf	`.windsurf/skills/`
GitHub Copilot	`.github/skills/`
Cursor, OpenAI Codex, OpenCode, Agents Convention	`.agents/skills/`

Each skill is generated with a -example suffix in the directory name. Rename the directories by removing the -example suffix when ready to use.

Usage: Run this command to scaffold reusable AI skills for common Spryker development tasks such as functional testing, data import, Propel schema changes, and frontend development.

Generate Prompts Command

The ai-dev:generate-prompts command generates MCP prompts from a configured Prompt Library.

docker/sdk console ai-dev:generate-prompts

This command:

Fetches prompts
Generates PHP-based prompt classes
Stores generated prompts in the configured directory

Usage: Use this command when you need to regenerate prompts from updated documentation or when initializing the module for the first time.

Extension points

The AiDev module provides plugin interfaces for extending the MCP server with custom functionality:

AiDevMcpToolPluginInterface

Implement this interface to add custom MCP tools that AI assistants can use to query or interact with your application.

Interface location: SprykerSdk\Zed\AiDev\Dependency\AiDevMcpToolPluginInterface

Integration: Register your tool plugins in AiDevDependencyProvider::getMcpToolPlugins():

<?php

namespace Pyz\Zed\AiDev;

use SprykerSdk\Zed\AiDev\AiDevDependencyProvider as SprykerAiDevDependencyProvider;
use Pyz\Zed\AiDev\Communication\Plugins\CustomAiDevMcpToolPlugin;

class AiDevDependencyProvider extends SprykerAiDevDependencyProvider
{
    /**
     * @return array<\SprykerSdk\Zed\AiDev\Dependency\AiDevMcpToolPluginInterface>
     */
    protected function getMcpToolPlugins(): array
    {
        return array_merge(parent::getMcpToolPlugins(), [
            new CustomAiDevMcpToolPlugin(),
        ]);
    }
}

AiDevMcpPromptPluginInterface

Implement this interface to add custom MCP prompts that provide context or instructions to AI assistants.

Interface location: SprykerSdk\Zed\AiDev\Dependency\AiDevMcpPromptPluginInterface

Integration: Register your prompt plugins in AiDevDependencyProvider::getMcpPromptPlugins():

<?php

namespace Pyz\Zed\AiDev;

use SprykerSdk\Zed\AiDev\AiDevDependencyProvider as SprykerAiDevDependencyProvider;
use Pyz\Zed\AiDev\Communication\Plugins\CustomAiDevMcpPromptPlugin;

class AiDevDependencyProvider extends SprykerAiDevDependencyProvider
{
    /**
     * @return array<\SprykerSdk\Zed\AiDev\Dependency\AiDevMcpPromptPluginInterface>
     */
    protected function getMcpPromptPlugins(): array
    {
        return [
            new CustomAiDevMcpPromptPlugin(),
        ];
    }
}

Configuration

The AiDev module can be configured through the AiDevConfig class. Key configuration options include:

Prompt Directory: Set the directory where generated prompts are stored

Refer to the module’s configuration class for available options and their default values.

Debugging the MCP server

Before connecting your MCP server to AI assistants, you can test and debug it using the MCP Inspector tool. The inspector provides a web interface to interact with your MCP server, test tools, and verify that everything works correctly.

Using the MCP Inspector

Navigate to your Spryker project directory and run:

npx @modelcontextprotocol/inspector docker/sdk console ai-dev:mcp-server -q

This command will:

Start the MCP Inspector in your browser
Connect to your local MCP server
Display all available tools and prompts
Allow you to test tool calls interactively

With Xdebug

npx @modelcontextprotocol/inspector docker/sdk cli -x console ai-dev:mcp-server

Node.js required

The MCP Inspector requires Node.js to be installed on your system. The npx command will automatically download and run the inspector tool without requiring a global installation.

Install the Purchasing Control feature

Fri, 17 Apr 2026 14:22:26 +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:"^0.1.0" spryker-shop/checkout-page:"^3.40.0" --update-with-dependencies ``` ### 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 | | CostCenterResponse | class | created | src/Generated/Shared/Transfer/CostCenterResponseTransfer.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 | | BudgetResponse | class | created | src/Generated/Shared/Transfer/BudgetResponseTransfer.php | | BudgetConsumption | class | created | src/Generated/Shared/Transfer/BudgetConsumptionTransfer.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 | {% endinfo_block %} ### 3) Set up behavior Enable the following behaviors by registering the plugins. #### Set up Zed plugins | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | 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 | | RestoreBudgetOmsCommandPlugin | Deletes all budget consumption records for a sales order when the order is cancelled, restoring the consumed budget amount. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Oms | **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 %} **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 %} **src/Pyz/Zed/Oms/OmsDependencyProvider.php** ```php extend(self::COMMAND_PLUGINS, function (CommandCollectionInterface $commandCollection) { // ... $commandCollection->add(new RestoreBudgetOmsCommandPlugin(), 'CostCenter/RestoreBudget'); #PurchasingControlFeature return $commandCollection; }); return $container; } } ``` {% info_block warningBox "Verification" %} When an order transitions to a cancelled state and the `CostCenter/RestoreBudget` OMS command runs, make sure the corresponding `spy_budget_consumption` records are deleted and the budget balance is restored. {% endinfo_block %} ### 4) Configure Back Office navigation Add the Purchasing Control section to the Back Office navigation: **config/Zed/navigation.xml** ```xml ... ... Purchasing Control Purchasing Control 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 **Purchasing Control** menu item is displayed and links to the cost center list page. {% endinfo_block %} ### 5) Configure the OMS process Add the `CostCenter/RestoreBudget` command to the `cancel` event in your OMS process XML. The following example uses `DummyPayment01`: **config/Zed/oms/DummyPayment01.xml** ```xml ... ... ``` {% info_block warningBox "Verification" %} In the Back Office, open a placed order and trigger the **cancel** event. Make sure the `spy_budget_consumption` records for the order are deleted and the budget balance is restored. {% endinfo_block %} ## Install feature frontend Follow the steps below to install the Purchasing Control feature frontend. ### 1) Import data Import the following glossary keys for Storefront translations: **data/import/common/common/glossary.csv** ```csv purchasing_control.selector.placeholder,Select cost center,en_US purchasing_control.selector.placeholder,Kostenstelle wählen,de_DE purchasing_control.budget.selector.label,Budget,en_US purchasing_control.budget.selector.label,Budget,de_DE purchasing_control.budget.selector.placeholder,Select budget,en_US purchasing_control.budget.selector.placeholder,Budget wählen,de_DE purchasing_control.budget.remaining,Remaining budget,en_US purchasing_control.budget.remaining,Verbleibendes Budget,de_DE purchasing_control.summary.cost_center_label,Cost Center,en_US purchasing_control.summary.cost_center_label,Kostenstelle,de_DE purchasing_control.summary.budget_label,Budget,en_US purchasing_control.summary.budget_label,Budget,de_DE purchasing_control.summary.budget_remaining,remaining,en_US purchasing_control.summary.budget_remaining,verbleibend,de_DE purchasing_control.validation.block,"Your order exceeds the allocated budget. Please adjust your order or contact your manager.",en_US purchasing_control.validation.block,"Ihre Bestellung überschreitet das zugewiesene Budget. Bitte passen Sie Ihre Bestellung an oder kontaktieren Sie Ihren Manager.",de_DE purchasing_control.validation.warn,Your order exceeds the allocated budget.,en_US purchasing_control.validation.warn,Ihre Bestellung überschreitet das zugewiesene Budget.,de_DE purchasing_control.validation.require-approval,This order exceeds the budget. Please send it for approval.,en_US purchasing_control.validation.require-approval,Diese Bestellung überschreitet das Budget. Bitte senden Sie sie zur Genehmigung.,de_DE purchasing_control.validation.required,"Please select a cost center and budget before placing your order.",en_US purchasing_control.validation.required,"Bitte wählen Sie vor der Bestellung eine Kostenstelle und ein Budget aus.",de_DE ``` 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 %} ### 2) Set up widgets Register the following global widgets: | WIDGET | DESCRIPTION | NAMESPACE | | --- | --- | --- | | CostCenterSelectorWidget | Renders the cost center and budget selection UI in the cart or checkout. | SprykerFeature\Yves\PurchasingControl\Widget | **src/Pyz/Yves/ShopApplication/ShopApplicationDependencyProvider.php** ```php */ protected function getGlobalWidgets(): array { return [ // ... CostCenterSelectorWidget::class, #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} Make sure the `CostCenterSelectorWidget` widget is available in Twig templates. {% endinfo_block %} ### 3) 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 %} ### 4) Set up routes Register the following route provider plugin: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | CostCenterRouteProviderPlugin | Adds the `POST /cost-center/update-quote` route, which handles cost center and budget selection form submissions from the cart or checkout. | None | SprykerFeature\Yves\PurchasingControl\Plugin\Router | **src/Pyz/Yves/Router/RouterDependencyProvider.php** ```php */ protected function getRouteProvider(): array { return [ // ... new CostCenterRouteProviderPlugin(), #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} Make sure the route `cost-center-update-quote` is accessible and that submitting the cost center selector form in the cart updates the quote with the selected cost center and budget. {% endinfo_block %}

Purchasing Control feature overview

Fri, 17 Apr 2026 14:20:09 +0000

The *Purchasing Control* feature lets B2B companies track and control procurement spending by assigning orders to cost centers and enforcing configurable budget rules. It extends the existing [Approval Process](/docs/pbc/all/cart-and-checkout/latest/base-shop/feature-overviews/approval-process-feature-overview.html) with a second dimension of spending governance: per-department or per-project budget limits that work alongside the existing per-person permission limits. {% info_block infoBox "Info" %} This feature is available in the Back Office and on the Storefront. {% endinfo_block %} ## Cost centers A *cost center* is an organizational unit within a company that incurs costs but does not directly generate revenue. Companies use cost centers to track and control spending by department, project, location, or function. **Common examples:** - **Departmental:** Marketing, Engineering, HR, Facilities - **Project-based:** Office Renovation Q2 2026, Trade Show Berlin - **Location-based:** Warehouse Berlin, Office London Every purchase a buyer makes is charged to a cost center so the company can track where money is being spent. In ERP systems such as SAP, Oracle, and Microsoft Dynamics, cost centers are a foundational accounting concept - orders flow into the ERP tagged with a cost center code, enabling financial reporting and cost allocation. ## Budgets A *budget* is a spending limit assigned to a cost center for a defined period - monthly, quarterly, or annually. It represents the maximum amount that a department or project is authorized to spend in that period. **Example:** The Marketing department has a quarterly procurement budget of €50,000 for office supplies and event materials. Once that budget is consumed, further purchases are either blocked, flagged for review, or escalated for approval. ### Budget enforcement rules Each budget is configured with one of three enforcement rules: | RULE | DESCRIPTION | | --- | --- | | Block | The order is rejected outright when the budget is exceeded. The buyer cannot proceed to checkout. | | Warn | A warning is displayed to the buyer, but they can proceed. | | Require Approval | The order is sent for approval when the budget is exceeded. The buyer cannot complete checkout until an approver accepts the order. | ## Relationship to the Approval Process Spryker's existing Approval Process triggers a workflow when a buyer's order exceeds their *Buy up to grand total* permission. The Purchasing Control feature adds a parallel check: an order might be within a buyer's personal permission limit but still exceed the cost center's remaining budget. Both checks run independently at checkout. If either the permission limit or the budget rule is triggered, the configured action - block, warn, or require approval - is applied. This gives companies layered spending governance: per-person limits *and* per-department or per-project limits. {% info_block warningBox "Approvals within a business unit" %} Approvers can only approve orders of employees within their own business unit. This constraint applies to both permission-based and budget-based approval requests. {% endinfo_block %} ## Cost centers and budgets in the procurement workflow The typical B2B procurement flow involving cost centers and budgets: 1. **Finance sets budgets.** At the start of a fiscal period, finance allocates budgets to each cost center. 2. **Buyers are assigned to cost centers.** Buyers are linked to one or more cost centers they are authorized to purchase against. Cost centers are linked to company business units, so all users in a business unit are automatically assigned to the corresponding cost centers. 3. **Orders are tagged.** At checkout, the buyer selects which cost center the purchase is charged to. The system automatically selects the active budget for that cost center: - If exactly one active budget is available - it is selected automatically. - If multiple budgets are available - the buyer selects from a dropdown. 4. **Budget is validated.** The system checks whether the order total fits within the remaining budget for the selected cost center. 5. **Enforcement rules apply.** Based on the configured rule, the order is blocked, a warning is shown, or approval is required. 6. **Budget is consumed.** Once the order is confirmed, the budget balance is reduced by the order amount. 7. **Budget is restored.** If the order is cancelled, the consumed amount is returned to the budget balance. ## Checkout validation outcomes | SCENARIO | OUTCOME | | --- | --- | | Within budget and within permission limit | Buyer completes checkout without additional steps. | | Exceeds budget - Warn rule | A warning is displayed; the buyer proceeds but the order requires approval. | | Exceeds budget - Require Approval rule | The order is sent for approval; the buyer cannot complete checkout until approved. | | Exceeds Buy up to grand total permission limit | The order is sent for approval, same as the standard Approval Process. | | Exceeds budget - Block rule | Checkout is blocked; no approval option is available. | ## Quote lock When an order is sent for approval - whether triggered by a budget rule or a permission limit - the quote is locked to preserve the order state during the approval review. Neither the buyer nor the approver can modify the quote while it is pending approval. For details, see [Quote lock functionality](/docs/pbc/all/cart-and-checkout/latest/base-shop/feature-overviews/approval-process-feature-overview.html#quote-lock-functionality). ## Roles and capabilities | ROLE | CAPABILITIES | | --- | --- | | Company Admin (Back Office) | Create, update, activate, and deactivate cost centers. Assign cost centers to business units. Create and manage budgets with amount, period, currency, and enforcement rule. View spend-vs-budget reports. Export reports to CSV. Review the audit log. | | Buyer (Storefront) | Select a cost center and budget at checkout. View remaining budget for the selected cost center. Submit orders for approval when required. | | Approver (Storefront) | Review locked quotes pending approval. Approve or reject orders, including those triggered by budget rules. | ## Related Developer documents | INSTALLATION GUIDES | | --- | | [Install the Purchasing Control feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-purchasing-control-feature.html) |

Stripe

Thu, 16 Apr 2026 13:59:55 +0000

[Stripe](https://stripe.com/en-de) is a financial infrastructure platform that enables businesses to accept payments, grow their revenue, and accelerate new business opportunities. The Stripe integration in Spryker is part of [Spryker ecosystem](/docs/integrations/eco-modules) and supports both the default Storefront Yves and Spryker GLUE APIs. ## Supported business models The Stripe module supports B2B, B2C, and Marketplace models. ## Stripe features - Interface within the Back Office to configure API keys. - Support of test (sandbox) or live credentials. - Storefront Payment Page: when the Stripe payment method is configured, after order submission end users are presented with the Stripe Elements payment form where they can select and complete their payment. This works both on the web and mobile. - Viewing the activated payment methods in the Stripe dashboard. - GLUE API support: Support for customers using Spryker headless. - Authorize payments and capture later: The default OMS configuration lets you authorize cards and capture the order amount either after shipping or based on the established business logic. - Default OMS Configuration: We provide default OMS configurations (for regular ecommerce sites and marketplaces) that you can use as an example or modify to align with your business logic. ## Stripe payment methods The Stripe module supports all payments enabled by Stripe in your region. For more information, see [Payment methods in Stripe](https://stripe.com/docs/payments/payment-methods/overview). However, our team only tested the following payment methods: - Cards: including Visa and Mastercard - Debit card - Bank transfer: supported in some regions, see [Bank transfer payments](https://stripe.com/docs/payments/bank-transfers) - PayPal - Klarna - Apple Pay - Google Pay - Direct Debit (SEPA) / Sofortüberweisung - iDEAL - Link - Przelewy24 - Giropay - US, UK, CA, AU, NZ: AfterPay ## Current limitations - Partial capture of payment for orders with multiple items isn't covered (Stripe allows only one capture per PaymentIntent). One payment intent is created per order, and the payment for the order can either be authorized, captured, or cancelled from Stripe's side. - Payments can't be partially canceled. - Items canceled after capture are handled via refunds. ## Browser back button handling Using the browser back button at the Stripe payment form may lead to issues with order persistence and stock management. For instructions on configuring your application to handle this scenario and prevent duplicate orders, see [Configure handling of browser back button action at payment page](/docs/pbc/all/payment-service-provider/latest/base-shop/configure-handling-of-browser-back-button-action-at-hosted-payment-page.html). ## Next step [Integrate Stripe](/docs/pbc/all/payment-service-provider/latest/base-shop/third-party-integrations/stripe/install-and-configure-stripe-prerequisites.html)

Stripe OMS configuration for marketplaces

Thu, 16 Apr 2026 13:59:55 +0000

This document provides guidelines for projects using Stripe in marketplaces. ## OMS configuration The complete default payment OMS configuration for marketplaces is available in `vendor/spryker-eco/stripe/config/Zed/oms/StripeManualMarketplace01.xml`. The payment flow of the default OMS involves authorizing the initial payment, which means that the amount is temporarily blocked when the payment method permits. Then, the OMS sends requests to capture, that is, transfer of the previously blocked amount from the customer's account to the store account. For more information about the base shop OMS configuration, see [OMS configuration for Stripe](/docs/pbc/all/payment-service-provider/latest/base-shop/third-party-integrations/stripe/project-guidelines-for-stripe/oms-configuration-for-stripe.html). In addition to the base shop implementation, the Stripe module in Marketplaces requires the following OMS configuration: - The `MerchantCommission/Calculate` command triggers the calculation of the commission for the merchant. By default, this command is initiated when an order is moved to the `payment captured` state. This command calculates the commission based on your projects settings. For more details on configuration, see [Marketplace Merchant Commission feature overview](/docs/pbc/all/merchant-management/latest/marketplace/marketplace-merchant-commission-feature-overview.html). - The `SalesPaymentMerchant/Payout` command initiates the payout to merchant action. By default, this command is initiated after the OMS is in the `delivered` state and the commission was calculated. - The `SalesPaymentMerchant/ReversePayout` command initiates the reversal of the payout to the merchant action. By default, this command is initiated after the OMS is in the `payment refunded` state. - The validation of the payout status is done by the `SalesPaymentMerchant/IsMerchantPaidOut` condition. By default, this condition is triggered after a payout is done. When a payout is successful, the OMS moves to the `closed` state. If a payout fails, the OMS moves to the `payout failed` state. - The `SalesPaymentMerchant/IsMerchantPayoutReversed` condition validates the reverse payout status. By default, this condition is triggered after the reverse payout is done. When a reverse payout is successful, the OMS moves to the `canceled` state. If a reverse payout fails, the OMS moves to the `reverse payout failed` state. You can change and configure your own payment OMS based on `StripeManualMarketplace01.xml` from the Stripe eco package. For more information about the OMS feature and its configuration, see [Install the Order Management feature](/docs/pbc/all/order-management-system/latest/base-shop/install-and-upgrade/install-features/install-the-order-management-feature.html). To configure your payment OMS based on `StripeManualMarketplace01.xml`, copy `StripeManualMarketplace01.xml` with the `Subprocess` folder to the project root `config/Zed/oms`. Then, change the file's name and the value of `

Payout subprocess example

```xml merchant payout ready closed payout merchant merchant payout ready payout failed payout merchant payout failed merchant payout ready retry payout merchant ```

Reverse Payout subprocess

```xml merchant payout reverse ready canceled reverse payout merchant payout reverse ready reverse payout failed reverse payout reverse payout failed merchant payout reverse ready retry reverse payout ```

## Processing payouts In the default OMS configuration, a payout to merchants is initiated after the OMS is in `delivered` state and the commission was calculated. This command sends a direct API call to Stripe to initiate the payout to the merchant. The payout status is tracked in the Back Office, and the OMS can either move to `payout failed` or `closed` state. The `payout failed` state is used to track the payout status and inform the Back Office user about the failure. The `closed` state is used to track the successful payout. ### Payout process 1. A customer pays for an order. 2. The money is transferred from the customer's account, like a bank account, to the marketplace Stripe account. - The marketplace calculates the commission for the merchant. - The marketplace initiates a payout to the merchant. - The money is transferred from the marketplace Stripe account to the merchant's Stripe account. ### When a payout fails A payout can fail for many reasons. Examples: - The merchant's account isn't verified - The merchant's account isn't connected to the marketplace Stripe account - The merchant's account isn't active You can identify the cause of a failure in the Stripe Dashboard. After resolving the issue, the payout can be reinitiated. ## Processing refunds as reverse payout In the default OMS configuration, a reverse payout can be done for an order or an individual item. The reverse payout action is initiated by a Back Office user triggering the `SalesPaymentMerchant/ReversePayout` command. The selected item or items are used to find the previously made payout in the database and the amount that was paid out to the merchant and make a direct API call to Stripe which does the reverse payout. Based on the response the items go either into `canceled` or `reverse payout failed` state. ### Reverse Payout process 1. A customer returns an item. 2. The money is transferred from the marketplace Stripe account to the customers account, like a bank account. 3. The marketplace initiates a reverse payout from a merchant. 4. The money is transferred from the merchant's Stripe account to the marketplace Stripe account. ### Reverse payout failures A reverse payout can fail for many reasons, for example — the merchant's Stripe account doesn't have the funds to cover a reverse payout. You can identify the cause of a failure in the Stripe Dashboard. After resolving the issue, the reverse payout can be reinitiated again.

Spryker Documentation

Enable and disable maintenance mode

Prerequisites

Per-store and per-region maintenance pages

Enable maintenance mode

Disable maintenance mode

Integrate Vertex

Enable Dynamic Multistore

Prerequisites

Enable Dynamic Multistore

Check if Dynamic Multistore is enabled

Disable Dynamic Multistore

Install and configure Stripe prerequisites for Marketplace

AI Dev SDK

Overview

How it works

Result

Key capabilities

Faster Spryker-specific answers

Smarter code generation

OMS debugging made easy

Working with complex data imports

Sharing prompts across your team

Database queries

Extensible for your project

Install the AI Dev SDK

Prerequisites

Installation steps

Next steps

AI Dev SDK Overview

Overview

Console commands

MCP Server Command

Generate Agents File Command

Generate Skills Command

Generate Prompts Command

Extension points

AiDevMcpToolPluginInterface

AiDevMcpPromptPluginInterface

Configuration

Debugging the MCP server

Using the MCP Inspector

Install the Purchasing Control feature

Purchasing Control feature overview

Stripe

Stripe OMS configuration for marketplaces