Spryker Documentation

AI Dev SDK Skills and Agents

Tue, 28 Jul 2026 12:39:52 +0000

Experimental module

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

Overview

The AI Dev SDK ships a set of skills and agents that codify common Spryker workflows. They reach your project in two ways:

Via the ai-dev:setup console command — copies the skills and agents into your project’s AI-tool directories (.claude/skills/ + .claude/agents/, .windsurf/skills/ + .windsurf/agents/, and so on). Works for every AI tool listed on the AI Dev SDK Overview that supports an agents directory. Codex CLI is the one exception — it has no agents directory, so agents are skipped for that tool.
Via the Claude Code plugin — for Claude Code users, the Claude Code Plugin installs the same skills and agents through the official marketplace, no console command required.

Both delivery paths read from the same source files — the plugin just packages them for marketplace installation.

What’s the difference between a skill and an agent?

Skills load into the active chat on demand. Use them when you want the assistant to follow a specific workflow (write a product requirement document, refresh caches, run QA).
Agents are isolated sub-conversations the assistant delegates to. Use them when you want focused, single-purpose work done in its own context window (verify a behavior, diagnose a failure).

You do not need to remember the names — the assistant picks the right skill or agent from your prompt. The tables below explain what each one does so you know what to expect.

How to invoke

In most cases you do not need to call a skill or agent by name. Describe what you want — “build this feature”, “verify the new fee shows on the cart”, “write a product requirement document for…” — and the assistant matches your wording to the right skill or agent from the set installed in your project.

If you want to invoke one explicitly:

Claude Code plugin — every skill is also available as a slash command. Type /<skill-name> (for example /spryker-customization) and the skill loads into the current chat. The full list of commands is on the Claude Code Plugin page.
Other AI tools — invocation follows the tool’s own convention for skills and agents. In Cursor, Windsurf, Copilot, OpenCode, and Codex CLI, the skills and agents land in the tool-specific directories (.cursor/, .windsurf/, etc.) and are picked up automatically by your assistant. The AI Dev SDK Overview lists the output paths per tool.
Agents (subagents) are not invoked by the user directly — they are spawned by the assistant or by a parent skill when the work calls for an isolated context. You can suggest one by name in your prompt (“use the spryker-verifier to…”), but the assistant decides when to spawn.

Skills

Skills are delivered through ai-dev:setup (all supported AI tools) or the Claude Code plugin.

Skill	Purpose	Benefits
`ai-dev-setup`	Generate rules, an agents/context file, and skills for the project and the chosen AI tool	One command sets up consistent AI tooling for the whole team
`code-review`	Review staged or PR changes against Spryker coding standards	Catches Spryker-specific issues before they reach a pull request
`propel-schema`	Create and modify Propel ORM schema files	Follows Spryker schema conventions automatically
`data-import`	Create and modify data import CSV files and importers	Generates importers that fit Spryker’s data-import path
`codecept-functional`	Generate Codeception functional tests	Tests follow Spryker test patterns out of the box
`static-validation`	Run and interpret static analysis tools (PHPStan, PHP CS Fixer)	Quick diagnosis of style and type issues without context-switching
`payment-template`	Scaffold payment method integration	Follows Spryker payment module patterns end-to-end
`yves-atomic-frontend`	Create atomic design components for the Yves storefront	Components match the project’s atomic conventions
`product-requirement-document`	Turn a feature idea into a research-grounded product requirement document before any code is written	Spec-before-code; assigns a real Spryker actor to every story; cuts ambiguity before implementation
`spryker-customization`	Walk a product requirement document or set of acceptance criteria through to a committed branch	One workflow drives the full build; quality bar (PoC or MVP) chosen up-front; delegates focused work to the agents below; never auto-commits
`spryker-bugfix`	Drive a bug from an optional tracker ticket or a plain description through to a committed, validated, QA-accepted fix	Orchestrates reproduce, root-cause, minimal fix, functional test, static validation, review, QA, and final verification; a shared attempt budget loops back on any failed gate; Autonomous mode adds a pushed Draft PR with a remote-CI watch loop
`spryker-refresher`	Run the right post-change console and composer commands after edits	Owns the file-to-command mapping (codegen, caches, frontend builds, class-resolver); no missed cache rebuilds
`spryker-qa-coverage`	Turn acceptance criteria into a four-bucket test plan executed against the live app	Coverage goes beyond literal ACs — happy / negative / authorization / corner cases; reports pass/fail with real evidence
`spryker-docs-research`	Look up the right answer in official Spryker documentation	Grounds AI work in documented behavior rather than the model’s memory; falls back gracefully when MCP tools are unavailable
`spryker-runtime`	Drive the running Spryker application — Yves, Back Office, Merchant Portal, console, HTTP	Real authenticated sessions; read-only DB / Redis / queue inspection; reusable building block for higher-level skills and agents
`ai-runtime-debugging`	Inspect Spryker runtime state safely from an AI session	`[AI-DEBUG]` tagged-log pattern plus optional XDebug step-debug; built-in cleanup of debug instrumentation before commit
`project-ci-generator`	Transform an inherited product-style CI setup into a single, lean project CI pipeline	Reads the CI that actually exists rather than applying a template; reuses the discovered commands verbatim so the result stays environment-correct; proposes a keep/drop plan for approval before deleting anything; ports the same jobs to GitLab or Bitbucket

Agents

Agents are delivered through ai-dev:setup (every supported AI tool with an agents directory) or the Claude Code plugin.

Agent	Purpose	Benefits
`spryker-code-reviewer`	Review code against Spryker’s coding standards and architectural rules	Deeper, Spryker-aware review than a generic linter; catches layer-architecture and module-convention issues
`spryker-feature-expert`	Answer “how does feature X work in this project / in Spryker”	Pushes back when the user’s framing reinvents an existing primitive; surfaces canonical patterns first; never edits code
`spryker-verifier`	Verify that a specific behavior holds in the running Spryker environment	Returns PASS / FAIL / BLOCKED per acceptance criterion with raw evidence; never lies green; never tries to fix
`spryker-issue-diagnoser`	Investigate why something failed and return a root cause	Reads logs, DB state, queue, search, browser console — returns a suggested direction; never attempts the fix itself
`spryker-data-seeder`	Create small additive test data through Spryker’s existing import path	Safe and incremental — CSV + `data:import` only; never edits code, never writes directly to the database
`spryker-screenshot-collector`	Capture screenshots and GIFs of pages and flows for demos and documentation	Pure capture — never asserts whether something works, never investigates failures, never edits

Claude Code Plugin

Tue, 28 Jul 2026 12:39:52 +0000

Experimental module

Project must be running

The MCP server runs inside your Spryker Docker container. Start your project with docker/sdk run before using any skills that rely on MCP tools.

Overview

Working with Spryker in an AI coding assistant without project-specific context leads to a predictable pattern: the AI generates plausible-looking code that does not follow Spryker’s layer architecture, uses the wrong patterns, or misses module conventions entirely. You end up spending more time correcting mistakes than you saved.

The spryker-ai-dev-sdk Claude Code plugin closes this gap. It gives Claude Code deep knowledge of how Spryker projects are structured — layers, namespaces, plugin stacks, transfer objects, OMS flows — so the code it generates fits your project from the start instead of requiring repeated corrections.

What it does for you:

No more explaining Spryker basics. Rules covering 20 Spryker architectural patterns are automatically loaded into every session. Claude Code knows about factories, dependency providers, expanders, mappers, and more without you having to explain them.
Correct code on the first attempt. Skills for common Spryker tasks — Propel schema changes, data importers, functional tests, payment integrations, atomic frontend components — follow the exact conventions your project expects.
Live project context. The MCP server runs inside your Docker container and gives Claude Code real-time access to your transfer objects, module interfaces, and OMS configuration. The AI works with your actual project data, not guesses.
Consistent code reviews. The spryker-code-reviewer subagent checks your changes against Spryker’s coding standards and architectural rules, catching issues before they reach a PR.
Team-wide consistency. Generated rules and context files are committed to your repository, so every developer on the team works with the same AI configuration.

The plugin is distributed through the spryker-plugins-official marketplace and installed directly inside Claude Code.

Prerequisites

Claude Code installed
Your Spryker project is running: docker/sdk run

Install the plugin from the marketplace

Open Claude Code in your terminal.
Add the Spryker plugin marketplace:
Install the plugin:
After installation, reload plugins in Claude Code.

Set up AI tooling for your project

After installing the plugin, run the ai-dev-setup skill to configure your project. The skill generates rules, context files, and reusable AI skills tailored to your project and AI tool.

In Claude Code, run the setup skill:

The skill:

Installs the spryker-sdk/ai-dev package in your Spryker project.
Wires up console commands for McpServerConsole and AiToolSetupConsole.
Registers the AI Dev MCP server with Claude Code.
Adds .claude/rules/ with Spryker coding conventions and architectural guidelines.
Adds CLAUDE.md with project-specific context loaded into every Claude Code session.

Check with running /context in Claude Code to see:

Capabilities

For a one-page reference of every skill and agent — what each does, when to use it, and the value it adds — see AI Dev SDK Skills and Agents.

Skills

The plugin bundles the following Spryker-aware skills. Invoke them in Claude Code with the / prefix.

