Spryker Documentation

Upgrade the OMS module

Mon, 30 Mar 2026 10:24:17 +0000

{% include pbc/all/upgrade-modules/upgrade-the-oms-module.md %}

Data import optimization guidelines

Mon, 30 Mar 2026 08:28:02 +0000

This article will define the best practices for Spryker modules that need to work with two infrastructure concepts like DataImport and Publish & Synchronize. After several reviews and tests, we found that we need to define these rules to help developers to write more scalable and high-performance code when they implementing their features. Most of the time when developers create features, they don’t consider very high traffic or heavy data processing for big data. This article is going to describe all necessary requirements when you want to create new features and they should work with big data, for example, you want to create a new DataImport or a new P&S module which save millions of entities into a database in a very short amount of time.

Rules for data importers

DataImport module is responsible for reading data from different formats like CSV, JSON, etc and import them into a database with proper Spryker data structure. Usually importing of data is a time-consuming process and we need to follow some best practices to increase the performance. Here you will find some of them:

Progress bar

The --progress-bar flag lets you monitor data import in real time using the Symfony Console Progress Bar component. While the import runs, the progress bar displays the current memory usage and processing speed, so you can identify bottlenecks without adding custom logging.

Prerequisites

Update the spryker/data-import package to version 1.32.0 or later:

composer update spryker/data-import:"^1.32.0"

Usage

Add the --progress-bar flag to any data import command:

console data:import combined-product-abstract --progress-bar

Performance note

The --progress-bar flag enables debug mode, which adds overhead to the import process. Use it for diagnostics and testing, not for production data imports.

Single vs batch operation

Assuming you are writing a data importer for ProductAbstract, you might want to find a category for each product abstract, your very basic code would be something like this:

protected function importProductAbstract(DataSetInterface $dataSet): void
{
    $categoryKey = $dataSet['category_key'];
    $productCategory = SpyCategoryQuery::create()->findOneByCategoryKey($categoryKey);
    $dataSet['product_category'] = $productCategory;

    $this->importProductCategories($dataSet);
}

This will work fine and you already achieved to your goals, but can you see the problem here?

Here is the problem:

protected function importProductAbstract(DataSetInterface $dataSet): void
{
    ...
    $productCategory = SpyCategoryQuery::create()->findOneByCategoryKey($categoryKey); // expensive call
 ...
}

importProductAbstract method will call for each line of your CSV, imagine if you have one CSV file with 1,000,000 lines, it means you will run this query again and again for 1 million times! The possible solution is to avoid single processing and implementing a batch query for it.

The current solution for DataImport is to add another step before the main step to gather all the information you need for the next steps. like querying all categories and remember them in memory and the next step can do a fast PHP look up from that result in memory.

Note

DataImport v1.4.x doesn’t support the batch processing by default and the next version will provide a very clear solution for it.

ORM vs PDO

ORM (Object-relational mapping) is a very good approach when we are working on very big and complex software but it’s not always the answer to all problems especially when it comes to batch processing. ORM is slow by design as they need to handle so many internal hydration and mapping.

Here is an example of using the Propel ORM, this is a very clean and nice approach but not optimized enough for importing big data.

protected function createOrUpdateProductAbstract(DataSetInterface $dataSet): SpyProductAbstract
{
    $productAbstractEntityTransfer = $this->getProductAbstractTransfer($dataSet);

    $productAbstractEntity = SpyProductAbstractQuery::create()
        ->filterBySku($productAbstractEntityTransfer->getSku())
        ->findOneOrCreate()
        ->save()
    ;

    return $productAbstractEntity;
}

This approach has two problems:

It runs two queries, one SELECT for findOneOrCreate and one INSERT or UPDATE for save.
Single process approach (repeated per each entry)

The solution is:

Avoid ORM, you can use a very simple raw SQL but you should also avoid complex raw or big raw SQL queries.
Implement DataSetWriterInterface to achieve the batch processing approach, prepare one by one and write them once (Take a look at ProductAbstractWriter in Dataimport as an example).

Facade calls

Sometimes you may need to run some validation or business logic for each data set, the easiest and safest way would be a Facade API call, that’s totally fine, but then imagine if these APIs also call some heavy queries very deep! this has a huge side effect on your performance during importing millions of data.

Here you can see for each product stock, there are two facade calls, each facade call may run more than 5 queries, this means for importing 1,000,000 data, you will have 10,000,000 queries! (this will never finish!).

protected function updateBundleAvailability(): void
{
    foreach (static::$stockProductCollection as $stockProduct) {
        if (!$stockProduct[ProductStockHydratorStep::KEY_IS_BUNDLE]) {
            continue;
        }
        $this->productBundleFacade->updateBundleAvailability($stockProduct[ProductStockHydratorStep::KEY_CONCRETE_SKU]);
        $this->productBundleFacade->updateAffectedBundlesAvailability($stockProduct[ProductStockHydratorStep::KEY_CONCRETE_SKU]);
    }
}

The solution is:

Implement a new Facade API for batch operation
Only call facade if they are very lightweight and they don’t run any query to a database

Memory management

Let’s say you already started to work with the batch operation, one of the challenges would be to keep the memory as low as possible. Sometimes you create variables and try to remember them always, but you may need them only until the end of the batch operation, so it’s better to release them as soon as possible.

Database vendor approach

Spryker supports PostgreSQL, MySQL, and MariaDB. When working with databases, it’s good to know their related features. For example, one of the great features we like is CTE. If you are inserting or updating big amounts of data, like millions of millions, use CTE as a replaceable for multiple inserts and updates. You can find examples of implementations in our Demo Shops.

Rules for Publish and Synchronize

P&S is a concept for transferring data from Zed database to Yves databases like key-value storage (Redis or Valkey) and ES, This operation is separated into two isolated processes which call Publish and Synchronize. Publishing is a process to aggregating data and writing it to Database and Queue. Synchronization is a process to read an aggregated message from a queue and write it to external endpoints. The performance issues mostly come from Publishing part. Again we need to follow the best practices to increase the performance. Here you will find some of them:

Single vs batch operation

When you are creating a new listener you should consider these rules:

Run your logic against a chunk of event messages not per each.
Don’t run the query inside of for-loop
Try to save them with a bulk operation, not one by one

Take a look at this example:

public function publish(array $productAbstractIds): void
{
    foreach ($productAbstractIds as $idProductAbstract) {
        $productAbstractProductListStorageEntity = $this->queryProductAbstractProductListEntity($idProductAbstract);
    }

}

Here we are passing a set of ids and then we try to run a query for each product abstract. Imagine if you have 2000 events as a chunk, then you have 2000 queries to a database.

We can easily fix this by changing the query and run query only once per 2000 ids.

public function publish(array $productAbstractIds): void
{
     $productAbstractProductListStorageEntities = $this->queryProductAbstractProductListEntities($productAbstractIds);
}

Facade calls

Another point that we need to be very careful here is to call Facade API without any thinking through, we must make sure that these APIs will not run queries inside same as DataImport rule. You are allowed to call Facade API but if:

