Spryker Documentation

Serialization

Mon, 30 Mar 2026 13:08:44 +0000

API Platform uses the [Spryker Serializer module](/docs/dg/dev/guidelines/serializer-guidelines.html) for converting between PHP objects back and forth. The Serializer is registered as a Symfony service and integrates directly with API Platform's serialization pipeline. ## How it works When a request hits an API Platform endpoint: 1. **Request deserialization** — the incoming payload is deserialized into the resource object using the Serializer. (API Platform) 2. **Provider/Processor** — your provider or processor works with the resource object, converts to array and or Transfer objects, and vice versa. 3. **Response serialization** — the resource object is serialized back into the expected response format. (API Platform) API Platform handles this automatically. You interact with the Serializer only when you need to customize serialization behavior. ## Customizing serialization context Use `SerializerContextTransfer` to control how data is serialized in your providers or processors. Common use cases: - **Serialization groups** — control which properties are included in the response - **Skip null values** — omit null properties from the output - **DateTime formatting** — set a custom date/time format For the full list of available context options, see the [Serializer guidelines](/docs/dg/dev/guidelines/serializer-guidelines.html). ## Custom normalizers To add a custom normalizer that applies to API Platform resources, implement `SerializerNormalizerPluginInterface` and register it in `SerializerDependencyProvider`. Custom normalizers take priority over built-in normalizers. For details on the Symfony Serializer component, see the [Symfony documentation](https://symfony.com/doc/current/serializer.html).

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)

Serializer guidelines

Mon, 30 Mar 2026 06:26:35 +0000

The Serializer module provides a Spryker-native wrapper around the [Symfony Serializer component](https://symfony.com/doc/current/serializer.html). It exposes serialization operations through the Spryker Service layer and supports extension via plugins. ## Operations The `SerializerServiceInterface` provides four operations: | Method | Description | |---|---| | `serialize()` | Converts data to a string format (JSON, XML, CSV) | | `deserialize()` | Converts a string into a typed object | | `normalize()` | Converts an object or data structure to an associative array | | `denormalize()` | Converts an array into a typed object | All operations accept an optional `SerializerContextTransfer` to configure behavior. ## SerializerContextTransfer The `SerializerContextTransfer` maps Spryker transfer conventions to Symfony Serializer context options. Supported options include: - **groups** — serialization groups for attribute filtering - **isSkipNullValues** — omit null properties from output - **isSkipUninitializedValues** — omit uninitialized properties - **isPreserveEmptyObjects** — keep empty objects as `{}` instead of `[]` - **isEnableMaxDepth** — enable max depth handling - **datetimeFormat** — custom date/time format string - **datetimeTimezone** — timezone for date/time normalization - **defaultConstructorArguments** — default constructor arguments for denormalization - **symfonyContext** — raw Symfony context array for advanced use cases (overrides explicit properties) For the full list of Symfony context options, see the [Symfony Serializer documentation](https://symfony.com/doc/current/serializer.html#context). ## Extension via plugins The module supports two plugin interfaces for registering custom normalizers and encoders: - `SerializerNormalizerPluginInterface` — provides additional normalizers/denormalizers - `SerializerEncoderPluginInterface` — provides additional encoders/decoders Register plugins in your project's `SerializerDependencyProvider`: ```php protected function getSerializerNormalizerPlugins(): array { return [ new YourCustomNormalizerPlugin(), ]; } ``` Custom normalizers are prepended before built-in normalizers, giving them higher priority. ## Built-in support The module includes the following Symfony normalizers and encoders out of the box: **Normalizers:** ObjectNormalizer, ArrayDenormalizer, DateTimeNormalizer, DateTimeZoneNormalizer, DateIntervalNormalizer, BackedEnumNormalizer, DataUriNormalizer, JsonSerializableNormalizer, UidNormalizer, UnwrappingDenormalizer **Encoders:** JsonEncoder, XmlEncoder, CsvEncoder

Guidelines

Mon, 30 Mar 2026 06:26:35 +0000

This section contains a collection of useful guidelines for developing on the Spryker Commerce OS: - [Coding guidelines](/docs/dg/dev/guidelines/coding-guidelines/coding-guidelines.html) - [Keeping a project upgradable](/docs/dg/dev/guidelines/keeping-a-project-upgradable/keeping-a-project-upgradable.html) - [Performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/general-performance-guidelines.html) - [Testing guidelines](/docs/dg/dev/guidelines/testing-guidelines/testing-best-practices/testing-concepts.html) - [Project development guidelines](/docs/dg/dev/guidelines/project-development-guidelines.html) - [Data processing guidelines](/docs/dg/dev/guidelines/data-processing-guidelines.html) - [Module configuration convention](/docs/dg/dev/guidelines/module-configuration-convention.html) - [Security guidelines](/docs/dg/dev/guidelines/security-guidelines.html) - [Serializer guidelines](/docs/dg/dev/guidelines/serializer-guidelines.html)

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

Spryker Documentation

Serialization

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

Serializer guidelines

Guidelines

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