Skill	Command	Description
AI Dev Setup	`/spryker-ai-dev-sdk:ai-dev-setup`	Generates rules, a context file, and skills for your project and AI tool
Code Review	`/spryker-ai-dev-sdk:code-review`	Reviews staged or PR changes against Spryker coding standards
Propel Schema	`/spryker-ai-dev-sdk:propel-schema`	Helps create and modify Propel ORM schema files following Spryker conventions
Data Import	`/spryker-ai-dev-sdk:data-import`	Assists with creating and modifying data import CSV files and importers
Codecept Functional	`/spryker-ai-dev-sdk:codecept-functional`	Generates Codeception functional tests following Spryker test patterns
Static Validation	`/spryker-ai-dev-sdk:static-validation`	Runs and interprets static analysis tools (PHPStan, PHP CS Fixer)
Payment Template	`/spryker-ai-dev-sdk:payment-template`	Scaffolds payment method integration following Spryker payment module patterns
Yves Atomic Frontend	`/spryker-ai-dev-sdk:yves-atomic-frontend`	Helps create atomic design components for the Yves frontend
Product Requirement Document	`/spryker-ai-dev-sdk:product-requirement-document`	Drafts a research-grounded product requirement document for a Spryker feature before implementation
Spryker Customization	`/spryker-ai-dev-sdk:spryker-customization`	Orchestrates the end-to-end build of a customization from product requirement document to committed branch
Spryker Bugfix	`/spryker-ai-dev-sdk:spryker-bugfix`	Orchestrates the end-to-end bug fix from a ticket or description to a committed, validated, QA-accepted branch (Autonomous mode adds a pushed Draft PR with a CI watch loop)
Spryker Refresher	`/spryker-ai-dev-sdk:spryker-refresher`	Runs the right post-change console and composer commands after edits
Spryker QA Coverage	`/spryker-ai-dev-sdk:spryker-qa-coverage`	Turns acceptance criteria into a four-bucket test plan and executes it against the running app
Spryker Docs Research	`/spryker-ai-dev-sdk:spryker-docs-research`	Looks up grounded answers in the official Spryker documentation
Spryker Runtime	`/spryker-ai-dev-sdk:spryker-runtime`	Drives the running Spryker application — storefront, back office, console, HTTP
AI Runtime Debugging	`/spryker-ai-dev-sdk:ai-runtime-debugging`	Adds tagged debug logs (and optional XDebug) for inspecting Spryker runtime state
Project CI Generator	`/spryker-ai-dev-sdk:project-ci-generator`	Rebuilds an inherited product-style CI setup into a single, lean project CI pipeline, keeping only the jobs and support files the project needs

Subagents

The plugin includes the following subagents. They are isolated sub-conversations that the assistant delegates to for focused, single-purpose work:

Subagent	Description
`spryker-code-reviewer`	Performs deep code reviews of your changes against Spryker architectural patterns, coding standards, and best practices
`spryker-feature-expert`	Answers questions about how a Spryker feature, module, or capability works, grounded in docs and the project’s actual code
`spryker-verifier`	Verifies a specific behavior in the running Spryker environment and returns PASS, FAIL, or BLOCKED per acceptance criterion with raw evidence
`spryker-issue-diagnoser`	Investigates a failure across logs, database, queue, search, and browser state and returns a root cause
`spryker-data-seeder`	Creates small additive test data through Spryker’s existing data import path
`spryker-screenshot-collector`	Captures screenshots and short GIFs of pages and flows for demos and documentation

Rules

The ai-dev-setup skill writes a set of Spryker-specific coding rules into your project. These rules guide the AI to follow Spryker conventions automatically, without requiring you to explain them in every prompt.

Rule file	What it enforces
`business-models.md`	Business model structure and responsibilities
`client-zed-communication.md`	Client–Zed gateway communication patterns
`controller.md`	Controller conventions and responsibilities
`dependency-provider.md`	Dependency provider wiring and plugin stacks
`enforce-constants-for-control-flow.md`	Use of constants instead of magic strings in control flow
`expander-pattern.md`	Expander pattern for extending transfer objects
`factory-pattern.md`	Factory class structure and dependency injection
`form-data-loading-performance.md`	Performant data loading in Zed forms
`layer-communication.md`	Cross-layer call rules (Presentation → Communication → Business → Persistence)
`mapper-pattern.md`	Mapper pattern for transfer-to-transfer and entity-to-transfer mappings
`module-config.md`	Module configuration class conventions
`naming-conventions.md`	Class, method, and variable naming standards
`owasp.md`	OWASP security guidelines applied to Spryker code
`performance.md`	Performance best practices (query optimization, caching)
`persistence.md`	Persistence layer conventions (repositories, entity managers)
`php-code-style.md`	PHP code style rules (PSR compliance, formatting)
`plugins.md`	Plugin and plugin interface implementation patterns
`table.md`	Back Office table and query container conventions
`transfer-object.md`	Transfer object usage and immutability rules
`upgradability.md`	Backward compatibility and upgradability guidelines

Context file

The ai-dev-setup skill generates a CLAUDE.md context file based on the AGENTS.example.md template. This file is automatically loaded into every Claude Code session and provides:

Common Docker CLI commands for your Spryker project
Spryker application layer overview (Zed, Yves, Glue, Client, Service, Shared)
Namespace and directory structure
Component rules for controllers, plugins, factories, repositories, and more
Abstract class references for all layers

Starting point, not a complete setup

The files generated by ai-dev-setup are a baseline derived from Spryker defaults. They cover general Spryker conventions but do not include anything specific to your project — custom modules, third-party integrations, team conventions, or environment details. Treat the generated CLAUDE.md and rules as a starting point and extend them with your project-specific requirements.

Security release notes 202306.0

Tue, 28 Jul 2026 12:32:55 +0000