There is no query inside
Facade API designed for batch operation (findPriceForSku vs findPricesForSkus)

Triggering events

DataImporters are triggering events manually, this is happening because of performance reasons :

Triggering events automatically will generate so many duplicates events during data importing, (e.g: Inserting a Product into spy_product and spy_product_localized_attribute table will generate two events with the same id_product). Events will be triggered one by one.

You can always switch the Event Triggering process with two methods:

use Spryker\Zed\EventBehavior\EventBehaviorConfig;
...

    public function foo()
    {
        /**
         * Disable the events triggering automatically
         */
        EventBehaviorConfig::disableEvent();

        // 1.Create many entities in multiple tables (e.g API bulk import, nightly update jobs)
        // 2.Trigger proper events if it's necessary ($eventFacade->triggerBulk('ProductAbstractPublish', $eventTransfers))

        /**
         * Enable the events triggering automatically
         */
        EventBehaviorConfig::enableEvent();
    }

P&S and CTE

Sometimes the amount of the data which needs be synced is very high, for this reason, we can not rely on a standard ORM solution for storing data in the database tables. we recommend you to use bulk insert operation whenever you have more than hundreds of thousand of data. you can still use the CTE technique which was used in DataImporter before. Spryker suite comes with several examples of using CTE technique in Storage and Search module you can replace them by overwriting the Business Factory in the modules:

Note

These examples only tested for PostgreSQL.

src/Pyz/Zed/PriceProductStorage/Business/Storage/PriceProductAbstractStorageWriter.php
src/Pyz/Zed/PriceProductStorage/Business/Storage/PriceProductConcreteStorageWriter.php
src/Pyz/Zed/ProductPageSearch/Business/Publisher/ProductAbstractPagePublisher.php
src/Pyz/Zed/ProductPageSearch/Business/Publisher/ProductConcretePageSearchPublisher.php
src/Pyz/Zed/ProductStorage/Business/Storage/ProductAbstractStorageWriter.php
src/Pyz/Zed/ProductStorage/Business/Storage/ProductConcreteStorageWriter.php
src/Pyz/Zed/UrlStorage/Business/Storage/UrlStorageWriter.php

Example classes are going to be replaced with a Core CTE solution.

Conclusion

When we are facing some batch operation, we need to think about big data and performance under heavy loading, we are not allowed to write same code that only does the job, it needs to be scalable and fast for high usages. Below you can find our main points:

Create batch queries and processes
Don’t use ORM for batch processing as it’s slow by design
Don’t run separated queries for each data-set
Don’t call any facade logic if they are slow or run internal queries
Release memory after each bulk operations to prevent memory issues
Use CTE technique (supported by PostgreSQL or MySQL >= 8, and MariaDB >= 10.2)

Ratings and Reviews

Thu, 26 Mar 2026 10:56:54 +0000

Drive sales by including user reviews and ratings. Reviews and ratings are a proven sign of trust; they allow brands to receive valuable and moderate feedback in the Administration Interface. The Ratings and Reviews feature also comes with the functionality to add text-free reviews and star ratings. ## Video tutorial For more details about managing ratings and reviews, check the video:

## Ratings & Reviews capabilities available in Spryker | NAME | MARKETPLACE COMPATIBLE | | --- | --- | | Spryker | No | ## Current constraints The feature has the following functional constraints, which are going to be resolved in the future: - Product reviews are linked to locales but not stores. - A review is available in all the stores that share the locale of the store in which it has been originally created. ## Related Business User documents | BACK OFFICE USER GUIDES | | - | | [Manage product reviews in the Back Office](/docs/pbc/all/ratings-reviews/latest/manage-product-reviews-in-the-back-office.html) | ## Related Developer documents | INSTALLATION GUIDES | GLUE API GUIDES | DATA IMPORT | TUTORIALS AND HOWTOS | |---------|---------|---------| - | | [Install the Product Rating and Reviews feature](/docs/pbc/all/ratings-reviews/latest/install-and-upgrade/install-the-product-rating-and-reviews-feature.html) | [Managing product ratings and reviews using Glue API](/docs/pbc/all/ratings-reviews/latest/manage-using-glue-api/glue-api-manage-product-reviews.html) | [File details: product_review.csv](/docs/pbc/all/ratings-reviews/latest/import-and-export-data/import-file-details-product-review.csv.html) | [HowTo: Configure product reviews](/docs/pbc/all/ratings-reviews/latest/tutorials-and-howtos/howto-configure-product-reviews.html) | | [Install the Product Rating and Reviews Glue API](/docs/pbc/all/ratings-reviews/latest/install-and-upgrade/install-the-product-rating-and-reviews-glue-api.html) | [Retrieve product reviews when retrieving abstract products](/docs/pbc/all/ratings-reviews/latest/manage-using-glue-api/glue-api-retrieve-product-reviews-when-retrieving-abstract-products.html) | | | | [Install the Product Rating and Reviews + Product Group feature](/docs/pbc/all/ratings-reviews/latest/install-and-upgrade/install-the-product-rating-and-reviews-product-group-feature.html) | [Retrieving product reviews when retrieving concrete products](/docs/pbc/all/ratings-reviews/latest/manage-using-glue-api/glue-api-retrieve-product-reviews-when-retrieving-concrete-products.html) | | |

Migrate from the ACP Vertex app

Wed, 25 Mar 2026 12:51:03 +0000

This document describes how to migrate from the MessageBroker-based [ACP Vertex](https://docs-archive.spryker.com/docs/pbc/all/tax-management/202507.0/base-shop/third-party-integrations/vertex/vertex) integration to the direct `spryker-eco/vertex` module. {% info_block infoBox "Info" %} The tax calculation logic remains the same. The ECO module communicates directly with the Vertex API from your application instead of going through the MessageBroker. {% endinfo_block %} ## 1. Install and integrate the module Follow the [Integrate Vertex](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/integrate-vertex.html) guide to install and set up the module. ## 2. Remove old ACP plugins and configuration ### 2a. Remove the TaxApp MessageBroker handler In `src/Pyz/Zed/MessageBroker/MessageBrokerDependencyProvider.php`, remove the following import and plugin registration: ```php // Remove this use statement: use Spryker\Zed\TaxApp\Communication\Plugin\MessageBroker\TaxAppMessageHandlerPlugin; // Remove from getMessageHandlerPlugins(): new TaxAppMessageHandlerPlugin(), ``` {% info_block infoBox "Info" %} If TaxApp was the only ACP app using the MessageBroker, you can also disable the `message-broker-consume-channels` cronjob in `config/Zed/cronjobs/jenkins.php` and set `MessageBrokerConstants::IS_ENABLED` to `false` in `config/Shared/config_default.php` to stop unnecessary background processing. {% endinfo_block %} ### 2b. Remove the TaxApp publisher plugin for DMS projects In `src/Pyz/Zed/Publisher/PublisherDependencyProvider.php`, remove the following import and plugin registration: ```php // Remove this use statement: use Spryker\Zed\TaxApp\Communication\Plugin\Publisher\Store\RefreshTaxAppStoreRelationPublisherPlugin; // In getTaxAppPlugins(), return an empty array: protected function getTaxAppPlugins(): array { return []; } ``` ### 2c. Replace the TaxApp calculation plugin In `src/Pyz/Zed/Calculation/CalculationDependencyProvider.php`, replace `TaxAppCalculationPlugin` with `VertexCalculationPlugin` in both quote and order calculator stacks: ```php // Remove: use Spryker\Zed\TaxApp\Communication\Plugin\Calculation\TaxAppCalculationPlugin; // Add: use SprykerEco\Zed\Vertex\Communication\Plugin\Calculation\VertexCalculationPlugin; ``` In `getQuoteCalculatorPluginStack()` and `getOrderCalculatorPluginStack()`, replace: ```php // Before: new TaxAppCalculationPlugin(), // After: new VertexCalculationPlugin(), ``` ### 2d. Replace the TaxApp OMS plugins In `src/Pyz/Zed/Oms/OmsDependencyProvider.php`, replace the plugins: ```php // Remove: use Spryker\Zed\TaxApp\Communication\Plugin\Oms\Command\SubmitPaymentTaxInvoicePlugin; use Spryker\Zed\TaxApp\Communication\Plugin\Oms\OrderRefundedEventListenerPlugin; // Add: use SprykerEco\Zed\Vertex\Communication\Plugin\Oms\Command\VertexSubmitPaymentTaxInvoicePlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Oms\VertexOrderRefundedEventListenerPlugin; ``` In `extendCommandPlugins()`, replace: ```php // Before: $commandCollection->add(new SubmitPaymentTaxInvoicePlugin(), 'TaxApp/SubmitPaymentTaxInvoice'); // After: $commandCollection->add(new VertexSubmitPaymentTaxInvoicePlugin(), 'Vertex/SubmitPaymentTaxInvoice'); ``` In `getOmsEventTriggeredListenerPlugins()`, replace: ```php // Before: new OrderRefundedEventListenerPlugin(), // After: new VertexOrderRefundedEventListenerPlugin(), ``` ### 2e. Replace the TaxApp Glue Storefront API plugin In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, replace the plugin: ```php // Remove: use Spryker\Glue\TaxAppRestApi\Plugin\TaxValidateIdResourceRoutePlugin; // Add: use SprykerEco\Glue\Vertex\Plugin\VertexTaxValidateIdResourceRoutePlugin; ``` In `getResourceRoutePlugins()`, replace: ```php // Before: new TaxValidateIdResourceRoutePlugin(), // After: new VertexTaxValidateIdResourceRoutePlugin(), ``` ### 2f. Update OMS state machine XML Update your OMS process XML files — for example, `config/Zed/oms/DummyPayment01.xml` — to reference the new command name: ```xml ``` ### 2g. Clean up config_default.php Remove TaxApp-specific configuration and MessageBroker channel mappings from `config/Shared/config_default.php`: ```php // Remove these transfer use statements: use Generated\Shared\Transfer\ConfigureTaxAppTransfer; use Generated\Shared\Transfer\DeleteTaxAppTransfer; use Generated\Shared\Transfer\SubmitPaymentTaxInvoiceTransfer; // Remove this use statement: use Spryker\Shared\TaxApp\TaxAppConstants; // Remove TaxAppConstants from OAuth and tenant assignments: // $config[TaxAppConstants::OAUTH_PROVIDER_NAME] = ... // $config[TaxAppConstants::OAUTH_GRANT_TYPE] = ... // $config[TaxAppConstants::OAUTH_OPTION_AUDIENCE] = ... // $config[TaxAppConstants::TENANT_IDENTIFIER] = ... // Remove TaxApp MessageBroker channel mappings from $config[MessageBrokerConstants::CHANNEL_TO_RECEIVER_TRANSPORT_MAP]: // ConfigureTaxAppTransfer::class => 'tax-commands', // DeleteTaxAppTransfer::class => 'tax-commands', // SubmitPaymentTaxInvoiceTransfer::class => 'payment-tax-invoice-commands', ``` ## 3. Add new Vertex configuration ### 3a. Add Vertex credentials In `config/Shared/config_default.php`, add the following: ```php use SprykerEco\Shared\Vertex\VertexConstants; $config[VertexConstants::IS_ACTIVE] = getenv('VERTEX_IS_ACTIVE') ?: null; $config[VertexConstants::CLIENT_ID] = getenv('VERTEX_CLIENT_ID') ?: null; $config[VertexConstants::CLIENT_SECRET] = getenv('VERTEX_CLIENT_SECRET') ?: null; $config[VertexConstants::SECURITY_URI] = getenv('VERTEX_SECURITY_URI') ?: null; $config[VertexConstants::TRANSACTION_CALLS_URI] = getenv('VERTEX_TRANSACTION_CALLS_URI') ?: null; // Optional: Tax ID Validator (Vertex Validator / Taxamo) $config[VertexConstants::TAXAMO_API_URL] = getenv('TAXAMO_API_URL') ?: null; $config[VertexConstants::TAXAMO_TOKEN] = getenv('TAXAMO_TOKEN') ?: null; ``` ### 3b. Override feature flags Create `src/Pyz/Zed/Vertex/VertexConfig.php`: ```php */ protected function getCalculableObjectVertexExpanderPlugins(): array { return [ new CalculableObjectCustomerWithVertexCodeExpanderPlugin(), new CalculableObjectExpensesWithVertexCodeExpanderPlugin(), new CalculableObjectItemProductOptionWithVertexCodeExpanderPlugin(), new CalculableObjectItemWithVertexSpecificFieldsExpanderPlugin(), new MerchantProfileAddressCalculableObjectTaxAppExpanderPlugin(), new ProductOfferAvailabilityCalculableObjectTaxAppExpanderPlugin(), ]; } /** * @return array<\SprykerEco\Zed\Vertex\Dependency\Plugin\OrderVertexExpanderPluginInterface|\Spryker\Zed\TaxAppExtension\Dependency\Plugin\OrderTaxAppExpanderPluginInterface> */ protected function getOrderVertexExpanderPlugins(): array { return [ new OrderCustomerWithVertexCodeExpanderPlugin(), new OrderExpensesWithVertexCodeExpanderPlugin(), new OrderItemProductOptionWithVertexCodeExpanderPlugin(), new OrderItemWithVertexSpecificFieldsExpanderPlugin(), new MerchantProfileAddressOrderTaxAppExpanderPlugin(), new ProductOfferAvailabilityOrderTaxAppExpanderPlugin(), ]; } /** * @return array<\Spryker\Zed\CalculationExtension\Dependency\Plugin\CalculationPluginInterface> */ protected function getFallbackQuoteCalculationPlugins(): array { return [ new TaxAmountCalculatorPlugin(), new ItemTaxAmountFullAggregatorPlugin(), new PriceToPayAggregatorPlugin(), new TaxRateAverageAggregatorPlugin(), ]; } /** * @return array<\Spryker\Zed\CalculationExtension\Dependency\Plugin\CalculationPluginInterface> */ protected function getFallbackOrderCalculationPlugins(): array { return [ new TaxAmountCalculatorPlugin(), new ItemTaxAmountFullAggregatorPlugin(), new PriceToPayAggregatorPlugin(), new TaxAmountAfterCancellationCalculatorPlugin(), ]; } } ``` ## 4. Set up the database and transfers ```bash vendor/bin/console propel:install vendor/bin/console transfer:generate ``` ## 5. 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. ## 6. Verify the migration 1. Clear caches: `vendor/bin/console cache:empty-all`. 2. Place a test order and verify that tax calculation works. 3. If invoicing is enabled, verify that the `Vertex/SubmitPaymentTaxInvoice` OMS command triggers correctly. 4. If tax ID validation is enabled, test the `POST /tax-id-validate` Glue Storefront API endpoint. For detailed verification steps, see [Verify Vertex connection](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/verify-vertex-connection.html). ## Summary of changes | Component | ACP (before) | ECO (after) | |-----------|-------------|-------------| | Tax calculation plugin | `TaxAppCalculationPlugin` | `VertexCalculationPlugin` | | OMS invoice command | `SubmitPaymentTaxInvoicePlugin` (`TaxApp/...`) | `VertexSubmitPaymentTaxInvoicePlugin` (`Vertex/...`) | | OMS refund listener | `OrderRefundedEventListenerPlugin` | `VertexOrderRefundedEventListenerPlugin` | | Glue tax validation | `TaxValidateIdResourceRoutePlugin` | `VertexTaxValidateIdResourceRoutePlugin` | | MessageBroker handler | `TaxAppMessageHandlerPlugin` | Removed (not needed) | | Publisher plugin | `RefreshTaxAppStoreRelationPublisherPlugin` | Removed (not needed) | | Configuration | `TaxAppConstants` + OAuth | `VertexConstants` + direct API credentials | | Communication | Via MessageBroker (async) | Direct Vertex API calls (sync) |

Performance guidelines

Wed, 25 Mar 2026 12:42:04 +0000

These performance guidelines originate from Spryker's years of experience across all kinds of projects, environments, and setups. They cover topics that are often missed at the project level, leading to poor performance or other related issues. The guidelines help you analyze and optimize performance of your website from different perspectives: - [Keeping dependencies updated](/docs/dg/dev/guidelines/performance-guidelines/keeping-dependencies-updated.html) to maintain optimal performance and security by staying current with Spryker module updates. - [Monitoring](/docs/dg/dev/guidelines/performance-guidelines/monitoring.html) to ensure effective application monitoring using APM tools. - [General performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/general-performance-guidelines.html) for general approaches to optimizing the server-side execution time. - [Architecture performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/architecture-performance-guidelines.html) to optimize performance in the very end servers. - [Frontend performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/front-end-performance-guidelines.html) to do the frontend-specific optimization. - [Twig performance best practices](/docs/dg/dev/guidelines/performance-guidelines/twig-performance-best-practices.html) to optimize Twig templating engine performance. - [Session locks](/docs/dg/dev/guidelines/performance-guidelines/session-locks.html) to optimize session locking mechanisms and reduce performance impact. Also see [Redis session lock](/docs/dg/dev/troubleshooting/troubleshooting-performance-issues/redis-session-lock.html) for troubleshooting session lock issues. - [Bot control](/docs/dg/dev/guidelines/performance-guidelines/bot-control.html) to manage honest and malicious bot traffic effectively. - [Batch processing of Propel entities](/docs/dg/dev/guidelines/performance-guidelines/performance-guidelines-batch-processing-propel-entities.html) for efficient batch processing, reduced database load, and support for complex entity relationships. - [Database performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/database-performance-guidelines.html) to optimize database operations through proper indexing, query optimization, and avoiding common database anti-patterns. - [Key-Value storage performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/key-value-storage-performance-guidelines.html) to optimize Redis/ValKey usage by limiting operations, avoiding admin commands in runtime, and implementing proper caching strategies. - [External HTTP requests](/docs/dg/dev/guidelines/performance-guidelines/external-http-requests.html) to understand Spryker's architecture principle of reading from fast storage and learn how to manage external HTTP requests when they're necessary. - [Search performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/search-performance-guidelines.html) to optimize Elasticsearch and OpenSearch performance, avoid common search anti-patterns, and implement efficient search queries. - [Infrastructure and worker configuration guidelines](/docs/dg/dev/guidelines/performance-guidelines/infrastructure-worker-configuration-guidelines.html) to optimize nginx configuration and worker orchestration for multi-store setups. - [CDN and traffic management integration](/docs/dg/dev/guidelines/performance-guidelines/cdn-and-traffic-management-integration.html) to configure CDN solutions like Akamai or Cloudflare to work correctly with Spryker's nginx compression and avoid unnecessary data transfer overhead. - [Custom code performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/custom-code-performance-guidelines.html) to implement performant custom code including caching strategies, background processing, and Quote calculator optimization. - [Common pitfalls in OMS design](/docs/pbc/all/order-management-system/latest/base-shop/datapayload-conversion/state-machine/common-pitfalls-in-oms-design.html) to avoid performance bottlenecks in Order Management System processes, especially ensuring heavy operations run in CLI context rather than during web requests. - [Order management system multi-thread](/docs/pbc/all/order-management-system/latest/base-shop/datapayload-conversion/state-machine/order-management-system-multi-thread.html) to process OMS timeouts and conditions in parallel for improved order processing performance. - [Troubleshooting performance issues](/docs/dg/dev/troubleshooting/troubleshooting-performance-issues/troubleshooting-performance-issues.html) for detecting and fixing common performance problems. - [Order details page performance guidance](/docs/pbc/all/order-management-system/latest/base-shop/order-management-feature-overview/order-details-page-performance-overview.html) to optimize the order detail page in the Back Office

Order details page performance guidance

Wed, 25 Mar 2026 12:35:52 +0000

The Back Office order details page can contain a large number of sub-requests. While sub-requests are a valid architectural pattern, in high-traffic environments they can become a source of performance issues—each sub-request adds latency and load to the system. To address this, Spryker introduces two plugin stacks that replace sub-requests with direct plugin-based data expansion and rendering on the order details page. ## How it works Previously, the order details page loaded data and rendered blocks by making sub-requests to other modules. Each sub-request was an independent HTTP call processed by the application stack, which multiplied response time and resource consumption proportionally to the number of blocks on the page. The new approach uses two plugin stacks: 1. **Data expansion plugins**: Plugins collect and provide data directly, bypassing sub-requests. 2. **Block renderer plugins**: Plugins render template blocks directly, bypassing sub-requests. If a plugin is registered, its data or rendered output is used. If a plugin is not registered, the system falls back to the original sub-request behavior, ensuring backward compatibility. ## Install the feature To install the feature, update the required modules using Composer. The following is the full list of modules involved—your project may not require all of them. ```bash composer update spryker/gift-card:"^1.13.0" spryker/manual-order-entry:"^1.3.0" spryker/money:"^2.17.0" spryker/oms:"^11.52.0" spryker/refund:"^5.15.0" spryker/sales:"^11.81.0" spryker/sales-extension:"^1.14.0" spryker/sales-order-threshold-gui:"^2.2.0" spryker/sales-payment-detail:"^1.6.0" spryker/sales-product-configuration-gui:"^1.1.0" spryker/sales-return-gui:"^2.2.0" spryker/shipment-gui:"^3.2.0" spryker-feature/self-service-portal:"^19.4.0" spryker/merchant-user:"^1.9.1" ``` For a full integration example, see the [B2B Demo Marketplace integration PR](https://github.com/spryker-shop/b2b-demo-marketplace/pull/957/changes). For the complete release details, see [Release Group 6396](https://api.release.spryker.com/release-group/6396). ## Plugin stacks ### Data expansion plugins The `getSalesOrderDetailDataExpanderPlugins()` method in `SalesDependencyProvider` registers plugins that expand order detail data directly, without sub-requests. **Location:** `src/Pyz/Zed/Sales/SalesDependencyProvider.php` ```php /** * @return array<\Spryker\Zed\SalesExtension\Dependency\Plugin\SalesOrderDetailDataExpanderPluginInterface> */ protected function getSalesOrderDetailDataExpanderPlugins(): array { return [ new ShipmentSalesOrderDetailDataExpanderPlugin(), new ProductConfigurationSalesOrderDetailDataExpanderPlugin(), new CommentsSalesOrderDetailDataExpanderPlugin(), new OmsFormsSalesOrderDetailDataExpanderPlugin(), new ThresholdExpensesSalesOrderDetailDataExpanderPlugin(), new ShipmentExpensesSalesOrderDetailDataExpanderPlugin(), ]; } ``` {% info_block infoBox "Plugin registration" %} Register only the plugins that are relevant to your project. Not all plugins may be required depending on the modules you use. {% endinfo_block %} ### Block renderer plugins The `getSalesDetailBlockRendererPlugins()` method in `SalesDependencyProvider` registers plugins that render order detail blocks directly, without sub-requests. **Location:** `src/Pyz/Zed/Sales/SalesDependencyProvider.php` ```php /** * @return array<\Spryker\Zed\SalesExtension\Dependency\Plugin\SalesDetailBlockRendererPluginInterface> */ protected function getSalesDetailBlockRendererPlugins(): array { return [ new OrderTransferBlockRendererPlugin(), new SalesCommentBlockRendererPlugin(), new SalesReturnListBlockRendererPlugin(), new SalesPaymentDetailListBlockRendererPlugin(), new RefundSalesListBlockRendererPlugin(), new SelfServicePortalOrderInquiryListBlockRendererPlugin(), ]; } ``` {% info_block infoBox "Plugin registration" %} Register only the plugins that are relevant to your project. Not all plugins may be required depending on the modules you use. {% endinfo_block %} This plugin stack replaces the sub-request configuration defined in `\Pyz\Zed\Sales\SalesConfig::getSalesDetailExternalBlocksUrls`. ### OrderTransferBlockRendererPlugin template map `OrderTransferBlockRendererPlugin` requires an additional configuration on the project level that maps block URLs to Twig templates. **Location:** `src/Pyz/Zed/Sales/SalesConfig.php` ```php /** * @return array */ public function getOrderDetailBlockUrlToTemplateMap(): array { return [ '/cart-note/sales/list' => '@CartNote/Sales/list.twig', '/comment-sales-connector/sales/list' => '@CommentSalesConnector/Sales/list.twig', '/cart-note-product-bundle-connector/sales/list' => '@CartNoteProductBundleConnector/Sales/list.twig', '/sales-payment-gui/sales/list' => '@SalesPaymentGui/Sales/list.twig', '/discount/sales/list' => '@Discount/Sales/list.twig', ]; } ``` Include only the entries that correspond to the modules enabled in your project.

Integrate Vertex

Wed, 25 Mar 2026 12:21:38 +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. 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(), ]; } ``` ## 7. 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 %} ``` ## 8. 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)