The following information pertains to security-related issues that have been recently resolved. All issues are listed by description and affected modules. If you need any additional support with this content, [contact our support](https://support.spryker.com/). If you found a new security vulnerability, inform us through [security@spryker.com](mailto:security@spryker.com). ## Stored XSS in product pages Administrators can place a malicious payload into the description section of new and existing product pages in the Back Office application. This payload is then executed to all users of the shop that visit the affected product pages, resulting in a Cross-Site Scripting (XSS) vulnerability. ### Affected modules `spryker/product-management`: 0.19.3-0.19.35 ### Introduced changes Sanitization controls have been implemented to prevent the input of malicious payloads within product forms. ### How to get the fix To implement a fix for this vulnerability, the ProductManagement module should be updated to version 0.19.36. If your version of `spryker/product-management` is earlier than 0.19.35, follow these steps: 1. Upgrade the `spryker/store` module to version 1.19.0 and `spryker/zed-request-extension` to version 1.1.0: ```bash composer require spryker/store:"~1.19.0" spryker/zed-request-extension:"~1.1.0" composer show spryker/store # Verify the version composer show spryker/zed-request-extension # Verify the version ``` 2. Upgrade the `spryker/product-management` module to version 0.19.36: ```bash composer require spryker/product-management:"~0.19.36" spryker/gui:"~3.48.0" spryker/util-sanitize-xss:"~1.1.0" composer show spryker/product-management # Verify the version ``` ## Cross-company role manipulation Because of missing access validation controls on the backend, an administrator user of a company was able to create and update roles for other companies. This was possible because of the possibility to manipulate the company ID parameter included in the HTTP requests of the role creation functionality. ### Affected modules `spryker-shop/company-page`: 1.0.0-2.21.0 ### Introduced changes Access validation controls have been implemented to prevent administrators from being able to create and edit roles for other companies. ### How to get the fix The update requires PHP 8 to be installed. If you are using PHP 7, see [PHP 8.1 as the minimum version for all Spryker projects](https://docs.spryker.com/docs/scos/user/intro-to-spryker/whats-new/php8-as-a-minimum-version-for-all-spryker-projects.html) for details on how to migrate to PHP 8.1. To implement a fix for this vulnerability, upgrade the `company-page` module to version 2.22.0: ```bash composer require spryker-shop/company-page:"~2.22.0" composer show spryker-shop/company-page # Verify the version ``` ## Unvalidated URL redirection Attackers were able to bypass the redirect URL validation for URLs provided through the GET request parameter and control the website that the user is redirected to. This type of vulnerability can be used in conjunction with social engineering to coerce a victim into navigating to a malicious resource or location. ### Affected modules `spryker/kernel`: 1.0.0-3.72.0 ### Introduced changes Additional validation controls have been implemented to prevent an attacker from being able to manipulate the location of the URL redirection. ### How to get the fix To implement a fix for this vulnerability, update the `kernel` module: - If your version of `spryker/kernel` is 3.72.0, update to version 3.72.1: ```bash composer require spryker/kernel:"~3.72.1" composer show spryker/kernel # Verify the version ``` - If your version of `spryker/kernel` is 3.71.0 or 3.71.1, update to version 3.71.2: ```bash composer require spryker/kernel:"~3.71.2" composer show spryker/kernel # Verify the version ``` - If your version of `spryker/kernel` is 3.70.0, update to version 3.70.1: ```bash composer require spryker/kernel:"~3.70.1" composer show spryker/kernel # Verify the version ``` - If your version of `spryker/kernel` is earlier than 3.69.0, update to version 3.68.1: ```bash composer require spryker/kernel:"~3.68.1" composer show spryker/kernel # Verify the version ``` ## Brute-force attacks on the Storefront and in the Back Office The Storefront, the Back Office, and the Merchant portals were prone to brute-force attacks. By exploiting this type of vulnerability, an attacker was able to systematically attempt different combinations of usernames and passwords against the login pages of the affected portals until a valid combination was identified. ### Affected modules `spryker/security-blocker`: 1.0.0-1.1.1 ### Introduced changes Maximum login attempts and blocking time can be configured for the affected portals. ### How to get the fix 1. Upgrade the `spryker/security-blocker` module version to 1.2.0: ```bash composer require spryker/security-blocker:"~1.2.0" composer show spryker/security-blocker # Verify the version ``` 2. Upgrade the `spryker/error-handler` module version to 2.8.0: ```bash composer require spryker/error-handler:"~2.8.0" composer show spryker/error-handler # Verify the version ``` 3. Install the `spryker/security-blocker-backoffice` module version 1.0.0: ```bash composer require spryker/security-blocker-backoffice:"~1.0.0" composer show spryker/security-blocker-backoffice # Verify the version ``` 4. Install the `spryker/security-blocker-backoffice-gui` module version 1.0.0: ```bash composer require spryker/security-blocker-backoffice-gui:"~1.0.0" composer show spryker/security-blocker-backoffice-gui # Verify the version ``` 5. Install the `spryker/security-blocker-storefront-customer` module version 1.0.0: ```bash composer require spryker/security-blocker-storefront-customer:"~1.0.0" composer show spryker/security-blocker-storefront-customer # Verify the version ``` 6. Install the `spryker/security-blocker-storefront-agent` module version 1.0.0: ```bash composer require spryker/security-blocker-storefront-agent:"~1.0.0" composer show spryker/security-blocker-storefront-agent # Verify the version ``` 7. Generate transfers: ```bash console transfer:generate ``` 8. Add configuration to `config/Shared/config_default.php`: ```php // >>> Security Blocker Storefront Agent $config[SecurityBlockerStorefrontAgentConstants::AGENT_BLOCK_FOR_SECONDS] = 360; $config[SecurityBlockerStorefrontAgentConstants::AGENT_BLOCKING_TTL] = 900; $config[SecurityBlockerStorefrontAgentConstants::AGENT_BLOCKING_NUMBER_OF_ATTEMPTS] = 9; // >>> Security Blocker Storefront Customer $config[SecurityBlockerStorefrontCustomerConstants::CUSTOMER_BLOCK_FOR_SECONDS] = 360; $config[SecurityBlockerStorefrontCustomerConstants::CUSTOMER_BLOCKING_TTL] = 900; $config[SecurityBlockerStorefrontCustomerConstants::CUSTOMER_BLOCKING_NUMBER_OF_ATTEMPTS] = 9; // >>> Security Blocker BackOffice user $config[SecurityBlockerBackofficeConstants::BACKOFFICE_USER_BLOCKING_TTL] = 900; $config[SecurityBlockerBackofficeConstants::BACKOFFICE_USER_BLOCK_FOR_SECONDS] = 360; $config[SecurityBlockerBackofficeConstants::BACKOFFICE_USER_BLOCKING_NUMBER_OF_ATTEMPTS] = 9; ``` 9. Add translations to `data/import/common/common/glossary.csv`: ```csv security_blocker_backoffice_gui.error.account_blocked,"Too many log-in attempts from your address. Please wait %minutes% minutes before trying again.",en_US security_blocker_backoffice_gui.error.account_blocked,"Warten Sie bitte %minutes% Minuten, bevor Sie es erneut versuchen.",de_DE ``` 10. Import glossary: ```bash console data:import:glossary ``` 11. Register plugins in `SecurityBlockerDependencyProvider`: ```php */ protected function getSecurityBlockerConfigurationSettingsExpanderPlugins(): array { return [ new BackofficeUserSecurityBlockerConfigurationSettingsExpanderPlugin(), new AgentSecurityBlockerConfigurationSettingsExpanderPlugin(), new CustomerSecurityBlockerConfigurationSettingsExpanderPlugin(), ]; } } ``` 12. Adjust `src/Pyz/Zed/ErrorHandler/ErrorHandlerConfig.php`: ```php */ public function getValidSubRequestExceptionStatusCodes(): array { return array_merge( parent::getValidSubRequestExceptionStatusCodes(), [ Response::HTTP_TOO_MANY_REQUESTS, ], ); } } ``` 13. Register plugins in `src/Pyz/Yves/EventDispatcher/EventDispatcherDependencyProvider.php`: ```php class EventDispatcherDependencyProvider extends SprykerEventDispatcherDependencyProvider { ... protected function getEventDispatcherPlugins(): array { return [ ... new SecurityBlockerBackofficeUserEventDispatcherPlugin(), ]; } ... ``` If Merchant Portal is also installed, follow these steps: 1. Install the `spryker/security-blocker-merchant-portal` module version 1.0.0: ```bash composer require spryker/security-blocker-merchant-portal:"~1.0.0" composer show spryker/security-blocker-merchant-portal # Verify the version ``` 2. Install the `spryker/security-blocker-merchant-portal-gui` module version 1.0.0: ```bash composer require spryker/security-blocker-merchant-portal-gui:"~1.0.0" composer show spryker/security-blocker-merchant-portal-gui # Verify the version ``` 3. Generate transfers: ```bash console transfer:generate ``` 4. Register plugins in `src/Pyz/Zed/EventDispatcher/EventDispatcherDependencyProvider.php`: ```php class EventDispatcherDependencyProvider extends SprykerEventDispatcherDependencyProvider { ... protected function getEventDispatcherPlugins(): array { return [ ... new SecurityBlockerMerchantPortalUserEventDispatcherPlugin(), ]; } ... ``` 5. Register plugins in `SecurityBlockerDependencyProvider`: ```php */ protected function getSecurityBlockerConfigurationSettingsExpanderPlugins(): array { return [ ... new MerchantPortalUserSecurityBlockerConfigurationSettingsExpanderPlugin(), ]; } } ``` 6. Add configuration to `config/Shared/config_default.php`: ```bash // >>> Security Blocker MerchantPortal user $config[SecurityBlockerMerchantPortalConstants::MERCHANT_PORTAL_USER_BLOCK_FOR_SECONDS] = 360; $config[SecurityBlockerMerchantPortalConstants::MERCHANT_PORTAL_USER_BLOCKING_TTL] = 900; $config[SecurityBlockerMerchantPortalConstants::MERCHANT_PORTAL_USER_BLOCKING_NUMBER_OF_ATTEMPTS] = 9; ``` 7. Add translations to `data/import/common/common/glossary.csv` : ```csv security_blocker_merchant_portal_gui.error.account_blocked,"Too many log in attempts from your address. Please wait %minutes% minutes before trying again.",en_US security_blocker_merchant_portal_gui.error.account_blocked,"Warten Sie bitte %minutes% Minuten, bevor Sie es erneut versuchen.",de_DE ``` 8. Import glossary: ```bash console data:import:glossary ``` ## Weak input validation for the customer address field The parameters related to the address field had insufficient server-side input validation. By supplying invalid or potentially malicious parameter values, an attacker might be able to cause the server to respond in an unexpected way. ### Affected modules - `spryker-shop/customer-page`: 0.1.0-2.41.0 - `spryker-shop/company-page`: 0.0.1-2.22.0 - `spryker/customer`: 0.20.0-7.51.2 - `spryker/company-unit-address-gui`: 0.1.0-1.3.0 - `spryker/merchant-profile-gui`: 0.1.0-1.2.0 ### Introduced changes Input validation controls have been implemented on the server side to validate values submitted in the address field. ### How to get the fix To implement a fix for this vulnerability, update the `shop-ui`, `customer-page`, `company-page`, `customer`, `company-unit-address-gui`, and `merchant-profile-gui` modules: 1. Upgrade the `spryker-shop/shop-ui` module to at least version 1.70.0: ```bash composer require spryker-shop/shop-ui:"^1.70.0" composer show spryker-shop/customer-page # Verify the version ``` 2. Add the `SanitizeXssTypeExtensionFormPlugin` plugin to `FormDependencyProvider`: **src/Pyz/Yves/Form/FormDependencyProvider.php** ```bash */ protected function getFormPlugins(): array { return [ new SanitizeXssTypeExtensionFormPlugin(), ]; } } ``` 3. Upgrade the `spryker-shop/customer-page` module to version 2.42.0: ```bash composer require spryker-shop/customer-page:"~2.42.0" composer show spryker-shop/customer-page # Verify the version ``` 4. Upgrade the `spryker-shop/company-page` module to version 2.23.0: ```bash composer require spryker-shop/company-page:"~2.23.0" composer show spryker-shop/company-page # Verify the version ``` 5. Upgrade the `spryker/customer` module: 1. If your version of `spryker/customer` is 7.42.0 and later, update it to version 7.51.3: ```bash composer require spryker/customer:"~7.51.3" composer show spryker/customer # Verify the version ``` 2. If your version of `spryker/customer` is earlier than 7.42.0, update it to version 7.42.1: ```bash composer require spryker/customer:"~7.42.1" composer show spryker/customer # Verify the version ``` 3. If your version of `spryker/customer` is earlier than 7.50.0, update it to version 7.50.1: ```bash composer require spryker/customer:"~7.50.1" composer show spryker/customer # Verify the version ``` 6. Upgrade the `spryker/company-unit-address-gui` module to version 1.3.1: ```bash composer require spryker/company-unit-address-gui:"~1.3.1" composer show spryker/company-unit-address-gui # Verify the version ``` 7. Upgrade the `spryker/merchant-profile-gui` module version to 1.2.1: ```bash composer require spryker/merchant-profile-gui:"~1.2.1" composer show spryker/merchant-profile-gui # Verify the version ``` ## Outdated third-party library guzzlehttp/psr7 An outdated version of the `guzzlehttp/psr7` library was identified to affect Spryker's applications. The version in use, 2.4.3, was affected by a publicly known vulnerability that could let an attacker sneak in a newline (\n) into both the header names and values (CVE-2023-29197). ### Affected modules - `spryker/guzzle`: 0.20.0-2.4.0 - `spryker/message-broker-aws`: 1.0.0-1.4.2 - `spryker/secrets-manager-aws`: 1.0.0-1.0.1 - `spryker/oauth-auth0` : 1.0.0 ### Introduced changes The affected library has been upgraded. ### How to get the fix To implement a fix for this vulnerability, update the `guzzle`, `message-broker-aws`, `secrets-manager-aws`, and `oauth-auth0` modules: 1. Upgrade the `spryker/guzzle` module to version 2.4.1: ```bash composer require spryker/guzzle:"^2.4.1" composer show spryker/guzzle # Verify the version ``` 2. Upgrade the `spryker/message-broker-aws` module to version 1.4.3: ```bash composer require spryker/message-broker-aws:"^1.4.3" composer show spryker/message-broker-aws # Verify the version ``` 3. Upgrade the `spryker/secrets-manager-aws` module to version 1.0.2: ```bash composer require spryker/secrets-manager-aws:"^1.0.2" composer show spryker/secrets-manager-aws # Verify the version ``` 4. Upgrade the `spryker/oauth-auth0` module to version 1.0.1: ```bash composer require spryker/oauth-auth0:"^1.0.1" composer show spryker/oauth-auth0 # Verify the version ``` ## Missing security HTTP headers Security-related HTTP headers were missing from Spryker's applications. Adding these headers improves the overall security posture of the applications because they implement an additional layer of protection against common web application attacks. ### Affected modules - `spryker/event-dispatcher`: <=1.4.0 - `spryker/glue-backend-api-application`: <=1.3.0 - `spryker/glue-storefront-api-application`: <=1.2.0 - `spryker/http`: <=1.10.0 - `spryker/merchant-portal-application`: <=1.1.0 ### Introduced changes The following security-related HTTP headers can be implemented: - `Strict-Transport-Security` - `Cache-Control` - `X-Content-Type-Options` - `X-Frame-Options` - `X-XSS-Protection` - `Content-Security-Policy` ### How to get the fix To implement a fix for this vulnerability: 1. Update the `event-dispatcher`, `glue-backend-api-application`, `glue-storefront-api-application`, `HTTP`, and `merchant-portal-application` modules: ```bash composer update spryker/event-dispatcher spryker/glue-backend-api-application spryker/glue-storefront-api-application spryker/http spryker/merchant-portal-application ``` 2. Register `Spryker\Glue\Http\Plugin\EventDispatcher\CacheControlHeaderEventDispatcherPlugin` in `Pyz\Glue\EventDispatcher::getEventDispatcherPlugins()`. 3. Register `Spryker\Glue\GlueBackendApiApplication\Plugin\GlueApplication\StrictTransportSecurityHeaderResponseFormatterPlugin` in `Pyz\Glue\GlueBackendApiApplication\GlueBackendApiApplicationDependencyProvider::getResponseFormatterPlugins()`. 4. In `Pyz\Glue\GlueStorefrontApiApplication\GlueStorefrontApiApplicationDependencyProvider::getResponseFormatterPlugins()`, register `Spryker\Glue\GlueStorefrontApiApplication\Plugin\GlueApplication\StrictTransportSecurityHeaderResponseFormatterPlugin`. 5. In `Pyz\Yves\EventDispatcher\EventDispatcherDependencyProvider::getEventDispatcherPlugins()`, register `Spryker\Yves\Http\Plugin\EventDispatcher\CacheControlHeaderEventDispatcherPlugin`. 6. In `Pyz\Yves\EventDispatcher\EventDispatcherDependencyProvider::getEventDispatcherPlugins()`, register `Spryker\Yves\Http\Plugin\EventDispatcher\EnvironmentInfoHeaderEventDispatcherPlugin`. 7. Remove deprecated `Spryker\Yves\Http\Plugin\EventDispatcher\HeaderEventDispatcherPlugin` from `Pyz\Yves\EventDispatcher\EventDispatcherDependencyProvider::getEventDispatcherPlugins()`. 8. In `Pyz\Zed\EventDispatcher\EventDispatcherDependencyProvider::getEventDispatcherPlugins()`, register `Spryker\Zed\Http\Communication\Plugin\EventDispatcher\CacheControlHeaderEventDispatcherPlugin`. 9. In `Pyz\Zed\EventDispatcher\EventDispatcherDependencyProvider::getEventDispatcherPlugins()`, register `Spryker\Zed\Http\Communication\Plugin\EventDispatcher\EnvironmentInfoHeaderEventDispatcherPlugin`. 10. In `Pyz\Zed\EventDispatcher\EventDispatcherDependencyProvider::getMerchantPortalEventDispatcherPlugins()`, register `Spryker\Zed\MerchantPortalApplication\Communication\Plugin\EventDispatcher\HeadersSecurityEventDispatcherPlugin`. 11. Remove deprecated `Spryker\Zed\Http\Communication\Plugin\EventDispatcher\HeaderEventDispatcherPlugin` from `Pyz\Zed\EventDispatcher\EventDispatcherDependencyProvider::getEventDispatcherPlugins()`. 12. In `Pyz\Zed\MerchantPortalApplication\MerchantPortalApplicationDependencyProvider::getMerchantPortalApplicationPlugins()`, register `Spryker\Zed\EventDispatcher\Communication\Plugin\MerchantPortalApplication\MerchantPortalEventDispatcherApplicationPlugin`. 13. Overwrite `Pyz\Glue\GlueBackendApiApplication\GlueBackendApiApplicationConfig::getSecurityHeaders()` and `Pyz\Glue\GlueStorefrontApiApplication\GlueStorefrontApiApplicationConfig::getSecurityHeaders()` to set Cache-Control security header: ```php /** * @return array */ public function getSecurityHeaders(): array { return array_merge( parent::getSecurityHeaders(), ['Cache-Control' => 'no-cache, private'], ); } ``` 14. Optional: adjust `config/Shared/config_default.php` to add cache control configuration. To see the list of available directives, check `Spryker\Yves\Http\Plugin\EventDispatcher\CacheControlHeaderEventDispatcherPlugin`. {% info_block warningBox "Never enable public caching globally" %} These values are applied to *every* response of the application—the plugin cannot exempt individual pages. Setting `'public' => true` with `'max-age'` makes the cart, checkout, and customer account pages cacheable, so browsers serve a stale cart and a CDN can serve one customer's cart to another customer. If you skip this step, the applications keep the Symfony default `Cache-Control: no-cache, private`, which is safe. {% endinfo_block %} ```php use Spryker\Shared\Http\HttpConstants; $config[HttpConstants::YVES_HTTP_CACHE_CONTROL_CONFIG] = [ 'private' => true, 'no-cache' => true, ]; $config[HttpConstants::ZED_HTTP_CACHE_CONTROL_CONFIG] = [ 'private' => true, 'no-cache' => true, ]; $config[HttpConstants::GLUE_HTTP_CACHE_CONTROL_CONFIG] = [ 'private' => true, 'no-cache' => true, ]; ```

Security guidelines

Tue, 28 Jul 2026 12:32:55 +0000

This document describes the data security guidelines you need to follow on the application level. In cloud environments, infrastructure security measures are implemented by default, so they're not described. ## Passwords The most important about password security is to not save passwords in plain text. Therefore, Spryker uses BCrypt based on Blowfish to hash passwords and add a random salt to each hash, preventing rainbow table attacks. To prevent dictionary and brute force attacks, you can force users to use special characters by adding validation rules to needed forms. For even higher security, use two-factor authentication and CAPTCHA. ## Secrets Store secrets, API keys, and similar sensitive data in a dedicated secrets management system rather than in `./config/Shared/**` and `./deploy.*.yml` files. For more information about secrets and parameters, see [Add variables in the Parameter Store](/docs/ca/dev/add-variables-in-the-parameter-store.html). We recommend establishing a regular cadence of rotating secrets. For recommendations on establishing a secrets rotation policy, see [Operational Best Practices for CIS AWS Foundations Benchmark v1.4 Level 1 1.14](https://docs.aws.amazon.com/config/latest/developerguide/operational-best-practices-for-cis_aws_benchmark_level_1.html). ## Hardcoded passwords Avoid using demo users in production environments. For example, installer users are used in `UserInstallerPlugin`, which runs during a destructive deployment. ```php namespace Pyz\Zed\User; class UserConfig extends \Spryker\Zed\User\UserConfig { public function getInstallerUsers(): array { return [ [ 'firstName' => 'Admin', 'lastName' => 'Spryker', 'username' => 'admin@spryker.com', 'password' => 'change123', 'localeName' => 'de_DE', 'isAgent' => 1, ], // ... ]; } } ``` We recommend moving installer user config to Parameter Store before the release of production. For more information, see [Add variables in the Parameter Store](/docs/ca/dev/add-variables-in-the-parameter-store.html). Also, make sure to remove demo customers from the `customer.csv` data import for production environments. ## Encrypted communication Because HTTP is a textual protocol having no built-in encryption, passwords and customer personal data are transferred to shops in plain text. So, a good practice is to configure and implement transport layer security (TLS), which is widely known to most users as HTTPS. In most cases, it prevents eavesdropping on traffic of users in local public networks like free Wi-Fi hotspots. Besides, it can be used to authenticate users using third-party integrations by requiring a client certificate to be trusted. You can force HTTPS for the Storefront, Back Office, and Glue using the `Strict-Transport-Security` header: - `HttpConstants::ZED_HTTP_STRICT_TRANSPORT_SECURITY_ENABLED` - `HttpConstants::YVES_HTTP_STRICT_TRANSPORT_SECURITY_ENABLED` - `HttpConstants::ZED_HTTP_STRICT_TRANSPORT_SECURITY_CONFIG` - `HttpConstants::YVES_HTTP_STRICT_TRANSPORT_SECURITY_CONFIG` - `HttpConstants::GLUE_HTTP_STRICT_TRANSPORT_SECURITY_ENABLED` - `HttpConstants::GLUE_HTTP_STRICT_TRANSPORT_SECURITY_CONFIG` ## Access to the Back Office and Merchant Portal The Back Office and Merchant Portal applications serve as administration panels. So, we highly recommend adding an extra layer of security by introducing a VPN, IP whitelisting, or additional authentication. This ensures that only authorized users have access to them. ## Allowlisting IP addresses of third-party systems We highly recommend allowlisting the IP Addresses of third-party systems, such as ERP or WMS. To request allowlisting, provide the IP addresses or CIDR by [creating a support case](https://support.spryker.com) ## Security headers Security headers are directives used by web applications to configure security defenses in web browsers. Based on these directives, browsers can make it harder to exploit client-side vulnerabilities such as Cross-Site Scripting or Clickjacking. Headers can also be used to configure the browser to only allow valid TLS communication and enforce valid certificates, or even enforce using a specific server certificate. The following sections describe the configuration places for various security headers. You can change them on the project level. ### X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Content-Security-Policy #### Yves Default security headers are located in: `\Spryker\Yves\Application\ApplicationConfig::getSecurityHeaders()`. Default values: ```yml X-Content-Type-Options: nosniff X-Frame-Options: SAMEORIGIN X-XSS-Protection: 1; mode=block Content-Security-Policy: frame-ancestors 'self'; sandbox allow-downloads allow-forms allow-modals allow-pointer-lock allow-popups allow-popups-to-escape-sandbox allow-same-origin allow-scripts allow-top-navigation; base-uri 'self'; form-action 'self' ``` #### Zed Default security headers are located in: `\Spryker\Zed\Application\ApplicationConfig::getSecurityHeaders()`. Default values: ```yml X-Content-Type-Options: nosniff X-Frame-Options: SAMEORIGIN X-XSS-Protection: 1; mode=block Content-Security-Policy: frame-ancestors 'self' ``` #### Glue Default security headers are located in: `\Spryker\Glue\GlueApplication\GlueApplicationConfig::getSecurityHeaders()`. Default values: ```yml X-Content-Type-Options: nosniff X-Frame-Options: SAMEORIGIN X-XSS-Protection: 1; mode=block Content-Security-Policy: frame-ancestors 'self' ``` #### Glue Storefront Default security headers are located in: `\Spryker\Glue\GlueStorefrontApiApplication\GlueStorefrontApiApplicationConfig:::getSecurityHeaders()`. Default values: ```yml X-Content-Type-Options: nosniff X-Frame-Options: SAMEORIGIN X-XSS-Protection: 1; mode=block Content-Security-Policy: frame-ancestors 'self' ``` #### Glue Backend Default security headers are located in: `\Spryker\Glue\GlueBackendApiApplication\GlueBackendApiApplicationConfig::getSecurityHeaders()`. Default values: ```yml X-Content-Type-Options: nosniff X-Frame-Options: SAMEORIGIN X-XSS-Protection: 1; mode=block Content-Security-Policy: frame-ancestors 'self' ``` #### Cache-Control header You can set a custom `Cache-Control` header for the Storefront, Back Office, and Glue using the following plugins: - `Spryker\Zed\Http\Communication\Plugin\EventDispatcher\CacheControlHeaderEventDispatcherPlugin`: - Add the plugin into an application specific method for Zed using `\Pyz\Zed\EventDispatcher\EventDispatcherDependencyProvider::getEventDispatcherPlugins()` - Plugin configuration: `Spryker\Shared\Http\HttpConstants::ZED_HTTP_CACHE_CONTROL_CONFIG` - `Spryker\Yves\Http\Plugin\EventDispatcher\CacheControlHeaderEventDispatcherPlugin`: - Add the plugin into an application specific method for Yves using `\Pyz\Yves\EventDispatcher\EventDispatcherDependencyProvider::getEventDispatcherPlugins()` - Plugin configuration: `Spryker\Shared\Http\HttpConstants::YVES_HTTP_CACHE_CONTROL_CONFIG` - `Spryker\Glue\Http\Plugin\EventDispatcher\CacheControlHeaderEventDispatcherPlugin` - Add the plugin into an application specific method for Glue using `\Pyz\Glue\EventDispatcher\EventDispatcherDependencyProvider::getEventDispatcherPlugins()` - Plugin configuration: `Spryker\Shared\Http\HttpConstants::GLUE_HTTP_CACHE_CONTROL_CONFIG` {% info_block warningBox "Never enable public caching globally" %} These values are applied to *every* response of the application—the plugins cannot exempt individual pages. Setting `'public' => true` with `'max-age'` makes the cart, checkout, and customer account pages cacheable, so browsers serve a stale cart and a CDN can serve one customer's cart to another customer. If you do not configure these keys, the applications keep the Symfony default `Cache-Control: no-cache, private`, which is safe. {% endinfo_block %} ## Session security and hijacking Websites include many third-party JavaScript libraries that can access the content of a page. - To prevent access to session cookies from Javascript, the HttpOnly attribute of the session cookie is set by default. We recommend setting this attribute for all sensitive cookies. - When using TLS, you can use a `secure` cookie flag to instruct a browser to send this cookie back to the server only via an encrypted connection. To configure it, use the `*_SESSION_COOKIE_SECURE` configuration keys. - To prevent session fixation, session identifier is refreshed on login and logout events. We recommend implementing the same behavior for other sensitive cookies if you use them in your shop. - Make sure that your web server configuration does not cut these flags from cookie headers. - Make sure that `*_SESSION_COOKIE_DOMAIN` matches only your domain to disallow a browser to send the cookie to another domain or subdomain. - Never send a session ID as a GET parameter of a URL, because the ID can be logged in logs or forwarded to external websites in HTTP Referer header. ## Cross-site request forgery (CSRF) CSRF forces a user to execute unwanted actions while being logged in and either click on a specially crafted link or just embed the URL into some HTML tags triggering the request automatically—for example, the `src` attribute of `img`. To prevent such attacks, Symfony Form provides the `csrf_protection` token by default. We recommend using it in all forms. ## Cross-site scripting (XSS) Cross-site scripting is a possibility to inject malicious scripts to be executed in the browser context, for example, for a logged-in user to scrape information from the page or steal cookies. To prevent such vulnerabilities, developers should filter input and sanitize output to prevent rendering HTML or JS code from user input. Twig template engine has autoescaping enabled by default, so make sure to not use a `raw` filter. HTML should be stripped from user input. Usually, shop operators are trusted to enter raw HTML. Because you can't limit them in this case, we recommend restricting access to the Back Office and other administrative panels in your shop. For example, introduce a VPN, IP whitelisting, or additional authentication. Additionally, you can set [X-XSS-Protection](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection) using `HeadersSecurityEventDispatcherPlugin`. ## Security between the Storefront and the Back Office The Storefront uses HTTP RPC calls to communicate with the Back Office. Secure these calls by enabling Back Office authorization for Storefront requests: - Set `ZedRequestConstants::AUTH_ZED_ENABLED` and `AuthConstants::AUTH_ZED_ENABLED` to true. - Set a random value of `AuthConstants::AUTH_DEFAULT_CREDENTIALS[‘zed_request’][‘token’]` for each environment. - Optional: Change the username used by Storefront in `UserConstants::USER_SYSTEM_USERS`. ## Remote code execution Avoid triggering remote code execution as follows: - Local file inclusion: using unsanitized paths in `include` statements. To limit locations of files to be included, use the `include_path` PHP configuration option. - Remote file inclusion: avoid using unsanitized URLs or user input in `include` statements. - Unsafe deserialization. Serialized data should not be sent to the browser and should not be accepted back by the server. During deserialization of serialized data, PHP might instantiate classes mentioned in the payload and invoke some actions. Avoid this behavior or implement signature verification methods to validate this input. - Command injection: avoid forwarding user input to `exec`, `system`, `passthru`, or similar functions. ## SQL injection SQL injections are happening when unsanitized user input is embedded into an SQL statement. Use the following mechanisms to prevent SQL injections: - Propel to build queries and avoid plain SQL. - Prepared statements (used by Propel by default) and typed placeholders. - Casting incoming data to concrete data types like integer or string. - The `CastId` method in Zed controllers. ## Clickjacking Clickjacking is when UI tweaked to force users to click on specific buttons or links. To prevent clickjacking, set correct headers in `X-Frame-Options` and `Content-Security-Policy` provided by `HeadersSecurityEventDispatcherPlugin`. Make sure that the headers are not deleted by webserver configuration. For more information about clickjacking, see the [OWASP](https://owasp.org/www-community/attacks/Clickjacking) article. ## Obsolete or outdated dependencies To make sure that all the security updates are installed, keep Spryker and third-party modules up to date. For upgradability guidelines, see [Keeping a project upgradable](/docs/dg/dev/guidelines/keeping-a-project-upgradable/keeping-a-project-upgradable.html). ## Packages security vulnerabilities To be up-to-speed with the security vulnerabilities, we recommend doing the following: - Check if Spryker packages have known vulnerabilities. We recommend checking [security release notes](https://docs.spryker.com/docs/scos/user/intro-to-spryker/releases/release-notes/release-notes.html) under every release. - Verify whether `composer` packages have known vulnerabilities. You can use the `./vendor/bin/console security:check` command to inspect third-party vulnerabilities. - Verify whether `npm` packages have known vulnerabilities. You can use `npm audit` command to inspect third-party vulnerabilities. ## Exceptions and debug mode Make sure that, in your production environment, the debugging mode is disabled, and exceptions are not shown. Debug mode is configured with the following: - `ApplicationConstants::ENABLE_APPLICATION_DEBUG` - `ShopApplicationConstants::ENABLE_APPLICATION_DEBUG` - `GlueApplicationConstants::GLUE_APPLICATION_REST_DEBUG` ## Demo data *Remove all the demo data from the environment*. A project should only use the real data that will be used after going live. Remove all the demo data that comes with Spryker, which includes demo and admin users. Demo admin users in a live shop pose a significant security risk for your project. Also, make sure to set strong passwords when creating new admin users. ## OAuth configuration We recommend using environment variables to define security configuration. Example: ```php $config[OauthConstants::PRIVATE_KEY_PATH] = getenv('SPRYKER_OAUTH_KEY_PRIVATE'); $config[OauthConstants::PUBLIC_KEY_PATH] = $config[OauthCryptographyConstants::PUBLIC_KEY_PATH] = getenv('SPRYKER_OAUTH_KEY_PUBLIC'); $config[OauthConstants::ENCRYPTION_KEY] = getenv('SPRYKER_OAUTH_ENCRYPTION_KEY') ?: null; $config[OauthConstants::OAUTH_CLIENT_CONFIGURATION] = json_decode(getenv('SPRYKER_OAUTH_CLIENT_CONFIGURATION'), true) ?: []; ``` ## ACL configuration Set up the ACL configuration according to your requirements and restrict access to sensitive data. For more information, see [ACL configuration](/docs/pbc/all/merchant-management/{{site.version}}/marketplace/marketplace-merchant-portal-core-feature-overview/persistence-acl-configuration.html). ## Backend GATEWAY protection Gateway is used for communication between the frontend and the backend. In most cases, it doesn't expect any communication from the internet. To protect this endpoint, you need to extend `deploy.{project}-{env}.yml` as follows: 1. Add backend auths: ```yaml x-backend-auth: &backend-auth <<: *real-ip auth: engine: whitelist include: - 128.01.01.01/32 #YVES/GLUE storefront IP, need to be requested from support ``` 2. Add this auth to gateway endpoints: ```yaml backgw: application: backend-gateway endpoints: {some-domain}.com: store: DE <<: *backend-auth # add this row to your gateway config primal: true ``` To verify the configuration, redeploy the environment and make sure that accessing the domain returns a 403 error, but ZED requests are going through. ## Summary To sum up, the main points to keep the data secure are the following: - Educate: Learn and spread [OWASP guidelines](https://owasp.org/www-pdf-archive/OWASP_SCP_Quick_Reference_Guide_v2.pdf) in your team. - Check the presence of security-related HTTP headers. - Check cookie settings. - Configure TLS. - Secure the Back Office. - Check the Spryker configuration and change default authentication parameters like users and passwords. - Protect your Backend GATEWAY from direct access. - Keep systems and applications up to date. - Make sure that exceptions are not shown and debug mode is disabled on production. - Make sure that the keys data is taken from secure environment variables and is not embedded into the configuration files.

OpenTelemetry instrumentation

Tue, 28 Jul 2026 09:46:01 +0000

This document describes how to configure and instrument application for OpenTelemetry (OTel). It contains a brief overview of basic OTel concepts, but reading [OpenTelemetry documentation](https://opentelemetry.io/docs/concepts/) first is recommended. ## Convention The current implementation version (1.20.0) follows [OpenTelemetry Semantic Conventions 1.38.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.38.0/docs/README.md). ## Trace A trace represents a single transaction. It has a unique ID and all spans are related to it. Each trace has a name that is defined automatically or can be changed as described in [Integration](#integration). ## Span A span represents a unit of work or operation, similar to executing a single method. As the building blocks of traces, spans contain the following information: - Name - Parent span ID (empty for root spans) - Start and End Timestamps - Span Context - Attributes - Span Events - Span Links - Span Status ## Hook A hook is a function that executes a closure before and after method execution, providing a way to instrument code without modifying it directly. When you execute a method, a `pre` closure is executed and opens a span. After the method is executed, a `post` closure is executed and caught. Then, missing attributes are added and the span is closed. All hooks that are autogenerated or provided by a library, such as Propel or key-value store (Redis or Valkey) hooks provided by Spryker, are registered automatically. If you want to register a hook for a class, make sure the registration is executed before the method you want to instrument is called.

Hook example

```php tracer() ->spanBuilder('ModuleName-MyClass::methodName')//Span name can be not unique, but it would easier to make it such if you want to find it easily. ->setParent($context)//Here parent span is attached to the current span. ->setAttribute(\OpenTelemetry\SemConv\TraceAttributes::CODE_FUNCTION, $function)//You can attach almost everything as a param as long as the value is scalar. Null value means that attribute will be omitted. ->setAttribute(\OpenTelemetry\SemConv\TraceAttributes::CODE_NAMESPACE, $class) ->setAttribute(\OpenTelemetry\SemConv\TraceAttributes::CODE_FILEPATH, $filename) ->setAttribute(\OpenTelemetry\SemConv\TraceAttributes::CODE_LINENO, $lineno) ->startSpan(); //Here span is attached to the global context \OpenTelemetry\Context\Context::storage()->attach($span->storeInContext($context)); }, post: static function ( $instance, array $params, $returnValue, //Result of the method execution. ?\Throwable $exception //Exception if one was thrown during the execution ) { $scope = \OpenTelemetry\Context\Context::storage()->scope(); if (null === $scope) { return; } //Here you can just check the $exception value. But in some cases you might want to take if from other places. E.g. if method that thrown exception was not instrumented, parent span should still have it. $error = error_get_last(); if (is_array($error) && in_array($error['type'], [E_ERROR, E_CORE_ERROR, E_COMPILE_ERROR, E_PARSE], true)) { $exception = new \Exception( 'Error: ' . $error['message'] . ' in ' . $error['file'] . ' on line ' . $error['line'] ); } $scope->detach(); $span = \Spryker\Service\Opentelemetry\Instrumentation\Span\Span::fromContext($scope->context()); if ($exception !== null) { $span->recordException($exception);//Exception will be attached as an event into the span. $span->setAttribute('error_message', $exception->getMessage()); $span->setAttribute('error_code', $exception->getCode()); } //Status code adds some visibility. Error status code will mark your span as a one with an error for easier navigation. $span->setStatus($exception !== null ? \OpenTelemetry\API\Trace\StatusCode::STATUS_ERROR : \OpenTelemetry\API\Trace\StatusCode::STATUS_OK); //Span ends and sent into a span processor to be validated and prepared for exporting. $span->end(); } ); ```

## Collector Collector collects traces and sends them to a monitoring platform. Traces are sent to collector after that request is sent so it doesn't affect response time. Collector operates separately from the application and should be set up by a Cloud engineer or you can add one for you local setup yourself. ## Integration Run the latest version of the script from the [Installer repo](https://github.com/spryker/opentelemetry-installer/). If you want to integrate manually, the following sections describe all steps of the scripts. Be advised that Opentelemetry integration works with PHP 8.2 and above. if you are using older versions you must upgrade your PHP version first. ### Install required packages OTel provides instrumentation via packages that can be installed to register hooks automatically. If you want to instrument additional parts of an application, such as Symfony code, you can install respective packages from [Registry](https://opentelemetry.io/ecosystem/registry/?language=php) or other sources. {% info_block warningBox %} Install third-party packages at your own risk. {% endinfo_block %} The [spryker/opentelemetry](https://packagist.org/packages/spryker/opentelemetry) package covers the essential parts of the integration: - The entry point for instrumentation - Plugin to wire in your monitoring service - A console command to generate [hooks](https://opentelemetry.io/docs/zero-code/php/#how-it-works) for project's code, which creates spans automatically - Instrumentation of Propel, key-value store (Redis or Valkey), ElasticSearch, RabbitMQ, and Guzzle calls ### Optional: Install the Monitoring module The Monitoring module enables you to add custom attributes and events, change trace names during the request execution, and add exceptions to the root span for visibility. You can get the Monitoring module from the [Packagist](https://packagist.org/packages/spryker/monitoring). Install the module and wire the Monitoring plugin. ```php */ protected function getMonitoringExtensions(): array { return [ new OpentelemetryMonitoringExtensionPlugin(), ]; } } ``` You can call methods from Monitoring service, and they will be translated to OTel actions. Some methods act as placeholders because they're are not implemented in OTel–for example, `\Spryker\Service\Opentelemetry\Plugin\OpentelemetryMonitoringExtensionPlugin::markStartTransaction()`. ### Wire a console command Spryker is a large application, so manually creating all hooks is impractical. The `OpentelemetryGeneratorConsole` command automates hook generation for classes you want to cover with spans. ```php

Add and configure cronjobs

Tue, 28 Jul 2026 09:22:58 +0000

This document shows how to add and configure cronjobs in Jenkins.

We use Jenkins for cronjob scheduling. Compared to Crontab, there are several benefits:

Jobs are queued and can be manually executed.
Job definitions are under version control and can be changed by any developer.
Console output is available for debugging.

Add a new job and run it

Jobs are defined in config/Zed/cronjobs/jenkins.php.

This file contains an array defining the jobs.

// Send emails every 10 minutes
$jobs[] = [
    'name'                  => 'send-mails',
    'command'               => '$PHP_BIN vendor/bin/console mail:send-mail',
    'schedule'              => '*/10 * * * *',
    'enable'                => true,
    'stores'                => ['DE', 'FR'],
];

To import this configuration to Jenkins, run vendor/bin/console scheduler:setup. In a production environment, this is part of the default Normal deployment process.

When you remove jobs from config/Zed/cronjobs/jenkins.php, the application cannot detect the removal, so the removed jobs stay in Jenkins in their last state.

To stop them, do so manually or through a support request.

Cronjob configuration

For each job you can define several configurations:

KEY	TYPE	PURPOSE	✓
name	string	Name of the job.	yes
command	string	The console command that is executed.	yes
schedule	string	Expression that defines the job schedule (how often the job runs). The schedule string is compatible with the cronjob schedule definition—for example, `0 * * * *` means run once each hour at minute 00. If the environment is in development, return an empty string—on the development environment, cronjobs run manually only.	yes
enable	bool	Enable or disable jobs.	yes
stores	array	An array of stores where the job is executed.	yes

When you do not use Jenkins for job scheduling, there is no locking between concurrently running commands.

Vertex

Fri, 24 Jul 2026 10:10:26 +0000

![vertex-hero](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/tax-management/vertex/vertex.md/vertex-hero.png) The Spryker Vertex module, based on the *Vertex O Series*, performs automatic, near-real-time tax calculations at the point of purchase while accounting for the following: - Tax rates in each state, county, and city. - Laws, rules, and jurisdiction boundaries. - Special circumstances like tax holidays and product exemptions. For more information about how Vertex calculates taxes, see the [Vertex O Series website](https://www.vertexinc.com/solutions/products/vertex-indirect-tax-o-series). The Spryker Vertex module offers the following features that are worth considering when comparing it to the default Spryker [Tax Management capability](/docs/pbc/all/tax-management/latest/tax-management.html): - *Configure Vertex in Spryker*: Add your Vertex configurations, including your company code, in `config/Shared/config_default.php` to connect your Spryker project to Vertex. Alternatively, you can manage every Vertex setting from the Back Office, per global or store scope, and choose the tax provider with the **Taxes** > **Tax Provider** switch. For details, see [Configure Vertex in the Back Office](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/configure-vertex-in-the-back-office.html). - *Tax determination and calculation*: View tax estimates during checkout and calculated taxes before generating an invoice. This feature works across all regions, including countries where taxes are included in the price. - *Discounts Support*: The Vertex module uses both the discount and the amount paid by the customer, sending this information to Vertex for tax calculation and estimation. - *Manage tax exemptions*: Configure your project to exclude tax-exempt customers using the Vertex module. - *View invoice reports in Vertex dashboard*: The Vertex module allows customers to send invoice reports for paid orders from Spryker to Vertex. Customers can opt out of sending invoices to Spryker if they choose. - *Support for refunds*: When order items are returned, refunded, or a paid order is canceled, the Vertex module updates the tax report in Vertex for accurate reporting and compliance. - *Failover Solution*: Store owners and marketplace operators can manage refunds and ensure accurate tax reporting even during downtime. - *Supported Product Types*: The integration currently supports tax calculation only for items/products created using Spryker Product capabilities. - *Application of custom tax rules to products*: You can implement custom tax rules to accommodate unique product categorizations or specific tax regulations that apply to your business. The Vertex Integration provides a means for taxes to be calculated using these rules. ## Supported Use Cases and Business Models 1. Tax Calculation in Regions where taxes are excluded from prices. For example, in the US and Canada. 2. Tax Calculation in Regions where taxes are included in the price. For example, in the EU. 3. Marketplace: Every line item sent from Spryker to Vertex includes the customer's shipping address and the merchant's warehouse address, which Vertex uses for tax calculation. 4. Support for Delivery Terms: Vertex allows customers to set delivery terms within their dashboard, which are used in tax calculation. This is especially important for cross-border transactions when the seller wants to use the customer's location to determine the applicable tax rate. 5. Inclusion of Shipping Tax in the Total Tax Calculated: Spryker sends the selected shipping method to Vertex. The `delivery-method-key` set in Spryker is used for this purpose. Projects must ensure this is mapped correctly inside the Vertex dashboard by following the steps below: - In Vertex you create a Taxability Driver with the same value from Spryker - In Vertex you create a Taxability Mapping for the driver to one of Vertex's defined Delivery Charges The following diagram demonstrates the flow of the Vertex integration: ![vertex-flow](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/tax-management/vertex/vertex.md/vertex-flow.png) ## How Vertex calculates taxes for different countries The Vertex module calculates taxes based on the tax rules and rates of the country where the product is shipped. The Vertex app uses the shipping address to determine the tax rate. In some cases, the Vertex module can't calculate taxes and returns a 0 tax rate. For example, when a seller is located in EU, and the buyer is located in the US. So, make sure your project has a logic for such cases. For example, when a buyer selects a shipping address different from the project's default tax region or country, a warehouse address in the respective region needs to be used. ## Product Class Code The Product Class Code is used to represent groups or categories of products or services with identical taxability. By default, Spryker Product SKU is sent as `LineItems[].product.value` and `LineItems.lineItemId`. The Vertex module does not create any Vertex Tax Categories. ### Item Flexible Fields Item Flexible Fields are optional fields provided by a project. They are needed for the customization of tax calculation. Flexible Fields are supported by the Vertex module, and whether or not to use them is a business decision. ## Freight tax for shipment Spryker doesn't support freight shipment in terms of big packaging support; but calculation of taxes for shipping prices is supported. ## Sending invoices to Vertex through OMS The Spryker OMS transition command is used as an execution point to send a full order with all existing and custom fields provided by the project. The results will be visible in the Invoice Tax Details report. ## Next steps [Integrate Vertex](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/integrate-vertex.html)

Integrate Vertex

Fri, 24 Jul 2026 10:10:26 +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 {% info_block infoBox "Manage settings in the Back Office" %} Instead of environment variables, you can manage every Vertex setting from the Back Office **Configuration**, per global or store scope, and choose the tax provider with a **Taxes** > **Tax Provider** switch. This is opt-in and backward compatible. For details, see [Configure Vertex in the Back Office](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/configure-vertex-in-the-back-office.html). If you decide so, skip this section. {% endinfo_block %} 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 {% info_block warningBox %} If you decided to use the Back Office Configuration, skip this section. {% endinfo_block %} 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(array $configurationScopeTransfers = []): bool { return true; } public function isInvoicingEnabled(array $configurationScopeTransfers = []): bool { return true; } } ``` ### Config methods The following methods must be overridden in `src/Pyz/Zed/Vertex/VertexConfig.php` to enable the respective features: | Method | Default | Description | |--------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `isTaxIdValidatorEnabled()` | `false` | Enables tax ID validation via [Vertex Validator](https://developer.vertexinc.com/vertex-e-commerce/docs/stand-alone-deployments). Requires `TAXAMO_API_URL` and `TAXAMO_TOKEN` to be set. | | `isTaxAssistEnabled()` | `false` | Enables the tax assist feature. Return Assisted Parameters in the response that will provide more details about the calculation. The logs can be checked in the Vertex Dashboard. | | `isInvoicingEnabled()` | `false` | Enables invoicing functionality. Requires OMS plugins to be registered. See [Register OMS plugins](#register-oms-plugins). | | `getSellerCountryCode()` | `''` | Overrides the default seller country code (2-letter ISO code, for example, `US`). Defaults to the first country of the store. | | `getCustomerCountryCode()` | `''` | Overrides the default customer country code (applied only when no customer billing address is provided). Defaults to the first country of the store. | ## 4. Set up the database schema Install the database schema: ```bash vendor/bin/console propel:install ``` ## 5. Generate transfer objects Generate transfer objects for the module: ```bash vendor/bin/console transfer:generate ``` ## 6. Import glossary data The module provides translation data for tax validation messages. **Option 1: Import using the module's configuration file** ```bash vendor/bin/console data:import --config=vendor/spryker-eco/vertex/data/import/vertex.yml ``` **Option 2: Copy file content and import individually** Copy content from `vendor/spryker-eco/vertex/data/import/*.csv` to the corresponding files in `data/import/common/common/`. Then run: ```bash vendor/bin/console data:import glossary ``` **Option 3: Add to the project's main import configuration** Add the import actions to your project's main data import configuration file and include them in your regular import pipeline. ## 7. Register plugins ### Register the tax calculation plugin Add the Vertex calculation plugin to `src/Pyz/Zed/Calculation/CalculationDependencyProvider.php`: ```php use SprykerEco\Zed\Vertex\Communication\Plugin\Calculation\VertexCalculationPlugin; protected function getQuoteCalculatorPluginStack(Container $container): array { return [ //... # Suggested plugins order is shown. new ItemDiscountAmountFullAggregatorPlugin(), # This plugin is replacing other tax calculation plugins in the stack and will use them as a fallback. # No other tax calculation plugins except for VertexCalculationPlugin should be present in the stack. new VertexCalculationPlugin(), new PriceToPayAggregatorPlugin(), //... ]; } protected function getOrderCalculatorPluginStack(Container $container): array { return [ //... # Suggested plugins order is shown. new ItemDiscountAmountFullAggregatorPlugin(), # This plugin is replacing other tax calculation plugins in the stack and will use them as a fallback. # No other tax calculation plugins except for VertexCalculationPlugin should be present in the stack. new VertexCalculationPlugin(), new PriceToPayAggregatorPlugin(), //... ]; } ``` #### Register Fallback Calculation Plugins Add order and quote Fallback Calculation Plugins to `src/Pyz/Zed/Vertex/VertexDependencyProvider.php`: ```php use Spryker\Zed\Calculation\Communication\Plugin\Calculator\ItemTaxAmountFullAggregatorPlugin; use Spryker\Zed\Calculation\Communication\Plugin\Calculator\PriceToPayAggregatorPlugin; use Spryker\Zed\Tax\Communication\Plugin\Calculator\TaxAmountAfterCancellationCalculatorPlugin; use Spryker\Zed\Tax\Communication\Plugin\Calculator\TaxAmountCalculatorPlugin; use Spryker\Zed\Tax\Communication\Plugin\Calculator\TaxRateAverageAggregatorPlugin; /** * {@inheritDoc} * * @return array<\Spryker\Zed\CalculationExtension\Dependency\Plugin\CalculationPluginInterface> */ protected function getFallbackQuoteCalculationPlugins(): array { return [ # These plugins will be called if Vertex configuration is missing or Vertex is disabled. # Please note that this list includes PriceToPayAggregatorPlugin - this plugin isn't a part of tax calculation logic but it's required by TaxRateAverageAggregatorPlugin. new TaxAmountCalculatorPlugin(), new ItemTaxAmountFullAggregatorPlugin(), new PriceToPayAggregatorPlugin(), new TaxRateAverageAggregatorPlugin(), ]; } /** * {@inheritDoc} * * @return array<\Spryker\Zed\CalculationExtension\Dependency\Plugin\CalculationPluginInterface> */ protected function getFallbackOrderCalculationPlugins(): array { return [ # These plugins will be called if Vertex configuration is missing or Vertex is disabled. # Please note that this list includes PriceToPayAggregatorPlugin - this plugin isn't a part of tax calculation logic but it's required by TaxAmountAfterCancellationCalculatorPlugin. new TaxAmountCalculatorPlugin(), new ItemTaxAmountFullAggregatorPlugin(), new PriceToPayAggregatorPlugin(), new TaxAmountAfterCancellationCalculatorPlugin(), ]; } ``` In general, `getFallbackQuoteCalculationPlugins()` and `getFallbackOrderCalculationPlugins()` methods should contain the tax calculation plugins, which are replaced by `VertexCalculationPlugin` in `\Pyz\Zed\Calculation\CalculationDependencyProvider`. The code snippet above is an example of such configuration based on the Spryker default tax calculation plugins. Tax calculation plugins moved: - from `getQuoteCalculatorPluginStack` method: `TaxAmountCalculatorPlugin`, `ItemTaxAmountFullAggregatorPlugin`, `PriceToPayAggregatorPlugin`, `TaxRateAverageAggregatorPlugin` - from `getOrderCalculatorPluginStack` method: `TaxAmountCalculatorPlugin`, `ItemTaxAmountFullAggregatorPlugin`, `PriceToPayAggregatorPlugin`, `TaxAmountAfterCancellationCalculatorPlugin` {% info_block infoBox "Fallback behavior" %} There are three different failure scenarios where `VertexCalculationPlugin` might need to use a fallback logic: 1. Vertex isn't connected: fallback plugins defined in `getFallbackQuoteCalculationPlugins()` and `getFallbackOrderCalculationPlugins()` will be used to calculate taxes. 2. Vertex is disabled: fallback plugins defined in `getFallbackQuoteCalculationPlugins()` and `getFallbackOrderCalculationPlugins()` will be used to calculate taxes. 3. Vertex is not responding or is responding with an error: tax value will be set to zero, and the customer will be able to proceed with the checkout. {% endinfo_block %} ### Register CalculableObject and order expander plugins Add order and CalculableObject expander plugins to `src/Pyz/Zed/Vertex/VertexDependencyProvider.php`. The proposed plugins are examples, you can select which ones to register based on your requirements or create custom ones if needed. ```php use SprykerEco\Zed\Vertex\Communication\Plugin\Order\OrderCustomerWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Order\OrderExpensesWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Order\OrderItemProductOptionWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Order\OrderItemWithVertexSpecificFieldsExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Quote\CalculableObjectCustomerWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Quote\CalculableObjectExpensesWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Quote\CalculableObjectItemProductOptionWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Quote\CalculableObjectItemWithVertexSpecificFieldsExpanderPlugin; protected function getCalculableObjectVertexExpanderPlugins(): array { return [ // ... other plugins new CalculableObjectCustomerWithVertexCodeExpanderPlugin(), new CalculableObjectExpensesWithVertexCodeExpanderPlugin(), new CalculableObjectItemProductOptionWithVertexCodeExpanderPlugin(), new CalculableObjectItemWithVertexSpecificFieldsExpanderPlugin(), ]; } protected function getOrderVertexExpanderPlugins(): array { return [ // ... other plugins new OrderCustomerWithVertexCodeExpanderPlugin(), new OrderExpensesWithVertexCodeExpanderPlugin(), new OrderItemProductOptionWithVertexCodeExpanderPlugin(), new OrderItemWithVertexSpecificFieldsExpanderPlugin(), ]; } ``` ## 8. Configure the Shop Application dependency provider Add the following code to `src/Pyz/Yves/ShopApplication/ShopApplicationDependencyProvider.php`: ```php namespace Pyz\Yves\ShopApplication; use SprykerShop\Yves\ShopApplication\ShopApplicationDependencyProvider as SprykerShopApplicationDependencyProvider; use SprykerShop\Yves\CartPage\Widget\CartSummaryHideTaxAmountWidget; class ShopApplicationDependencyProvider extends SprykerShopApplicationDependencyProvider { /** * @phpstan-return array> * * @return array */ protected function getGlobalWidgets(): array { return [ //... # This widget is replacing Spryker default tax display in cart summary page with text stating that tax amount will be calculated during checkout process. CartSummaryHideTaxAmountWidget::class, ]; } } ``` If you have custom Yves templates or make your own Frontend, add `CartSummaryHideTaxAmountWidget` to your template. The core template is located at `SprykerShop/Yves/CartPage/Theme/default/components/molecules/cart-summary/cart-summary.twig`. Here is an example with `CartSummaryHideTaxAmountWidget`: ```html {% raw %}

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

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

Integrate Vertex Validator

Fri, 24 Jul 2026 10:10:26 +0000

To integrate Vertex Validator, take the following steps. Registers the `POST /tax-id-validate` Glue REST API endpoint that validates a customer's Tax Identification Number (VAT ID) against a given country code via the Vertex Taxamo service. This is useful for B2B storefronts where customers must provide a valid VAT ID during checkout or address management to qualify for tax-exempt or reverse-charge transactions within the EU. ## 1. Install required modules ```bash composer require spryker-eco/vertex ``` ## 2. Add glossary keys 1. Add the following keys to your existing glossary file:

Click to view all glossary keys

```csv key,translation,locale vertex.tax-number-country-blocked,Dieses Land ist in den Einstellungen blockiert.,de_DE vertex.tax-number-validation-not-available,Die Steuernummer konnte nicht durch den Dienst überprüft werden.,de_DE vertex.tax-number-ignored,"Die Steuernummer wurde ignoriert, da Nummern für diese Region, dieses Land oder diesen Verkäufer blockiert wurden.",de_DE vertex.tax-number-syntax-valid,Das Format der Steuernummer ist korrekt. Es wurden jedoch keine weiteren Prüfungen durchgeführt.,de_DE vertex.tax-number-syntax-invalid,Das Format der Steuernummer ist ungültig.,de_DE vertex.tax-number-considered-valid-in-domestic-country,Die Steuernummer ist im Heimatland des Verkäufers gültig.,de_DE vertex.tax-number-valid-according-to-external-service,Die Steuernummer wurde erfolgreich bei der Steuerbehörde validiert.,de_DE vertex.tax-number-invalid-according-to-external-service,Die Steuernummer wurde bei der Steuerbehörde überprüft und ist ungültig.,de_DE vertex.tax-number-validation-requested-additional-interactions,"Die Steuerbehörde verlangt zusätzliche Informationen (z. B. CAPTCHA), um die Nummer zu validieren.",de_DE vertex.tax-number-service-temporarily-unavailable,Der Validierungsdienst ist vorübergehend nicht erreichbar.,de_DE vertex.tax-number-syntax-considered-valid-but-not-verified,"Das Format der Steuernummer ist korrekt, aber der Status konnte nicht bestätigt werden, da der externe Dienst nicht reagierte.",de_DE vertex.tax-number-country-blocked,This county is blocked in the settings.,en_US vertex.tax-number-validation-not-available,The service was not able to validate this number.,en_US vertex.tax-number-ignored,"The number is ignored because the settings have been changed to block numbers for this region, country or seller.",en_US vertex.tax-number-syntax-valid,"The syntax of the ID is valid. However, no further validations were done. In cases where a checksum is required, like for India, the ID is considered valid if the syntax is valid and the checksum is not configured.",en_US vertex.tax-number-syntax-invalid,The syntax of the ID is invalid.,en_US vertex.tax-number-considered-valid-in-domestic-country,The Tax ID is valid in the domestic country of the supplier.,en_US vertex.tax-number-valid-according-to-external-service,The Tax ID has been validated against the Tax Authority's database of Tax IDs and is valid.,en_US vertex.tax-number-invalid-according-to-external-service,The Tax ID has been validated against the Tax Authority's database of Tax IDs and is invalid.,en_US vertex.tax-number-validation-requested-additional-interactions,"The Tax Authority has requested additional parameters. For example, a country might require CAPTCHA validation and needs more information before they can validate the ID.",en_US vertex.tax-number-service-temporarily-unavailable,Could not connect to validation service due to temporary unavailability of the service.,en_US vertex.tax-number-syntax-considered-valid-but-not-verified,The Tax ID syntax is valid but the ID's status could not be verified by the external service. This occurs when the on-error settings is set to syntax-check and external service does not respond.,en_US vertex.invalid-request-data,Invalid request data.,en_US vertex.invalid-request-data,Ungültige Anfragedaten.,de_DE vertex.tax-app-disabled,Tax service is disabled.,en_US vertex.tax-app-disabled,Die Steueranwendung ist deaktiviert.,de_DE vertex.tax-validator-unavailable,Tax Validator API is unavailable.,en_US vertex.tax-validator-unavailable,Die Steuerprüfungs-API ist nicht verfügbar.,de_DE vertex.validator-api-inactive,Unable to connect to Vertex Validator API: vertex app or tax id validation is inactive.,en_US vertex.validator-api-inactive,Verbindung zur Vertex Validator API fehlgeschlagen: Die Vertex-Anwendung oder der Steuernummern-Prüfdienst ist nicht aktiv.,de_DE vertex.request-failed,Request to Vertex API failed.,en_US vertex.request-failed,Anfrage an die Vertex-API fehlgeschlagen.,de_DE vertex.invalid-credentials,Invalid credentials.,en_US vertex.invalid-credentials,Ungültige Anmeldeinformationen.,de_DE ```

2. Import the updated glossary: ```bash console data:import:glossary ``` ### 3. Register the Glue API plugin {% info_block infoBox "Optional" %} This step is required only if you want to expose tax validation via the REST API. {% endinfo_block %} Add the Glue plugin to `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`: ```php

Configure Vertex in the Back Office

Fri, 24 Jul 2026 10:10:26 +0000

This document describes how to manage Vertex settings from Back Office > Configuration and how to select the tax provider per scope store.

With this feature enabled, operators manage every Vertex setting from the Back Office, per global or store scope, instead of environment variables. A new Configuration > Taxes > Tax Provider switch chooses between the built-in Spryker tax calculation and Vertex. Save-time validation prevents leaving the integration in a broken state.

Backward compatible

This feature is opt-in and backward compatible. Until you enable it, Vertex keeps reading its configuration from environment variables, and nothing changes for existing integrations.

Prerequisites

Use spryker-eco/vertex version 1.5.0 or later.
Integrate Vertex into your Spryker shop.
Install the Configuration Management feature. The Vertex module depends on spryker/configuration-extension, but it does not require the spryker/configuration module that provides the Back Office UI and stores the values. If the Configuration Management feature is not installed yet, install it first. For details, see Install the Configuration Management feature.

1. Enable the configuration source

The configuration source is gated behind the isConfigurationModuleUsed() flag, which defaults to false (environment-based behavior). To read values from the Back Office instead, override the flag in src/Pyz/Shared/Vertex/VertexConfig.php to return true:

<?php

namespace Pyz\Shared\Vertex;

use SprykerEco\Shared\Vertex\VertexConfig as SprykerEcoVertexConfig;

class VertexConfig extends SprykerEcoVertexConfig
{
    public function isConfigurationModuleUsed(): bool
    {
        return true;
    }
}

When the flag is true, SprykerEco\Zed\Vertex\VertexConfig reads values using getModuleConfig instead of from the config/Shared/config_default.php constants.

2. Register the pre-save validation plugin

Register VertexTaxProviderPreSavePlugin in src/Pyz/Zed/Configuration/ConfigurationDependencyProvider.php to enable save-time validation:

<?php

namespace Pyz\Zed\Configuration;

use Spryker\Zed\Configuration\ConfigurationDependencyProvider as SprykerConfigurationDependencyProvider;
use SprykerEco\Zed\Vertex\Communication\Plugin\Configuration\VertexTaxProviderPreSavePlugin;

class ConfigurationDependencyProvider extends SprykerConfigurationDependencyProvider
{
    /**
     * @return array<\Spryker\Zed\ConfigurationExtension\Dependency\Plugin\ConfigurationValuePreSavePluginInterface>
     */
    protected function getConfigurationValuePreSavePlugins(): array
    {
        return [
            // ... other plugins
            new VertexTaxProviderPreSavePlugin(),
        ];
    }
}

3. Sync the configuration schema

Sync the configuration schema so the Vertex settings appear in the Back Office:

console configuration:sync

4. Manage Vertex settings in the Back Office

After the sync, the settings are available under Configuration in Integrations > Vertex. All settings are scoped to global and store by default.

Integrations > Vertex

Group	Label	Requirement
Configuration	Security URI	Required, URL-validated
Configuration	Transaction calls URI	Required, URL-validated
Configuration	Client ID	Required
Configuration	Client secret	Required
Configuration	Default taxpayer company code	Optional
Configuration	Vendor code	Optional
Configuration	Seller country code	Optional, 2-letter ISO code
Configuration	Customer country code	Optional, 2-letter ISO code
Tax ID validation (Taxamo)	Taxamo API URL	URL-validated
Tax ID validation (Taxamo)	Taxamo token
Invoicing	Submit Tax invoices to Vertex
Tax Assist	Enable Tax Assist in Vertex

Tax ID validation

The Taxamo API URL and token are stored but consumed only when the tax ID validator is enabled. For details, see Integrate Vertex Validator.

Taxes > Tax Provider

Label	Values
Tax provider	`spryker` (default) or `vertex`

Selecting vertex requires a complete Vertex configuration for that scope. This requirement is enforced at save time.

Configuration source and precedence

The active configuration source depends on the flag Spryker\Shared\Vertex\VertexConfig::isConfigurationModuleUsed() or its project-level value:

Flag off (default): getters read the legacy VERTEX:* environment values from config/Shared/config_default.php.
Flag on: getters resolve values per scope store from the spryker/configuration. Environment values from config/Shared/config_default.php is ignored.

Save-time validation

When you save a configuration, the following changes are blocked to prevent leaving the integration in a broken state:

Selecting Vertex while incomplete: you cannot switch the tax provider to Vertex if Vertex is not fully configured for that scope. The error lists the missing fields.
Breaking an active configuration: you cannot clear or remove a credential that would leave Vertex incomplete while Vertex is the selected provider for that scope. This applies to both edits and deletions.
Cross-scope breakage: a change to the global scope that would break any store that has Vertex selected and inherits the global values is blocked. The error names the affected store.
Invalid URLs: the Security URI, Transaction calls URI, and Taxamo API URL must be valid URLs, even when Vertex is not the selected provider.

Next steps

Verify Vertex connection

Spryker Documentation

AI Dev SDK Skills and Agents

Overview

How to invoke

Skills

Agents

Related

Claude Code Plugin

Overview

Prerequisites

Install the plugin from the marketplace

Set up AI tooling for your project

Capabilities

Skills

Subagents

Rules

Context file

Security release notes 202306.0

Security guidelines

OpenTelemetry instrumentation

Add and configure cronjobs

Add a new job and run it

Cronjob configuration

Vertex

Integrate Vertex

Integrate Vertex Validator

Configure Vertex in the Back Office

Prerequisites

1. Enable the configuration source

2. Register the pre-save validation plugin

3. Sync the configuration schema

4. Manage Vertex settings in the Back Office

Integrations > Vertex

Taxes > Tax Provider

Configuration source and precedence

Save-time validation

Next steps