AI Foundation Audit Logs

Wed, 25 Mar 2026 08:44:45 +0000

This document describes how to use audit logging with the AiFoundation module to track and audit AI interactions in your Spryker application.

The audit logging feature provides comprehensive tracking of all AI interactions, including prompts, responses, token usage, inference time, and metadata. This enables monitoring, compliance, cost tracking, and debugging of AI operations.

Back Office: Audit Logs page

After enabling audit logging, you can view and analyze AI interaction logs in the Back Office at Intelligence > Audit Logs.

The Audit Logs page provides:

Summary statistics cards: Total requests, total tokens consumed, success rate, and average inference time for the filtered dataset.
Filterable data table: Filter logs by configuration name, status (success/failed), conversation reference, and date range.
Detail drawer: Click a row’s prompt to view complete prompt and response text, token breakdown, metadata, and error details.

The AiFoundation module registers its navigation under the Intelligence menu. To include the Audit Logs entry in your project navigation, add the following to config/Zed/navigation.xml:

<ai-foundation>
    <label>Intelligence</label>
    <title>Intelligence</title>
    <icon>network_intel_node</icon>
    <pages>
        <ai-interaction-log>
            <label>Audit Logs</label>
            <title>Audit Logs</title>
            <bundle>ai-foundation</bundle>
            <controller>ai-interaction-log</controller>
            <action>index</action>
        </ai-interaction-log>
    </pages>
</ai-foundation>

After updating the navigation XML, rebuild the navigation cache:

console navigation:cache:remove

Overview

The AiFoundation audit logging system automatically captures detailed information about each AI interaction:

Configuration and Provider Information: The AI configuration name, provider, and model used
Prompt and Response Data: The user prompt and AI response messages
Token Usage: Input and output token counts for cost tracking
Performance Metrics: Inference time in milliseconds
Metadata: Tool invocations, errors, and structured schema information
Conversation Tracking: Links to conversation references for multi-turn conversations
Status: Success or failure status of each interaction
Timestamps: Creation timestamps for each logged interaction

All AI interactions are persisted to the spy_ai_interaction_log database table and can be queried, analyzed, and audited.

Architecture

The audit logging system uses post-prompt plugins to capture AI interaction data and integrates with the Spryker logging infrastructure. For detailed architecture information, see AiFoundation module Overview.

Enable audit logging

1. Register the audit logger plugins

<?php

namespace Pyz\Zed\AiFoundation;

use Spryker\Zed\AiFoundation\AiFoundationDependencyProvider as SprykerAiFoundationDependencyProvider;
use Spryker\Zed\AiFoundation\Communication\Plugin\AuditLogPostPromptPlugin;
use Spryker\Zed\AiFoundation\Communication\Plugin\AuditLogPostToolCallPlugin;
use Spryker\Zed\AiFoundation\Communication\Plugin\Log\AiInteractionHandlerPlugin;

class AiFoundationDependencyProvider extends SprykerAiFoundationDependencyProvider
{
    /**
     * @return array<\Spryker\Zed\AiFoundation\Dependency\Plugin\PostPromptPluginInterface>
     */
    protected function getPostPromptPlugins(): array
    {
        return [
            new AuditLogPostPromptPlugin(),
        ];
    }
    
    /**
     * @return array<\Spryker\Zed\AiFoundation\Dependency\Plugin\PostToolCallPluginInterface>
     */
    protected function getPostToolCallPlugins(): array
    {
        return [
            new AuditLogPostToolCallPlugin(),
        ];
    }

    /**
     * @return array<\Spryker\Shared\Log\Dependency\Plugin\LogHandlerPluginInterface>
     */
    protected function getAiInteractionLogHandlerPlugins(): array
    {
        return [
            new AiInteractionHandlerPlugin(),
        ];
    }
}

2. Configure the audit logger in your config

In your configuration file (for example, config/Shared/config_default.php), add the AiInteractionAuditLoggerConfigPlugin to the audit logger plugins:

<?php

use Spryker\Shared\Log\LogConstants;
use Spryker\Zed\AiFoundation\Communication\Plugin\Log\AiInteractionAuditLoggerConfigPlugin;

$config[LogConstants::AUDIT_LOGGER_CONFIG_PLUGINS_ZED] = [
    // existing plugins...
    AiInteractionAuditLoggerConfigPlugin::class,
];

$config[LogConstants::AUDIT_LOGGER_CONFIG_PLUGINS_MERCHANT_PORTAL] = [
    // existing plugins...
    AiInteractionAuditLoggerConfigPlugin::class,
];

3. Generate transfers

Generate the transfer objects for audit logging:

console transfer:generate

4. Run database migrations

Run the database migrations to create the spy_ai_interaction_log table:

console propel:install

Understanding AI interaction log data

AiInteractionLog transfer properties

Each logged AI interaction contains the following information:

Property	Type	Description
`idAiInteractionLog`	int	Unique identifier for the log record
`configurationName`	string	AI configuration name
`provider`	string	AI provider name
`model`	string	AI model name
`prompt`	string	User prompt sent to the AI
`response`	string	AI response message
`inputTokens`	int	Input token count
`outputTokens`	int	Output token count
`conversationReference`	string	Conversation reference for multi-turn conversations
`inferenceTimeMs`	int	Inference time in milliseconds
`isSuccessful`	bool	Interaction success status
`metadata`	string	JSON-encoded metadata
`createdAt`	string	Timestamp (ISO 8601 format)

Best practices

Regular cleanup: Implement a periodic cleanup process to archive or delete old audit logs if required by your retention policies
Cost tracking: Use token counts to monitor and optimize AI usage costs
Performance monitoring: Track inference times to identify slow interactions
Error analysis: Review failed interactions to improve prompts and error handling
Metadata inspection: Store and analyze metadata to understand tool invocations and structured responses

AiFoundation module Overview

Wed, 25 Mar 2026 08:31:12 +0000

This document describes how to integrate and use the AiFoundation module to interact with various AI providers in your Spryker application. The AiFoundation module provides a unified interface for working with multiple AI providers, such as OpenAI, Anthropic Claude, AWS Bedrock, and others.

The AiFoundation module uses a Zed-backed architecture where the client provides a simple interface that delegates all processing to the Zed facade. This design enables centralized management of AI configurations, conversation history persistence, and tool execution.

Architecture

The AiFoundation module uses a two-layer architecture:

Client Layer: Provides a simple AiFoundationClientInterface that serves as the entry point for AI interactions
Zed Layer: Contains the AiFoundationFacade that handles all business logic including:
- AI configuration resolution
- Vendor adapter plugin delegation
- Conversation history persistence and retrieval
- Tool execution and invocation tracking
- Structured response validation and mapping

The client delegates all processing to the Zed facade through a request stub, ensuring centralized management of AI operations and database persistence.

Install the AiFoundation module

Require the package:
```
composer require spryker/ai-foundation
```
Generate transfers:
```
console transfer:generate
```

Configure AI providers

Configure AI providers in a dedicated configuration file. The module uses the AI_CONFIGURATIONS constant to define one or more AI configurations.

Best practice

Create a separate configuration file for AI settings to keep your configuration organized and maintainable.

Security

Store API keys as environment variables, not in configuration files. For Spryker Cloud, use the parameter store to manage sensitive credentials. For details, see Add variables in the parameter store.

Create a new configuration file config/Shared/config_ai.php:

<?php

use Spryker\Shared\AiFoundation\AiFoundationConstants;

// AI provider configurations
$config[AiFoundationConstants::AI_CONFIGURATIONS] = [
    // Your AI configurations will be defined here
];

Include the AI configuration file in your main configuration file (for example, config/Shared/config_default.php):
```
<?php

require 'config_ai.php';
```

Alternatively, you can define AI configurations directly in config/Shared/config_default.php if you prefer a single configuration file approach.

Configuration structure

Each AI configuration requires:

provider_name: The AI provider identifier (required)
provider_config: Provider-specific configuration (required)
system_prompt: Default system prompt for the AI provider

Default configuration

The module automatically uses the configuration named AI_CONFIGURATION_DEFAULT when you do not specify a configuration in the PromptRequest. Define at least one default configuration:

<?php

use Spryker\Shared\AiFoundation\AiFoundationConstants;

$config[AiFoundationConstants::AI_CONFIGURATIONS] = [
    AiFoundationConstants::AI_CONFIGURATION_DEFAULT => [
        'provider_name' => AiFoundationConstants::PROVIDER_OPENAI,
        'provider_config' => [
            'key' => getenv('OPENAI_API_KEY'),
            'model' => 'gpt-4o',
        ],
        // Resolved at runtime from Configuration Management
        'system_prompt' => AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX . 'ai_commerce:backoffice_assistant:general:system_prompt',
    ],
];

Any string value prefixed with configuration:: (AiFoundationConstants::CONFIGURATION_REFERENCE_PREFIX) is resolved at runtime via the Configuration Management module. This lets admin users update AI settings—model, API key, system prompt—from the Back Office without a code deployment.

Provider configuration examples

OpenAI

'openai-config' => [
    'provider_name' => AiFoundationConstants::PROVIDER_OPENAI,
    'provider_config' => [
        'key' => getenv('OPENAI_API_KEY'), // required
        'model' => 'gpt-4o', // required
        'parameters' => [], // optional
        'httpOptions' => [ // optional
            'timeout' => 60,
            'connectTimeout' => 5,
            'headers' => [],
        ],
    ],
    'system_prompt' => 'You are a helpful assistant.', // optional
],

Anthropic Claude

'anthropic-config' => [
    'provider_name' => AiFoundationConstants::PROVIDER_ANTHROPIC,
    'provider_config' => [
        'key' => getenv('ANTHROPIC_API_KEY'), // required
        'model' => 'claude-sonnet-4-20250514', // required
        'version' => '2023-06-01', // optional
        'max_tokens' => 8192, // optional
        'parameters' => [], // optional
        'httpOptions' => [ // optional
            'timeout' => 60,
        ],
    ],
],

AWS Bedrock

AWS Bedrock requires a system_prompt configuration. AWS credentials are automatically loaded from environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN.

'bedrock-config' => [
    'provider_name' => AiFoundationConstants::PROVIDER_BEDROCK,
    'provider_config' => [
        'model' => 'eu.anthropic.claude-sonnet-4-20250514-v1:0', // required
        'bedrockRuntimeClient' => [ // required
            'region' => 'eu-west-1', // required
            'version' => 'latest', // optional
        ],
    ],
    'system_prompt' => 'You are a helpful assistant.', // required for Bedrock
],

Ollama (local/self-hosted)

If Ollama runs outside the Docker SDK on macOS, use http://host.docker.internal:11434/api as the URL to access the host machine from within Docker containers.

'ollama-config' => [
    'provider_name' => AiFoundationConstants::PROVIDER_OLLAMA,
    'provider_config' => [
        'url' => 'http://host.docker.internal:11434/api', // required - use host.docker.internal for Mac when Ollama runs outside Docker
        'model' => 'llama3.2', // required
        'parameters' => [], // optional
        'httpOptions' => [ // optional
            'timeout' => 60,
            'connectTimeout' => 5,
        ],
    ],
],

Run Ollama with Docker SDK

To run Ollama as a service within the Spryker Docker SDK:

Create an ollama.yml file in your project root:

version: '3.8'

services:
    ollama:
        image: ollama/ollama:latest
        environment:
            OLLAMA_HOST: "0.0.0.0:11435"
        volumes:
            - ./data/tmp/ollama_data:/root/.ollama
        networks:
            - private
            - public

Reference the Ollama compose file in your deploy.dev.yml:
```
compose:
    yamls: ['./ollama.yml']
```

Update your AI configuration to use the Ollama service URL:

'ollama-config' => [
    'provider_name' => AiFoundationConstants::PROVIDER_OLLAMA,
    'provider_config' => [
        'url' => 'http://ollama:11435/api', // use service name when running inside Docker SDK
        'model' => 'llama3.2',
    ],
],

Deploy the changes:

docker/sdk boot deploy.dev.yml
docker/sdk up

Pull the required Ollama model:

docker/sdk cli exec -c ollama ollama pull llama3.2

The Ollama data is stored in the ./data/tmp/ollama_data directory, which you should exclude from version control (.gitignore or .dockerignore).

Google Gemini

'gemini-config' => [
    'provider_name' => AiFoundationConstants::PROVIDER_GEMINI,
    'provider_config' => [
        'key' => getenv('GEMINI_API_KEY'), // required
        'model' => 'gemini-2.0-flash', // required
        'parameters' => [], // optional
    ],
],

Deepseek

'deepseek-config' => [
    'provider_name' => AiFoundationConstants::PROVIDER_DEEPSEEK,
    'provider_config' => [
        'key' => getenv('DEEPSEEK_API_KEY'), // required
        'model' => 'deepseek-chat', // required
        'parameters' => [], // optional
    ],
],

HuggingFace

'huggingface-config' => [
    'provider_name' => AiFoundationConstants::PROVIDER_HUGGINGFACE,
    'provider_config' => [
        'key' => getenv('HUGGINGFACE_API_KEY'), // required
        'model' => 'meta-llama/Llama-3.3-70B-Instruct', // required
        'parameters' => [], // optional
    ],
],

Mistral AI

'mistral-config' => [
    'provider_name' => AiFoundationConstants::PROVIDER_MISTRAL,
    'provider_config' => [
        'key' => getenv('MISTRAL_API_KEY'), // required
        'model' => 'mistral-large-latest', // required
        'parameters' => [], // optional
    ],
],

xAI Grok

'grok-config' => [
    'provider_name' => AiFoundationConstants::PROVIDER_GROK,
    'provider_config' => [
        'key' => getenv('XAI_API_KEY'), // required
        'model' => 'grok-2-latest', // required
        'parameters' => [], // optional
    ],
],

Azure OpenAI

'azure-openai-config' => [
    'provider_name' => AiFoundationConstants::PROVIDER_AZURE_OPEN_AI,
    'provider_config' => [
        'key' => getenv('AZURE_OPENAI_API_KEY'), // required
        'endpoint' => 'https://your-resource.openai.azure.com', // required
        'model' => 'your-deployment-name', // required
        'version' => '2024-02-01', // optional
        'parameters' => [], // optional
    ],
],

Use the AiFoundation facade

Basic usage

<?php

namespace Pyz\Zed\YourModule\Business;

use Generated\Shared\Transfer\PromptMessageTransfer;
use Generated\Shared\Transfer\PromptRequestTransfer;
use Spryker\Zed\AiFoundation\Business\AiFoundationFacadeInterface;

class YourBusinessModel
{
    public function __construct(
        protected AiFoundationFacadeInterface $aiFoundationFacade
    ) {
    }

    public function generateContent(string $userMessage): string
    {
        $promptRequest = (new PromptRequestTransfer())
            ->setPromptMessage(
                (new PromptMessageTransfer())->setContent($userMessage)
            );

        $response = $this->aiFoundationFacade->prompt($promptRequest);

        return $response->getMessage()->getContent();
    }
}

Using a specific configuration

Specify a configuration name to use a configuration other than the default:

$promptRequest = (new PromptRequestTransfer())
    ->setAiConfigurationName('anthropic-config')
    ->setPromptMessage(
        (new PromptMessageTransfer())->setContent('Explain Spryker modules')
    );

$response = $this->aiFoundationFacade->prompt($promptRequest);

Multiple configurations example

Configure multiple AI providers for different use cases in your application:

<?php

use Spryker\Shared\AiFoundation\AiFoundationConstants;

$config[AiFoundationConstants::AI_CONFIGURATIONS] = [
    AiFoundationConstants::AI_CONFIGURATION_DEFAULT => [
        'provider_name' => AiFoundationConstants::PROVIDER_OPENAI,
        'provider_config' => [
            'key' => getenv('OPENAI_API_KEY'),
            'model' => 'gpt-4o',
        ],
    ],
    'fast-responses' => [
        'provider_name' => AiFoundationConstants::PROVIDER_OPENAI,
        'provider_config' => [
            'key' => getenv('OPENAI_API_KEY'),
            'model' => 'gpt-4o-mini',
        ],
        'system_prompt' => 'Provide concise, brief responses.',
    ],
];

Available provider constants

The module provides the following provider constants in AiFoundationConstants:

PROVIDER_OPENAI - OpenAI (ChatGPT)
PROVIDER_ANTHROPIC - Anthropic Claude
PROVIDER_BEDROCK - AWS Bedrock Runtime
PROVIDER_GEMINI - Google Gemini
PROVIDER_DEEPSEEK - Deepseek AI
PROVIDER_HUGGINGFACE - HuggingFace
PROVIDER_MISTRAL - Mistral AI
PROVIDER_OLLAMA - Ollama (local/self-hosted)
PROVIDER_GROK - xAI Grok
PROVIDER_AZURE_OPEN_AI - Azure OpenAI

Transfer objects

PromptRequest

This transfer contains the request data for AI interaction:

promptMessage (PromptMessage, required): The message to send to the AI
aiConfigurationName (string, optional): The configuration name to use. If not provided, uses AI_CONFIGURATION_DEFAULT
structuredMessage (object, optional): A Transfer object that defines the expected response structure for structured responses
toolSetName (string[], optional): Array of tool set names to make available to the AI. For details, see Use AI tools with the AiFoundation module
conversationReference (string, optional): Unique identifier for multi-turn conversations. When provided, the message is persisted in conversation history and previous messages are automatically included in the request context. For details, see Manage conversation history with the AiFoundation module
maxRetries (int, optional): Maximum number of retry attempts for failed requests. Default is 0

PromptMessage

This transfer represents a message in the conversation:

content (string): The text content of the message
contentData (array, optional): Additional structured data
attachments (Attachment[], optional): File or image attachments

PromptResponse

This transfer contains the AI response:

message (PromptMessage): The AI’s response message
isSuccessful (bool): Whether the request was successful
errors (array, optional): Array of error messages if the request failed
toolInvocations (ToolInvocation[], optional): Array of tool invocations made by the AI during response generation

Attachment

This transfer represents a file or image attachment:

type (string): Type of attachment (use AiFoundationConstants::ATTACHMENT_TYPE_IMAGE or ATTACHMENT_TYPE_DOCUMENT)
content (string): The content (URL or Base64-encoded data)
contentType (string): Content type format (use AiFoundationConstants::ATTACHMENT_CONTENT_TYPE_URL or ATTACHMENT_CONTENT_TYPE_BASE64)
mediaType (string): MIME type (for example, image/png, application/pdf)

ToolInvocation

This transfer contains information about a tool invocation made by the AI:

name (string): The name of the tool that was invoked
arguments (array): The arguments passed to the tool
result (string): The result returned by the tool execution

StructuredMessage

Define the expected structure (structuredMessage property) of the AI response for structured responses. This is a Spryker Transfer object that you can customize based on your requirements.

Conversation History

Conversation history is created by conversationReference and persisted in the database using the spy_ai_conversation_history table. When you provide a conversationReference in a prompt request, all messages are automatically stored and previous messages are retrieved to maintain conversation context. For complete details, see Manage conversation history with the AiFoundation module.

About NeuronAI framework

The AiFoundation module uses the NeuronAI PHP agentic framework under the hood. NeuronAI provides the foundational infrastructure for AI provider integrations.

The Spryker AiFoundation client is designed for simple use cases where you need to send prompts to AI providers and receive responses. This covers most common AI integration scenarios in e-commerce applications.

For advanced agentic solutions that require complex workflows, multi-agent systems, or custom AI behaviors, you can use the NeuronAI framework directly in your project code. However, note that Spryker does not officially support direct usage of NeuronAI APIs outside of the AiFoundation module. If you choose to use NeuronAI directly, you are responsible for maintenance and compatibility with future versions.

Warehouse Management System

Mon, 23 Mar 2026 16:09:31 +0000

The *Warehouse Management System* capability lets you create and manage warehouses and their stock. The capability consists of the Demo Shop and additional features. The Demo Shop includes warehouse and inventory management for running a regular shop, as well as marketplace functionality for creating virtual warehouses per merchant and managing their stock. The additional features support omnichannel fulfillment operations. ## Demo shop The Demo Shop provides the core warehouse and inventory management features, including marketplace functionality for managing merchant-specific stock: - [Inventory Management feature overview](/docs/pbc/all/warehouse-management-system/latest/base-shop/inventory-management-feature-overview.html) - manage warehouses, stock quantities, and product availability across stores. - [Availability Notification feature overview](/docs/pbc/all/warehouse-management-system/latest/base-shop/availability-notification-feature-overview.html) - let customers subscribe to back-in-stock notifications for out-of-stock products. - [Product Availability Display feature overview](/docs/pbc/all/warehouse-management-system/latest/base-shop/product-availability-display-feature-overview.html) - show stock quantities and availability status on product pages and in carts. - [Manage in the Back Office](/docs/pbc/all/warehouse-management-system/latest/base-shop/manage-in-the-back-office/manage-warehouses-in-the-back-office.html) - create and edit warehouses, check product availability, and manage stock. - [Import and export data](/docs/pbc/all/warehouse-management-system/latest/base-shop/import-and-export-data/warehouse-management-system-data-import.html) - import warehouses, warehouse addresses, store assignments, and product stock. - [Marketplace Inventory Management feature overview](/docs/pbc/all/warehouse-management-system/latest/marketplace/marketplace-inventory-management-feature-overview.html) - create virtual warehouses per merchant and manage merchant product offer stock. ## Additional features Unified Commerce features support omnichannel fulfillment operations: - [Fulfillment App overview](/docs/pbc/all/warehouse-management-system/latest/unified-commerce/fulfillment-app-overview.html) - pick and pack orders using the Fulfillment App. - [Warehouse Picking feature overview](/docs/pbc/all/warehouse-management-system/latest/unified-commerce/warehouse-picking-feature-overview.html) - generate pick lists to streamline warehouse order fulfillment. - [Warehouse User Management feature overview](/docs/pbc/all/warehouse-management-system/latest/unified-commerce/warehouse-user-management-feature-overview.html) - assign warehouse users to specific warehouses for picking operations.

Spryker Documentation

Upgrade the OMS module

Data import optimization guidelines

Rules for data importers

Progress bar

Single vs batch operation

ORM vs PDO

Facade calls

Memory management

Database vendor approach

Rules for Publish and Synchronize

Single vs batch operation

Facade calls

Triggering events

P&S and CTE

Conclusion

Ratings and Reviews

Migrate from the ACP Vertex app

Performance guidelines

Order details page performance guidance

Integrate Vertex

AI Foundation Audit Logs

Back Office: Audit Logs page

Navigation setup

Overview

Architecture

Enable audit logging

1. Register the audit logger plugins

2. Configure the audit logger in your config

3. Generate transfers

4. Run database migrations

Understanding AI interaction log data

AiInteractionLog transfer properties

Best practices

AiFoundation module Overview

Architecture

Install the AiFoundation module

Configure AI providers

Configuration structure

Default configuration

Provider configuration examples

OpenAI

Anthropic Claude

AWS Bedrock

Ollama (local/self-hosted)

Run Ollama with Docker SDK

Google Gemini

Deepseek

HuggingFace

Mistral AI

xAI Grok

Azure OpenAI

Use the AiFoundation facade

Basic usage

Using a specific configuration

Multiple configurations example

Available provider constants

Transfer objects

PromptRequest

PromptMessage

PromptResponse

Attachment

ToolInvocation

StructuredMessage

Conversation History

About NeuronAI framework

Warehouse Management System