Spryker documentation center. https://docs.spryker.com/ Mon, 16 Mar 2026 08:55:46 +0000 Jekyll v4.2.2  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. - *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:  ## 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) Mon, 16 Mar 2026 08:55:32 +0000 https://docs.spryker.com/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/vertex.html https://docs.spryker.com/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/vertex.html This document describes how to verify Vertex integration. ## Prerequisites - [Install Vertex](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/integrate-vertex.html). - Create an account with [Vertex](https://www.vertexinc.com/). If you need support getting a Vertex account, contact [support](https://support.spryker.com/) or your Customer Success Manager. - Optional: For Vertex Validator integration, create an account with [Vertex Validator](https://www.vertexinc.com/). ## Verify Vertex connection {% info_block warningBox "Test the configuration" %} To ensure accuracy and compliance with tax laws, we highly recommend thoroughly testing the Vertex integration. {% endinfo_block %} Once you've configured Vertex, the taxes are calculated in real time in the checkout. A message about this is displayed on the checkout page.  On the Storefront, the tax amount is displayed on the checkout summary page. In the Back Office, the taxes are displayed on the order details page. If you configured invoices to be saved in Vertex, you can view the taxes processed by Vertex as follows: 1. In the Vertex dashboard, go to **Reporting** > **Standard Reports**. 2. Click **Report Output**. 3. Next to the report you want to view the taxes for, click **Action**>**View report**.  4. On the invoice page, you can verify the invoice number that corresponds to the Spryker order number and the applicable country tax calculated by Vertex.  ## Verify Vertex Validator tax ID validation Validate a tax ID by sending a request to `/tax-id-validate` using Glue API. ### Request ```json { "data": { "type": "tax-id-validate", "attributes": { "countryCode": "**", "taxId": "*****" } } } ``` One of the following should be returned: Successful response: HTTP code: 200. ```json { "data": [], "links": [] } ``` Unsuccessful response: HTTP code: 400, 422. ```json { "errors": [ { "status": 400, "detail": "Wrong format of the tax number." } ] } ``` Mon, 16 Mar 2026 08:55:32 +0000 https://docs.spryker.com/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/verify-vertex-connection.html https://docs.spryker.com/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/verify-vertex-connection.html Spryker Cloud Commerce OS is an end-to-end solution for digital commerce. This document contains a business-level description of new features and improvements. For information about installing Spryker, see [Getting started guide](/docs/dg/dev/development-getting-started-guide.html). ## Self-Service Portal {% include badge.html type="new-product" %} Self-Service Portal is a comprehensive digital solution that empowers customers to manage their own experience. It unifies traditional commerce and after-sales interactions within a single, intuitive self-service platform.  ### Key capabilities - Self-service dashboard: A centralized hub for managing all asset-related data and interactions, offering permission-based access, enhanced visibility, and great operational efficiency - Asset management: Enables customers to organize, track, and access assets, such as physical or digital products - Services: Consolidates offline and online services into a unified ordering and management process - General inquiries: Streamlines how customers submit general questions or requests related to products and services - Claims: Simplifies the submission and resolution of warranty claims, refund requests, and order-related issues, improving service quality and reducing operational costs - Asset inquiries: Supports detailed inquiries about specific assets, such as technical specs or irregular behavior - File management: Offers secure, centralized file storage and sharing to enhance collaboration and ensure vital documents for the assets are always accessible ### Business benefits - Customer empowerment and convenience: Reduce support overhead by enabling customers to independently manage inquiries, assets, and services through an intuitive self-service interface - Operational efficiency: Centralize permission-based access to assets and files to streamline data management, improve accuracy, and reduce manual processes - Enhance customer satisfaction and loyalty: Increase satisfaction and retention by delivering faster resolutions and full transparency across all after-sales and service interactions ### Docs - [Self-Service Portal](/docs/pbc/all/self-service-portal/latest/self-service-portal) - [Install Self-Service Portal](/docs/pbc/all/self-service-portal/latest/install/install-self-service-portal) ## Order Amendment {% include badge.html type="feature" %} The Order Amendment feature enhances the shopping experience by enabling customers to add, update, and remove items from existing orders after placement. This brings flexibility and control to the post-purchase process: - Flexible price recalculation: Choose between retaining original prices, applying current catalog prices, or defining a custom strategy to suit your business logic. - Flexible stock recalculation: Allow order edits even if items are deactivated or out of stock by preserving original order stock. Quantity can be adjusted down or increased, up to the combined amount of reserved order stock and current catalog availability. - Seamless multi-cart experience: Customers can switch between editing an order and shopping in their active cart without losing progress. This functionality requires [multi-cart](/docs/pbc/all/cart-and-checkout/latest/base-shop/feature-overviews/multiple-carts-feature-overview). - Preserve original order reference: Maintain consistent tracking and reporting by keeping the original order reference. <figure class="video_container"> <video width="100%" height="auto" controls> <source src="https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/order-management-system/base-shop/order-amendment-feature-overview.md/Order_Amendment_Explained.mp4" type="video/mp4"> </video> </figure> ### Business benefits - Reduce cancellations by allowing post-checkout edits - Minimize manual customer service interventions ### Docs - [Order Amendment feature overview](/docs/pbc/all/order-management-system/latest/base-shop/order-amendment-feature-overview) - [Install the Order Amendment feature](/docs/pbc/all/order-management-system/latest/base-shop/install-and-upgrade/install-features/install-the-order-amendment-feature) ## Bulk product import in Merchant Portal {% include badge.html type="early-access" %} {% include badge.html type="feature" %} The Product Import feature in the Merchant Portal enables you to bulk upload products using a universal CSV format, streamlining workflows, reducing manual effort, and accelerating time-to-market.  ### Key capabilities - Import products, pricing, and stock in one go: Upload a single file to populate essential product data, minimizing repetitive tasks and improving data accuracy. - Simplified CSV structure: Use a clean, single-line format that supports fast onboarding and easy updates to large product catalogs. - Built-in import logs: Get immediate feedback with success and error logs to troubleshoot issues and ensure smooth uploads. ### Business benefits - Empower merchants with self-service tools - Launch and update product catalogs faster - Reduce data entry errors and manual rework ### Docs - [Install the Marketplace Merchant Portal Data Import feature](/docs/pbc/all/product-information-management/latest/marketplace/install-and-upgrade/install-features/install-the-merchant-portal-data-import-feature.html) - [Install the Marketplace Merchant Portal Product Data Import feature](/docs/pbc/all/product-information-management/latest/marketplace/install-and-upgrade/install-features/install-the-merchant-product-data-import-feature.html) ## Marketplace Discounts {% include badge.html type="improvement" %} The Marketplace Discounts enhancements introduce advanced targeting capabilities for Marketplace Operators, enabling promotions specific to individual merchants or product offers: - Merchant-specific discounts: Apply discounts exclusively to products from a specific merchant using merchant references in discount conditions. - Product offer-specific discounts: Target discounts at the product offer level for more granular promotions.  ### Business benefits - Strategic promotions: Gain full control to drive growth in specific segments, support underperforming merchants, or push high-priority inventory. - Merchant performance and retention: Equip your merchants with tools to run tailored promotions under your governance, helping them increase sales and stay competitive. ### Docs - [Install the Marketplace Merchant + Promotions & Discounts feature](/docs/pbc/all/merchant-management/latest/marketplace/install-and-upgrade/install-features/install-the-marketplace-merchant-promotions-and-discounts-feature) - [Install the Marketplace Product Offer + Promotions & Discounts feature](/docs/pbc/all/offer-management/latest/marketplace/install-and-upgrade/install-features/install-the-marketplace-product-offer-promotions-and-discounts-feature) ## Discount conditions for customer-related criteria {% include badge.html type="improvement" %} The latest discount condition enhancements introduce more precise control over customer-related promotion scenarios, enabling restrictions and targeting directly based on customer identity or behavior: - Maximum uses per customer: Limit how many times a logged-in customer can redeem a specific discount or voucher. Ideal for one-time offers, such as welcome codes, newsletter subscription rewards, or limited campaigns where repeated usage should be prevented. - Customer reference: Target a discount at a specific customer by assigning their unique customer reference. Useful for compensation vouchers, exclusive rewards, or customer-specific promotional scenarios.  ### Business benefits - Precision in customer targeting and control: Define exactly who can use a promotion and how often, enabling tailored experiences for first-time buyers, high-value customers, or compensation scenarios. - Increased promotion efficiency and ROI: Align discount usage with customer behavior and strategic goals, ensuring that promotions reach the right audience with the right frequency. ### Docs [Install the Customer Account Management + Promotions & Discounts feature](/docs/pbc/all/customer-relationship-management/latest/base-shop/install-and-upgrade/install-features/install-the-customer-account-management-promotions-and-discounts-feature) ## Back Office UX improvements {% include badge.html type="improvement" %} These updates make it easier to work with large data sets in the Back Office, especially across key areas like orders, products, and marketplace operations: - Advanced table filters with multi-select: Quickly narrow down results in views, such as Orders, Products, Product Offers, Merchants, and Discounts, using flexible, multi-select filters. - Search by product variant SKU: Find specific products faster by searching for concrete product SKUs in the Abstract Products list. - Measurement unit management: Back Office users can now manage measurement units, including the ability to add and maintain translations for each unit.  ### Business benefits - Operational speed and efficiency: Save time on routine tasks with faster filtering and improved search capabilities—allowing teams to process orders, manage catalogs and discounts, and support merchants more effectively. - Scalability in daily workflows: Handle high volumes of data with ease. The improved navigation and filtering ensure the Backoffice stays responsive and usable as your orders, product, and merchant base grows. ## Spryker Monitoring Integration {% include badge.html type="feature" %} Spryker Monitoring Integration integrates Spryker's monitoring data into your APM platform based on the Spryker's implementation of the OpenTelemetry framework. It enables you to unite Spryker's insights with your monitoring ecosystem, ensuring full visibility across eCommerce workflows, faster issue detection, and alignment with your monitoring best practices. ### Business benefits - Personalized application monitoring: Integrate Spryker into your monitoring platform for a tailored, customized monitoring experience. - Comprehensive tracing and health check metrics: Forward traces and health check metrics from both your application and Spryker services to enable precise performance analysis and faster anomaly detection - Consolidated monitoring: Consolidate all performance data in a singe monitoring platform, ensuring full visibility across your entire eCommerce workflow ### Docs [Spryker Monitoring Integration](/docs/ca/dev/monitoring/spryker-monitoring-integration/spryker-monitoring-integration.html) ## Configurable data exporter {% include badge.html type="feature" %} Configurable Data Exporter provides structured access to your operational data, built for flexibility, performance, and security. Export curated datasets on a scheduled basis to your own cloud storage without affecting production systems. Secure RDS-to-S3 transfers enable integration into your analytics stack, data lake, or ETL pipeline — whether for BI, ML, or advanced audits — all without added operational risk. ### Business benefits - Plug into any destination: Easily connect to your BI tools or data pipelines, from Snowflake to Looker or custom analytics platforms. - Scheduled and scalable: Automate your exports based on business cadence, ensuring consistency and performance as your data needs grow. - Governed and composable: Fine-grained control over data scope and structure means exports align with internal policies and evolving business questions. - Controlled access: Avoid direct querying of your production systems, protecting uptime while granting safe access to curated, business-critical datasets. ### Docs [Set up data export to S3](/docs/ca/dev/set-up-data-export-to-s3.html) ## Algolia as a global search {% include badge.html type="improvement" %} The Algolia ACP app is expanded to support search through content within CMS pages and PDF documents, on top of existing product catalog search. This upgrade significantly enriches the search experience, delivering more relevant and complete results. ### Business benefits - Improved user experience: Provides richer, more complete search results. - Increased content discoverability: Makes all types of information searchable. ### Docs [Algolia](/docs/pbc/all/search/latest/base-shop/third-party-integrations/algolia/algolia) [Integrate Algolia](/docs/pbc/all/search/latest/base-shop/third-party-integrations/algolia/integrate-algolia.html) ### Technical prerequisites [Install prerequisites and enable ACP](/docs/dg/dev/acp/install-prerequisites-and-enable-acp) ## Vertex Tax ID validator {% include badge.html type="feature" %} Simplify B2B invoicing and tax compliance checks with the updated Vertex ACP App. This release features direct, out-of-the-box integration of the Vertex Validator API into checkout. With Vertex Validator and Vertex ACP App, you can validate business tax IDs for syntax, validity, and location, reducing operational costs from incorrect invoices and ensuring accurate application of VAT. ### Business benefits - Automated tax ID validation during checkout or any part of the process thanks to the headless integration - Improved tax compliance through ID verification and accurate VAT application via company location data - Decreased operational costs thanks to minimized invoicing errors - Global validation in over 65 countries ### Docs [Integrate Vertex Validator](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/integrate-vertex-validator) ### Technical prerequisites - [Install prerequisites and enable ACP](/docs/dg/dev/acp/install-prerequisites-and-enable-acp) - [Install Vertex](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/integrate-vertex.html) ## Multi-Factor Authentication {% include badge.html type="improvement" %} Multi-Factor Authentication (MFA) adds an additional layer of protection by requiring users to verify their identity through multiple methods, such as a password and a one-time code sent to their email.  ### Key capabilities - An additional authentication layer for Storefront, Back Office, Merchant Portal, and API endpoints - Supports for custom authenticity validators, such as TOTP or Short Message - Ensures that an email address is validated before a user signs up or updates their email address ### Business benefits Improves the overall security of your project, as well as the security of each customer. ### Docs [Multi-Factor Authentication](/docs/pbc/all/multi-factor-authentication/latest/multi-factor-authentication) ## SEO Sitemap {% include badge.html type="improvement" %} The Sitemap feature generates XML sitemaps that improve SEO by helping search engines efficiently index your Storefront content. Generated sitemaps include products, categories, product sets, CMS pages, and merchant pages by default. You can configure other entities to be included on the project level. ### Business benefits Improved SEO ### Docs - [Sitemap feature overview](/docs/pbc/all/miscellaneous/latest/sitemap-feature-overview) - [Install the Sitemap feature](/docs/pbc/all/miscellaneous/latest/install-and-upgrade/install-features/install-the-sitemap-feature) ## Add to cart from images (AI-powered) {% include badge.html type="early-access" %} {% include badge.html type="feature" %} This feature enables customers to add products to cart by uploading images on the Quick Order page. Upload a PDF, image, photo of handwritten notes, or any other text mentioning products to add to cart. Based on the uploaded image, OpenAI detects matching products in your catalog and adds them to cart. A single image can contain multiple products, and they both will be added to cart. Customers need own OpenAI accounts to use this feature. <figure class="video_container"> <video width="100%" height="auto" controls> <source src="https://spryker.s3.eu-central-1.amazonaws.com/docs/About/all/releases/release-notes-202507.0.md/AI_Visual_Add_To_Cart.mp4" type="video/mp4"> </video> </figure> ### Business benefits - Enable more buying routes - Reduce friction in transactions for power users ## Accessibility improvements {% include badge.html type="improvement" %} Accessibility ensures inclusive experiences for all users in Back Office and B2B Storefront, enhancing usability and helping customers in compliance with the 2025 EU Accessibility Act: - Keyboard usage: Users with mobility impairments can navigate seamlessly without a mouse. - Distinguishable colors: Users can easily read and interact with content, even if they have visual impairments or color blindness. B2B Strorefront has a 100% Lighthouse score in Google Chrome:  ### Business benefits - Meeting regulatory requirements: reduced legal risks related to 2025 EU Accessibility Act - Inclusive user experience: Improves usability for all users, including those with disabilities - Broader market reach: Enables access for a wider audience, enhancing engagement and trust ### Docs - [Install Back Office accessibility improvements](/docs/pbc/all/back-office/latest/base-shop/install-and-upgrade/install-back-office-accessibility-improvements) - [Integrate accessibility improvements](/docs/dg/dev/integrate-and-configure/integrate-accessibility-improvements) ## Performance optimizations in cart and checkout {% include badge.html type="improvement" %} This release delivers major performance improvements to checkout, order placement, and large cart processing—ensuring a smooth and responsive experience during peak traffic and high order volumes: ### Key capabilities - Smarter order reference generation: Introduces a new random string algorithm for Sales Order References, enabling high-speed, database lock-free order placement. This approach supports faster checkouts and seamless scaling during peak demand. - Optimized support for large orders (50–100 items): key features, such as Cart, Checkout, Inventory, OMS, Discounts, Shipments, Product, and Merchant, have been fine-tuned to efficiently handle large orders. Internal benchmarks show up to 40% faster performance across Storefront, Glue API, and background OMS operations. - Improved cart page performance: The dynamic cart page now renders up to twice as fast, delivering a more responsive and seamless customer experience. ### Business benefits Smooth, efficient processing of large carts and orders, enhancing the checkout experience for both B2C and B2B customers. ### Docs - [Unique random order reference generator](/docs/pbc/all/order-management-system/latest/base-shop/unique-random-order-reference-generator) - To benefit from these improvements, make sure to update the recommended modules listed in [Performance Guidelines](/docs/dg/dev/guidelines/performance-guidelines/general-performance-guidelines.html#use-the-newest-modules) - Cart page performance is now improved. The new configuration is described in the [Cart installation guide](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-cart-feature#set-up-configuration) ## Valkey key-value store {% include badge.html type="improvement" %} Spryker is migrating its cache solution from Redis to Valkey, a high-performance, open-source in-memory data store, supported by AWS ElasticCache. This integration significantly enhances data processing capabilities, offering improved speed, scalability, and security. ### Business benefits - Accelerate performance: Leverage Valkey's advanced multi-threading for substantially higher throughput (up to 5x observed in tests for write operations) and more stable latencies, resulting in faster application response times, especially during peak traffic. - Enhance scalability and reliability: Benefit from Valkey's superior scaling capabilities and improved cluster failover mechanisms, ensuring your platform can robustly handle business growth and larger, more complex workloads. - Improve system efficiency: Utilize Valkey's optimized memory management for better resource utilization and overall system performance. - Future-proof your infrastructure: Redis reached its end-of-life version, so migrating to Valkey ensures ongoing security updates, a clear BSD 3-clause licensing model, and strong, long-term support backed by the Linux Foundation and major industry players. ### Docs [Use and configure Redis or Valkey as a key-value store](/docs/dg/dev/backend-development/client/use-and-configure-redis-or-valkey-as-a-key-value-store) ## Cache performance improvement: Data Compression {% include badge.html type="feature" %} Spryker is introducing seamless and efficient data compression in Valkey key-value store to enhance overall system performance and reduce latency. By minimizing the size of stored and transferred data without compromising speed, this feature optimizes data-intensive operations, leading to faster access times and more efficient use of network and storage resources. With intelligent compression levels tailored for performance, Spryker enables businesses to scale more effectively while maintaining rapid user experiences. ### Business benefits - Enhanced performance: Transparent compression in Valkey boosts application responsiveness by reducing storage overhead - Faster data transfer: Up to 50% reduction in data size leads to quicker transfers between database and Spryker applications - Reduced latency: Improved data retrieval speeds from Valkey ensure smoother, low-latency experiences for end users - Efficient compression: Uses fast compression algorithms that minimize text data without introducing performance overhead ### Docs [Advanced configuration for Redis compression](/docs/dg/dev/set-up-spryker-locally/key-value-store-configuration#advanced-configuration-for-redis-compression) ### Technical prerequisites [Use and configure Redis or Valkey as a key-value store](/docs/dg/dev/backend-development/client/use-and-configure-redis-or-valkey-as-a-key-value-store) ## Cloud self-service: Storage and access management {% include badge.html type="feature" %} Cloud Self Service is a new automated system for handling common customer support requests. This feature leverages internal tooling to process requests for IAM user creation, VPN and SSH access, and S3 bucket creation automatically, streamlining the support process and empowering customers with faster resolutions. ### Business benefits - Reduce lead times: Speed up development and operational tasks by having common requests fulfilled faster - Enhance request quality and consistency: Automated processing minimizes human error, ensuring that requests are handled accurately and consistently every time ## Cloud security improvements {% include badge.html type="improvement" %} This release introduces both internal and customer-facing enhancements, including Multi-Factor Authentication (MFA) and improved password policy, now enabled by default for all new and existing cloud users. All IAM users are now required to activate MFA and use more complex passwords by default. These measures significantly reduce the risk of credential exposure and prevent unauthorized access to your cloud environments. ### Business benefits - Enhanced account security: Multi-Factor authentication and stronger password policies safeguard your cloud environments against unauthorized access and credential misuse - Security best practices by default: Pre-configured security settings ensure a strong baseline without additional setup, making it easier to maintain a secure and resilient cloud setup ### Docs [Multi-factor authentication and passwords](/docs/ca/dev/security/multi-factor-authentication-and-passwords) ## Stable Workers {% include badge.html type="early-access" %} Introducing a significant enhancement to Publish and Synchronize (P&S) focused on increasing its job processing stability. While Jenkins continues to manage non-P&S tasks, P&S now uses a new Stable Worker Architecture. This redesign addresses stability challenges from its previous Jenkins-based execution, ensuring more reliable data synchronization (products, prices, assets), especially for large catalogs and frequent updates. The new architecture provides isolated worker contexts, automatic retries, and better error handling for a more robust P&S operation. ### Docs [Stable Workers](/docs/dg/dev/backend-development/cronjobs/stable-workers) ### Business benefits - Improved P&S performance and stability: Faster, more stable catalog data refreshes and timely frontend updates - Better handling of complex scenarios: Efficiently manage large, frequently updated catalogs - Reduced operational disruptions: Minimized downtime and manual P&S interventions due to enhanced resilience - Enhanced logging: Better visibility for logs (CloudWatch) for quicker resolution of P&S issues ## Support for GitHub Enterprise {% include badge.html type="feature" %} Spryker now offers native integration for GitHub Enterprise Server (GHES). This enhancement lets you directly connect your self-hosted GHES repositories with the Spryker platform, eliminating the previous requirement to mirror repositories. ### Business benefits - Simple, direct integration: Directly connect your GitHub Enterprise Server, removing the complexity and overhead of mirroring repositories - Streamlined workflows: Improved development and deployment workflows through a direct, native connection to your GHES infrastructure - Reduced operational overhead: Eliminate the need for maintaining and managing repository mirroring processes ## Improved autoscaling {% include badge.html type="improvement" %} Spryker Cloud Autoscaling has been enhanced with a faster reaction to traffic spikes. The measured improvement is up to five times faster to scale out from the time an event is observed. Aggressive scale out and scale-in better address temporary traffic surges–for example, during sales events–and improve the reliability of your shop. The improvements are already implemented with no action required from you. ### Business benefits - Improved reliability: Services scale five times faster - Improved end-user experience: No increase in request latency for users Mon, 16 Mar 2026 08:55:32 +0000 https://docs.spryker.com/docs/about/all/releases/release-notes-202507.0.html https://docs.spryker.com/docs/about/all/releases/release-notes-202507.0.html The Spryker Commerce OS is an end-to-end solution for digital commerce. This document contains a business-level description of new features and enhancements. For information about installing the Spryker Commerce OS, see [Getting started guide](/docs/dg/dev/development-getting-started-guide.html). ## <span class="inline-img"></span> Fulfillment App {% include badge.html type="feature" %} As part of Spryker's Unified Commerce capability, the Fulfillment App provides an all-new user interface designed to streamline your order fulfillment process. Supporting new business models and with enhanced functionalities, the Fulfillment App simplifies tasks for warehouse and store staff, offering an efficient and effective fulfillment process. The fulfillment App includes the following features: - New picking list concept: Compatible with many picking strategies to increase order fulfillment efficiency. - Warehouse allocation strategy: Optimize warehouse space utilization for your specific warehouse setup. - Offline mode: Ensure uninterrupted picking, even without an internet connection. - Backend API architecture: Better performance and improved scalability. - Powered by Spryker's Oryx Framework: Make rapid frontend customizations by utilizing a rich library of components. **Business benefits**: - Fulfill orders faster, easier, and smarter. - Rapidly customize and scale with a flexibly built app. ### Documentation [Fulfillment App overview](/docs/pbc/all/warehouse-management-system/latest/unified-commerce/fulfillment-app-overview.html) ## <span class="inline-img"></span> Click&Collect {% include badge.html type="feature" %} With Enhanced Click&Collect, your customers now have the flexibility to choose between delivery and pickup during checkout, enhancing their shopping experience. Store operators also benefit from advanced configuration capabilities for their in-store stock. Click&Collect includes the following features: - Service points: Service points broaden the scope of services you can offer at your physical locations beyond order collection. Its adaptable framework simplifies implementing features such as return services and appointment scheduling, allowing businesses to tailor solutions to their specific needs. - Integrated shipment types at checkout: Provide your customers with the flexibility to choose between delivery and pickup during checkout. With the flexible architecture of the Enhanced Click&Collect, you can create custom shipment types, like "Ship-from-Store", on the project level. - Works seamlessly with multi-address checkout: Lets your customers divide their orders for different delivery methods. For example, they can have some items delivered to their doorstep while they pick up other items at a location they select. - Merchant Portal integration: As a store operator, you can now do the following: - Specify product availability based on different service points: physical retail outlets, warehouses, or any other pickup location. - Adjust stock availability for each service point. - Offer varied pricing for items based on their pickup or delivery location.  **Business benefits**:<br> Enhanced Click&Collect facilitates immediate product availability, offering both B2B and B2C clients the convenience of bypassing wait times associated with shipping. This feature not only significantly reduces or eliminates shipping costs but also provides an opportunity for immediate product inspection, ensuring quality and specifications meet the client's standards. Moreover, it seamlessly blends the digital shopping experience with the tangible benefits of a physical store, fostering direct customer-business interactions and potentially driving additional in-store purchases. While pickup has its roots in B2C operations, its utility in B2B contexts is growing: - Automotive industry: Manufacturers and dealers can offer customers the convenience of ordering parts online with the option for on-site installation. - Manufacturing sector: Streamline operations by letting clients directly retrieve bulk orders from warehouses, enhancing the efficiency of the procurement process. ### Documentation [Service point management](/docs/pbc/all/service-point-management/latest/service-point-management.html) ## <span class="inline-img"></span> Data Exchange API {% include badge.html type="feature" %} Traditionally, developing APIs required technical expertise and time-consuming coding processes. However, with the new Spryker dynamic Data Exchange API infrastructure, we have removed the complexities, making it seamless for you to create APIs effortlessly. With this tool, you can quickly build, customize, and manage APIs tailored to your specific business requirements, all through an intuitive user interface. The key features of the Data Exchange API include the following: - No coding required: No complex coding and development efforts are needed. The user-friendly interface enables you to create APIs effortlessly. - Rapid API generation: The streamlined process lets you generate APIs in a matter of minutes. This helps you speed up your integration projects and get your applications up and running faster than before. - Flexibility and customization: You can tailor your API endpoints to your exact needs. You can define parameters, which allows for seamless compatibility with your systems. - Real-time updates: You can modify your API endpoints on the go. Our infrastructure allows you to make changes dynamically so you can adapt to evolving business needs without any downtime. **Business benefits**: - Reduce time-to-market, speeding up faster integration - Cost savings, especially on maintenance ### Documentation - [Data Exchange API](/docs/pbc/all/data-exchange/{{site.version}}/data-exchange.html) ### Technical prerequisites - [Install the Data Exchange API](/docs/pbc/all/data-exchange/latest/install-and-upgrade/install-the-data-exchange-api.html) [Install the Data Exchange API + Inventory Management feature](/docs/pbc/all/data-exchange/latest/install-and-upgrade/install-the-data-exchange-api-inventory-management-feature.html) ## <span class="inline-img"></span> Next Generation Middleware: Spryker Middleware powered by Alumio {% include badge.html type="feature" %} The Spryker Middleware powered by Alumio solves the main challenges of data integrations in a flexible and customizable way and, therefore, greatly reduces the efforts for Spryker's data exchange use cases. It is the foundation on which we build our Integration Apps. The Spryker Middleware powered by Alumio uses Alumio data integration technology. The Spryker Middleware powered by Alumio helps you to reach the following outcomes: - Lower the total cost of ownership, centralizing the management of data flows. - Lower return rate with more comprehensive & accurate product information. - Gain higher customer satisfaction by keeping consistent and up-to-date data across all touchpoints. - Gain higher conversion rate by reacting to customer demands and competitive challenges more quickly. **Business benefit**:<br> Faster time-to-value shortening setup times for integrations ### Technical prerequisites To connect Spryker Middleware powered by Alumio with Spryker Cloud Commerce OS, you need to install or deploy the [Data Exchange API feature](/docs/pbc/all/data-exchange/latest/install-and-upgrade/install-the-data-exchange-api.html) in your environment. ## <span class="inline-img"></span> Akeneo PIM Integration App {% include badge.html type="feature" %} Our Akeneo PIM Integration App simplifies the management of your product information by providing an out-of-the-box and highly flexible integration with the popular Akeneo PIM system. This saves you time and effort, allowing you to seamlessly manage your product information across all channels, resulting in a more efficient and effective sales process. The Spryker Akeneo PIM Integration App allows you to do the following: - Reduce time to market and set up a product data synchronization feed between Spryker and Akeneo PIM without any coding. - Easily adapt to any changes in your data model with intuitive, visual data mapping capabilities. - Increase the reliability of your data flow between Spryker and Akeneo PIM with buffering, retries, and extensive troubleshooting capabilities. **Business benefit**:<br> Reduce time-to-market with a flexible integration to Akeneo PIM, keeping new product information synchronized at the rhythm your business demands. ### Technical prerequisites - To use your Akeneo PIM Integration App, you need to have the Spryker Middleware powered by Alumio. - The Akeneo PIM Integration App works with B2C or B2B business models of Spryker Cloud Commerce. Currently, it doesn't cover the Marketplace business models. ## <span class="inline-img"></span> Log forwarding and metric streaming to Dynatrace {% include badge.html type="feature" %} {% info_block warningBox "Improved version of Dynatrace" %} We're going to release a refactored version of the Dynatrace integration. This version will be more robust and future-proof. For most projects, we recommend waiting for the new version. {% endinfo_block %} We are delighted to announce our newest integration - Dynatrace with Log Forwarding and Metrics Streaming from Spryker PaaS+! This integration is a key step in our journey to support more monitoring platforms compatible with Open Telemetry. This integration significantly enhances our current monitoring capabilities by extending the coverage of metrics and logs across crucial services such as Amazon ECS, RDS, OpenSearch Service, ElastiCache (Redis), PHP Exceptions, and RabbitMQ. Previously, the scope of these services was more limited, but with this enhancement, a broader and more precise range of metrics for tracking, debugging, and optimization is achieved. These monitoring improvements will also be available in New Relic and CloudWatch at no additional cost. This feature is ideal for customer DevOps/SREs seeking enhanced, flexible monitoring solutions. **Business benefits**:<br> Until now, New Relic was the sole option for aggregating logs and metrics. This integration offers customers the flexibility to connect and integrate their Dynatrace account to Spryker PaaS+, thus enhancing observability and cloud extensibility. Key features of this integration include the following: - Log forwarding: Facilitates forwarding of logs from Spryker Cloud services to Dynatrace, covering services like Amazon RDS, ECS, Redis, RabbitMQ, and OpenSearch. - Metric streaming: Streams performance metrics like CPU usage, memory, network latency, and error rates to Dynatrace, offering real-time insights. - Unified Observability Platform: Offers a centralized platform for all monitoring needs, compatible with various third-party platforms. - Efficient data processing: Ensures immediate forwarding of logs and metrics, with frequent data transmission for up-to-date monitoring. - Spryker support 24/7: Designed to work seamlessly with existing monitoring solutions, Spryker will keep watching over for you 24/7, regardless of the monitoring platform you use. - Scalability and adaptability: Can handle varying data volumes and peaks, with 24 hours of retention in case of unavailability. ### Technical prerequisites - Only available for Spryker Cloud customers. - You need a self-managed Dynatrace account, and you have to provide the necessary Endpoints to Spryker. ## <span class="inline-img"></span> Improved performance, stability, and scalability {% include badge.html type="improvement" %} Adding third-party integrations via apps to your existing SCCOS solution has become easier with the App Composition Platform (ACP). Get in touch with us to get ACP enabled faster and take advantage of ACP's steadily growing number of no and low-code apps. **Business benefit**:<br> Simplified and faster enablement of ACP for SCCOS, as well as improved scalability, performance, and data security of the entire platform. ### Documentation [ACP overview](/docs/acp/user/intro-to-acp/acp-overview.html) ### Technical prerequisites [Install the ACP catalog](/docs/dg/dev/acp/app-composition-platform-installation.html) ## <span class="inline-img"></span> Vertex app {% include badge.html type="feature" %} Staying up-to-date with ever-changing tax rules and rates can require a lot of resources. Spryker, through the Vertex integration, offers a means for businesses to automate tax calculation and centralize sales taxes on their transactions. **Business benefits**: - Comply with tax frameworks anywhere you do business. Let Vertex take care of tax management with a seamless and easy-to-use solution that meets the needs across Tax, IT, and Finance teams. - Free up valuable resources for other operations as it stays compliant and up to date with the tax regulations of your markets. - Automate tax processes and improve business agility by easily validating business tax at check-out and issuing tax-compliant invoices at the point of sale. ### Documentation [Vertex](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/vertex.html) ### Technical prerequisites - [Install ACP](/docs/acp/user/app-composition-platform-installation.html) - [Install Vertex](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/integrate-vertex.html) ## <span class="inline-img"></span> Algolia app {% include badge.html type="improvement" %} Build an efficient path to purchase for your buyers with Algolia search, an innovative search and navigation solution that empowers your customers to quickly find the products they want. With our powerful and flexible implementation, headless or with search components on your storefront, you can easily integrate search capabilities into your storefront, streamlining the customer journey and increasing conversions. **Business benefits**: - Easily bring search into your storefront with our implementation, headless or with frontend search components, and enable customers to get to what matters faster. - With the latest feature addition, you can now use the search components to display Algolia search results and support your users with search suggestions. ### Documentation [Algolia](/docs/pbc/all/search/latest/base-shop/third-party-integrations/algolia/algolia.html) ### Technical prerequisites [Integrate Algolia](/docs/pbc/all/search/latest/base-shop/third-party-integrations/algolia/integrate-algolia.html) ## <span class="inline-img"></span> Autointegration of code releases {% include badge.html type="improvement" %} In addition to updating Spryker packages in your repository, with this release, Spryker Code Upgrader starts integrating plugins, settinh configurations keys, and adding new translations and similar elements to your project code. Now engineers don't have to figure out and manually apply code changes to activate new features. **Business benefit**:<br> Reduce the engineering time needed to integrate a Spryker module release into your project. ### Documentation [Integrating code releases](/docs/ca/devscu/integrating-code-releases/integrating-code-releases.html) ### Technical prerequisites Connect to [Spryker Code Upgrader](/docs/ca/devscu/spryker-code-upgrader.html) service to receive security updates semi-automatically. ## <span class="inline-img"></span> Security upgrades {% include badge.html type="improvement" %} Receive security releases before any other releases offered by Spryker Code Upgrader. The Upgrader prioritizes security releases, ensuring a timely application of critical security fixes. **Business benefit**:<br> Reduce the security risks from running outdated software by taking security updates before other updates. ### Documentation [Integrating security releases](/docs/ca/devscu/integrating-code-releases/integrating-security-releases.html) ### Technical prerequisites Connect to [Spryker Code Upgrader](/docs/ca/devscu/spryker-code-upgrader.html) service to receive security updates semi-automatically. ## <span class="inline-img"></span> Upgradability Evaluator improvements {% include badge.html type="improvement" %} This update offers notifications about critical security issues and vulnerabilities in Spryker and third-party components based on known vulnerability databases from NPM and Composer ecosystems. These improvements enhance the security monitoring and upgrade process. This update is complementary to the [Security Upgrades] improvement for Spryker Code Upgrader, but addresses all Spryker users. **Business benefit**:<br> Better awareness of security issues and vulnerabilities. ### Documentation - [Handling upgrade warnings](/docs/ca/devscu/integrating-code-releases/handling-upgrade-warnings.html) - [Spryker security checker](/docs/dg/dev/guidelines/keeping-a-project-upgradable/upgradability-guidelines/spryker-security-checker.html) - [NPM checker](/docs/dg/dev/guidelines/keeping-a-project-upgradable/upgradability-guidelines/npm-checker.html) - [Open-source vulnerabilities checker](/docs/dg/dev/guidelines/keeping-a-project-upgradable/upgradability-guidelines/open-source-vulnerabilities.html) ### Technical prerequisites Install and run [Upgrader compliance Evaluator](/docs/dg/dev/guidelines/keeping-a-project-upgradable/run-the-evaluator-tool.html) to detect security issues. ## <span class="inline-img"></span> Oryx Framework {% include badge.html type="improvement" %} Oryx Framework empowers developers to efficiently build composable frontends. Oryx provides a rich library of Oryx components, including a design system, allowing developers to rapidly create modern and visually appealing user interfaces. These components integrate with Spryker APIs by default, providing a seamless, decoupled experience for developers and end consumers. **Business benefit**:<br> Save time and effort with Oryx Framework. Spryker's purpose-built framework lets developers utilize fast, lightweight, and reactive components for storefronts and other frontends that quickly and dynamically display various devices. ### Learn more [Oryx in 90 seconds videos](https://www.youtube.com/playlist?list=PLJooqCSo73Sj9r_632NRtr-O0zuY7eHPb) ### Documentation [Oryx](/docs/dg/dev/frontend-development/latest/oryx/oryx.html) ### Technical prerequisites Oryx can be installed on your local machine and requires a Node.js or a compatible Javascript runtime and an npm runtime. For installation instructions, see [Set up Oryx](/docs/dg/dev/frontend-development/latest/oryx/getting-started/set-up-oryx.html). ## <span class="inline-img"></span> Composable Storefront: Additional foundation features - EA (early access) {% include badge.html type="improvement" %} Additional features are being released for Spryker's new upgradeable, decoupled frontend solution — Composable Storefront. This set of features provides essential components for commonplace purchase journeys. Spryker Composable Storefront is built using Spryker's Oryx framework, a reactive, fast, and lightweight framework. For more information about this Early Access product, contact your Spryker representative. **Business benefit**:<br> Provides commonplace features out-of-the-box for future-proof, agile, scalable, and upgradeable solutions for digital commerce business models. ### Learn more Composable Storefront is part of the Oryx framework. Oryx provides the features, and the presets for the various applications that you can create with Oryx, such as a Composable Storefront or Fulfillment App. ### Documentation [Oryx](/docs/dg/dev/frontend-development/latest/oryx/oryx.html) ### Technical prerequisites Oryx can be installed on your local machine and requires a Node.js or a compatible Javascript runtime and an npm runtime. See Set up Oryx for more information on the installation. Mon, 16 Mar 2026 08:55:32 +0000 https://docs.spryker.com/docs/about/all/releases/release-notes-202311.0.html https://docs.spryker.com/docs/about/all/releases/release-notes-202311.0.html This document describes the project configuration to consider when using Vertex for tax calculation. ## Adding country-specific fields to the address form Make sure that, on the Storefront, the address form has the required fields for each country. For example, the US store should have the **State** field, and the CA store should have the **Province** field. ## Sending additional data to Vertex By default, the following data is sent to Vertex for tax calculation: - Customer Shipping address - Product SKU - Shipping(delivery) method key - Warehouse address that also includes the Merchant warehouse address for a Marketplace model - Product SKUs - Product prices - Discounts - Shipping costs You can send additional data to Vertex, like a Customer Exemption Certificate, using plugins and the `taxMetadata` fields. You can add more data to request any specific information that's not available in Spryker by default. For example, this could be data from ERP, other systems, and customized Spryker instances. For the implementation details, see [Configure Vertex-specific metadata](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/configure-vertex-specific-metadata.html#2-implement-vertex-specific-metadata-extender-plugins). ## Additional configuration options for Vertex - You can configure the Vertex app for invoices to be saved in Vertex. However, we recommend to send invoice requests only for paid orders, as specified in [Integrate Vertex](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/integrate-vertex.html#8-optional-sending-tax-invoices-to-vertex-and-handling-refunds). The current implementation works asynchronously, so no response is saved in Spryker. - The default Spryker functionality uses tax rates to manage taxes. When using Vertex for tax determination, Vertex doesn't provide any tax rates to Spryker. To avoid confusion, we recommend removing the default Spryker tax rates. In the Back Office, you can delete them in **Administration** > **Tax Rates**. ## Logging and tracking Vertex issues If the Vertex app is down or taxes can't be calculated for other reasons, taxes are displayed as 0, letting customers place orders. For some orders, taxes might actually be 0, so there is no way to identify if there is an issue with tax calculation. In future, there will be a flag to identify and track these issues. ## Next steps [Verify Vertex connection](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/verify-vertex-connection.html) Mon, 16 Mar 2026 08:55:32 +0000 https://docs.spryker.com/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/project-configuration-for-vertex.html https://docs.spryker.com/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/project-configuration-for-vertex.html This document describes how to integrate [Vertex](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/vertex.html) into a Spryker shop. ## Prerequisites Before integrating Vertex, ensure the following prerequisites are met: - Make sure that your deployment pipeline executes database migrations. ## 1. Install the module Install the Vertex module using Composer: ```bash composer require spryker-eco/vertex ``` ## 2. Configure the module Add the following configuration to `config/Shared/config_default.php`: ```php use SprykerEco\Shared\Vertex\VertexConstants; $config[VertexConstants::IS_ACTIVE] = getenv('VERTEX_IS_ACTIVE'); $config[VertexConstants::CLIENT_ID] = getenv('VERTEX_CLIENT_ID'); $config[VertexConstants::CLIENT_SECRET] = getenv('VERTEX_CLIENT_SECRET'); $config[VertexConstants::SECURITY_URI] = getenv('VERTEX_SECURITY_URI'); $config[VertexConstants::TRANSACTION_CALLS_URI] = getenv('VERTEX_TRANSACTION_CALLS_URI'); // Optional: Tax ID Validator (requires Vertex Validator, previously known as Taxamo, see https://developer.vertexinc.com/vertex-e-commerce/docs/stand-alone-deployments) $config[VertexConstants::TAXAMO_API_URL] = getenv('TAXAMO_API_URL'); $config[VertexConstants::TAXAMO_TOKEN] = getenv('TAXAMO_TOKEN'); // Optional: Vendor Code $config[VertexConstants::VENDOR_CODE] = ''; ``` ### Required configuration constants | Constant | Description | |----------|-------------| | `IS_ACTIVE` | Enables or disables Vertex tax calculation. | | `CLIENT_ID` | OAuth client ID for the Vertex API. | | `CLIENT_SECRET` | OAuth client secret for the Vertex API. | | `SECURITY_URI` | Vertex OAuth security endpoint. | | `TRANSACTION_CALLS_URI` | Vertex transaction calls endpoint. | ### Optional configuration constants | Constant | Description | |----------|--------------------------------------------------------------------------------------------------------------------------------------------| | `TAXAMO_API_URL` | Vertex Validator API URL for tax ID validation. [Details](https://developer.vertexinc.com/vertex-e-commerce/docs/stand-alone-deployments). | | `TAXAMO_TOKEN` | Vertex Validator API authentication token. | | `VENDOR_CODE` | Vendor code for Vertex tax calculations. | | `DEFAULT_TAXPAYER_COMPANY_CODE` | Default taxpayer company code. | ## 3. Override feature flags The `isTaxIdValidatorEnabled`, `isTaxAssistEnabled`, and `isInvoicingEnabled` methods default to `false` and are not driven by constants. To enable them, override `src/Pyz/Zed/Vertex/VertexConfig.php`: ```php namespace Pyz\Zed\Vertex; use SprykerEco\Zed\Vertex\VertexConfig as SprykerEcoVertexConfig; class VertexConfig extends SprykerEcoVertexConfig { public function isTaxIdValidatorEnabled(): bool { return true; } public function isTaxAssistEnabled(): bool { return true; } public function isInvoicingEnabled(): bool { return true; } } ``` ### Config methods The following methods must be overridden in `src/Pyz/Zed/Vertex/VertexConfig.php` to enable the respective features: | Method | Default | Description | |--------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `isTaxIdValidatorEnabled()` | `false` | Enables tax ID validation via [Vertex Validator](https://developer.vertexinc.com/vertex-e-commerce/docs/stand-alone-deployments). Requires `TAXAMO_API_URL` and `TAXAMO_TOKEN` to be set. | | `isTaxAssistEnabled()` | `false` | Enables the tax assist feature. Return Assisted Parameters in the response that will provide more details about the calculation. The logs can be checked in the Vertex Dashboard. | | `isInvoicingEnabled()` | `false` | Enables invoicing functionality. Requires OMS plugins to be registered. See [Register OMS plugins](#register-oms-plugins). | | `getSellerCountryCode()` | `''` | Overrides the default seller country code (2-letter ISO code, for example, `US`). Defaults to the first country of the store. | | `getCustomerCountryCode()` | `''` | Overrides the default customer country code (applied only when no customer billing address is provided). Defaults to the first country of the store. | ## 4. Set up the database schema Install the database schema: ```bash vendor/bin/console propel:install ``` ## 5. Generate transfer objects Generate transfer objects for the module: ```bash vendor/bin/console transfer:generate ``` ## 6. Register plugins ### Register the tax calculation plugin Add the Vertex calculation plugin to `src/Pyz/Zed/Calculation/CalculationDependencyProvider.php`: ```php use SprykerEco\Zed\Vertex\Communication\Plugin\Calculation\VertexCalculationPlugin; protected function getQuoteCalculatorPluginStack(Container $container): array { return [ //... # Suggested plugins order is shown. new ItemDiscountAmountFullAggregatorPlugin(), # This plugin is replacing other tax calculation plugins in the stack and will use them as a fallback. # No other tax calculation plugins except for VertexCalculationPlugin should be present in the stack. new VertexCalculationPlugin(), new PriceToPayAggregatorPlugin(), //... ]; } protected function getOrderCalculatorPluginStack(Container $container): array { return [ //... # Suggested plugins order is shown. new ItemDiscountAmountFullAggregatorPlugin(), # This plugin is replacing other tax calculation plugins in the stack and will use them as a fallback. # No other tax calculation plugins except for VertexCalculationPlugin should be present in the stack. new VertexCalculationPlugin(), new PriceToPayAggregatorPlugin(), //... ]; } ``` #### Register Fallback Calculation Plugins Add order and quote Fallback Calculation Plugins to `src/Pyz/Zed/Vertex/VertexDependencyProvider.php`: ```php use Spryker\Zed\Calculation\Communication\Plugin\Calculator\ItemTaxAmountFullAggregatorPlugin; use Spryker\Zed\Calculation\Communication\Plugin\Calculator\PriceToPayAggregatorPlugin; use Spryker\Zed\Tax\Communication\Plugin\Calculator\TaxAmountAfterCancellationCalculatorPlugin; use Spryker\Zed\Tax\Communication\Plugin\Calculator\TaxAmountCalculatorPlugin; use Spryker\Zed\Tax\Communication\Plugin\Calculator\TaxRateAverageAggregatorPlugin; /** * {@inheritDoc} * * @return array<\Spryker\Zed\CalculationExtension\Dependency\Plugin\CalculationPluginInterface> */ protected function getFallbackQuoteCalculationPlugins(): array { return [ # These plugins will be called if Vertex configuration is missing or Vertex is disabled. # Please note that this list includes PriceToPayAggregatorPlugin - this plugin isn't a part of tax calculation logic but it's required by TaxRateAverageAggregatorPlugin. new TaxAmountCalculatorPlugin(), new ItemTaxAmountFullAggregatorPlugin(), new PriceToPayAggregatorPlugin(), new TaxRateAverageAggregatorPlugin(), ]; } /** * {@inheritDoc} * * @return array<\Spryker\Zed\CalculationExtension\Dependency\Plugin\CalculationPluginInterface> */ protected function getFallbackOrderCalculationPlugins(): array { return [ # These plugins will be called if Vertex configuration is missing or Vertex is disabled. # Please note that this list includes PriceToPayAggregatorPlugin - this plugin isn't a part of tax calculation logic but it's required by TaxAmountAfterCancellationCalculatorPlugin. new TaxAmountCalculatorPlugin(), new ItemTaxAmountFullAggregatorPlugin(), new PriceToPayAggregatorPlugin(), new TaxAmountAfterCancellationCalculatorPlugin(), ]; } ``` In general, `getFallbackQuoteCalculationPlugins()` and `getFallbackOrderCalculationPlugins()` methods should contain the tax calculation plugins, which are replaced by `VertexCalculationPlugin` in `\Pyz\Zed\Calculation\CalculationDependencyProvider`. The code snippet above is an example of such configuration based on the Spryker default tax calculation plugins. Tax calculation plugins moved: - from `getQuoteCalculatorPluginStack` method: `TaxAmountCalculatorPlugin`, `ItemTaxAmountFullAggregatorPlugin`, `PriceToPayAggregatorPlugin`, `TaxRateAverageAggregatorPlugin` - from `getOrderCalculatorPluginStack` method: `TaxAmountCalculatorPlugin`, `ItemTaxAmountFullAggregatorPlugin`, `PriceToPayAggregatorPlugin`, `TaxAmountAfterCancellationCalculatorPlugin` {% info_block infoBox "Fallback behavior" %} There are three different failure scenarios where `VertexCalculationPlugin` might need to use a fallback logic: 1. Vertex isn't connected: fallback plugins defined in `getFallbackQuoteCalculationPlugins()` and `getFallbackOrderCalculationPlugins()` will be used to calculate taxes. 2. Vertex is disabled: fallback plugins defined in `getFallbackQuoteCalculationPlugins()` and `getFallbackOrderCalculationPlugins()` will be used to calculate taxes. 3. Vertex is not responding or is responding with an error: tax value will be set to zero, and the customer will be able to proceed with the checkout. {% endinfo_block %} ### Register CalculableObject and order expander plugins Add order and CalculableObject expander plugins to `src/Pyz/Zed/Vertex/VertexDependencyProvider.php`. The proposed plugins are examples, you can select which ones to register based on your requirements or create custom ones if needed. ```php use SprykerEco\Zed\Vertex\Communication\Plugin\Order\OrderCustomerWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Order\OrderExpensesWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Order\OrderItemProductOptionWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Order\OrderItemWithVertexSpecificFieldsExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Quote\CalculableObjectCustomerWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Quote\CalculableObjectExpensesWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Quote\CalculableObjectItemProductOptionWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Quote\CalculableObjectItemWithVertexSpecificFieldsExpanderPlugin; protected function getCalculableObjectVertexExpanderPlugins(): array { return [ // ... other plugins new CalculableObjectCustomerWithVertexCodeExpanderPlugin(), new CalculableObjectExpensesWithVertexCodeExpanderPlugin(), new CalculableObjectItemProductOptionWithVertexCodeExpanderPlugin(), new CalculableObjectItemWithVertexSpecificFieldsExpanderPlugin(), ]; } protected function getOrderVertexExpanderPlugins(): array { return [ // ... other plugins new OrderCustomerWithVertexCodeExpanderPlugin(), new OrderExpensesWithVertexCodeExpanderPlugin(), new OrderItemProductOptionWithVertexCodeExpanderPlugin(), new OrderItemWithVertexSpecificFieldsExpanderPlugin(), ]; } ``` ## 7. Configure the Shop Application dependency provider Add the following code to `src/Pyz/Yves/ShopApplication/ShopApplicationDependencyProvider.php`: ```php namespace Pyz\Yves\ShopApplication; use SprykerShop\Yves\ShopApplication\ShopApplicationDependencyProvider as SprykerShopApplicationDependencyProvider; use SprykerShop\Yves\CartPage\Widget\CartSummaryHideTaxAmountWidget; class ShopApplicationDependencyProvider extends SprykerShopApplicationDependencyProvider { /** * @phpstan-return array<class-string<\Spryker\Yves\Kernel\Widget\AbstractWidget>> * * @return array<string> */ 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 %} <li class="list__item spacing-y"> {{ 'cart.total.tax_total' | trans }} {% widget 'CartSummaryHideTaxAmountWidget' args [data.cart] only %} {% nowidget %} <span class="float-right">{{ data.cart.totals.taxTotal.amount | money(true, data.cart.currency.code) }}</span> {% endwidget %} </li> {% endraw %} ``` ## 8. Optional: Sending tax invoices to Vertex and handling refunds Configure payment `config/Zed/oms/{your_payment_oms}.xml`as in the following example: ```xml <?xml version="1.0"?> <statemachine xmlns="spryker:oms-01" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="spryker:oms-01 http://static.spryker.com/oms-01.xsd" > <process name="SomePaymentProcess" main="true"> <!-- other configurations --> <states> <!-- other states --> <state name="tax invoice submitted" reserved="true" display="oms.state.paid"/> <!-- other states --> </states> <transitions> <!-- other transitions --> <transition happy="true"> <source>paid</source> <!-- Suggested that paid transition should be the source, but it's up to you --> <target>tax invoice submitted</target> <event>submit tax invoice</event> </transition> <!-- other transitions --> <transition happy="true"> <source>tax invoice submitted</source> <!-- Here are the contents of the target transition --> </transition> <!-- other transitions --> </transitions> <events> <!-- other events --> <event name="submit tax invoice" onEnter="true" command="Vertex/SubmitPaymentTaxInvoice"/> <!-- other events --> </events> </process> </statemachine> ``` ### 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 step [Configure Vertex-specific metadata](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/configure-vertex-specific-metadata.html) Mon, 16 Mar 2026 08:55:32 +0000 https://docs.spryker.com/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/integrate-vertex.html https://docs.spryker.com/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/integrate-vertex.html 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: <details> <summary>Click to view all glossary keys</summary> ```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 ``` </details> 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 <?php namespace Pyz\Glue\GlueApplication; use Spryker\Glue\GlueApplication\GlueApplicationDependencyProvider as SprykerGlueApplicationDependencyProvider; use SprykerEco\Glue\Vertex\Plugin\VertexTaxValidateIdResourceRoutePlugin; class GlueApplicationDependencyProvider extends SprykerGlueApplicationDependencyProvider { protected function getResourceRoutePlugins(): array { return [ // ... other plugins new VertexTaxValidateIdResourceRoutePlugin(), ]; } } ``` ## 4. Use translations To use translations, send requests with the `Accept-Language` header. For example, to use German translations, include the `Accept-Language: de` header. ## Next step [Verify Vertex connection](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/verify-vertex-connection.html) Mon, 16 Mar 2026 08:55:32 +0000 https://docs.spryker.com/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/integrate-vertex-validator.html https://docs.spryker.com/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/integrate-vertex-validator.html <p>After you have <a href="/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/integrate-vertex.html">integrated Vertex module</a> for tax calculation, you can Configure Vertex-specific metadata.</p> <p>Spryker doesn’t have the same data model as Vertex, which is necessary for accurate tax calculations. Therefore, the integration requires project developers to add some missing information to the Quote object before sending a calculation request.</p> <p>The following diagram shows the data flow of the tax calculation request from the Spryker Cart to the Vertex API.</p> <p><img src="https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/tax-management/vertex/install-vertex/vertex-tax-calculation-requests.png" alt="tax-calculation-request" /></p> <p>To integrate Vertex, follow these steps.</p> <h2 id="configure-vertex-specific-metadata-transfers">1. Configure Vertex-specific metadata transfers</h2> <p>Define specific Vertex Tax metadata transfers and extend other transfers with them:</p> <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <span class="cp">&lt;?xml version="1.0"?&gt;</span> <span class="nt">&lt;transfers</span> <span class="na">xmlns=</span><span class="s">"spryker:transfer-01"</span> <span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span> <span class="na">xsi:schemaLocation=</span><span class="s">"spryker:transfer-01 http://static.spryker.com/transfer-01.xsd"</span><span class="nt">&gt;</span> <span class="c">&lt;!-- Calculable Object is extended with SaleTaxMetadata --&gt;</span> <span class="nt">&lt;transfer</span> <span class="na">name=</span><span class="s">"CalculableObject"</span><span class="nt">&gt;</span> <span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">"taxMetadata"</span> <span class="na">type=</span><span class="s">"SaleTaxMetadata"</span> <span class="na">strict=</span><span class="s">"true"</span><span class="nt">/&gt;</span> <span class="nt">&lt;/transfer&gt;</span> <span class="c">&lt;!-- Order is extended with SaleTaxMetadata --&gt;</span> <span class="nt">&lt;transfer</span> <span class="na">name=</span><span class="s">"Order"</span><span class="nt">&gt;</span> <span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">"taxMetadata"</span> <span class="na">type=</span><span class="s">"SaleTaxMetadata"</span> <span class="na">strict=</span><span class="s">"true"</span><span class="nt">/&gt;</span> <span class="nt">&lt;/transfer&gt;</span> <span class="c">&lt;!-- Expense is extended with ItemTaxMetadata --&gt;</span> <span class="nt">&lt;transfer</span> <span class="na">name=</span><span class="s">"Expense"</span><span class="nt">&gt;</span> <span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">"taxMetadata"</span> <span class="na">type=</span><span class="s">"ItemTaxMetadata"</span> <span class="na">strict=</span><span class="s">"true"</span><span class="nt">/&gt;</span> <span class="nt">&lt;/transfer&gt;</span> <span class="c">&lt;!-- Item is extended with ItemTaxMetadata --&gt;</span> <span class="nt">&lt;transfer</span> <span class="na">name=</span><span class="s">"Item"</span><span class="nt">&gt;</span> <span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">"taxMetadata"</span> <span class="na">type=</span><span class="s">"ItemTaxMetadata"</span> <span class="na">strict=</span><span class="s">"true"</span><span class="nt">/&gt;</span> <span class="nt">&lt;/transfer&gt;</span> <span class="c">&lt;!-- Product Option is extended with ItemTaxMetadata --&gt;</span> <span class="nt">&lt;transfer</span> <span class="na">name=</span><span class="s">"ProductOption"</span><span class="nt">&gt;</span> <span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">"taxMetadata"</span> <span class="na">type=</span><span class="s">"ItemTaxMetadata"</span> <span class="na">strict=</span><span class="s">"true"</span><span class="nt">/&gt;</span> <span class="nt">&lt;/transfer&gt;</span> <span class="c">&lt;!-- Sales Tax Metadata. It contains Vertex tax metadata which is related to Order or Quote in general. --&gt;</span> <span class="nt">&lt;transfer</span> <span class="na">name=</span><span class="s">"SaleTaxMetadata"</span> <span class="na">strict=</span><span class="s">"true"</span><span class="nt">&gt;</span> <span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">"seller"</span> <span class="na">type=</span><span class="s">"array"</span> <span class="na">associative=</span><span class="s">"true"</span> <span class="na">singular=</span><span class="s">"_"</span><span class="nt">/&gt;</span> <span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">"customer"</span> <span class="na">type=</span><span class="s">"array"</span> <span class="na">associative=</span><span class="s">"true"</span> <span class="na">singular=</span><span class="s">"_"</span><span class="nt">/&gt;</span> <span class="nt">&lt;/transfer&gt;</span> <span class="c">&lt;!-- Items Tax Metadata. It contains Vertex tax metadata which is related to Item.--&gt;</span> <span class="nt">&lt;transfer</span> <span class="na">name=</span><span class="s">"ItemTaxMetadata"</span> <span class="na">strict=</span><span class="s">"true"</span><span class="nt">&gt;</span> <span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">"product"</span> <span class="na">type=</span><span class="s">"array"</span> <span class="na">associative=</span><span class="s">"true"</span> <span class="na">singular=</span><span class="s">"_"</span><span class="nt">/&gt;</span> <span class="nt">&lt;property</span> <span class="na">name=</span><span class="s">"flexibleFields"</span> <span class="na">type=</span><span class="s">"array"</span> <span class="na">associative=</span><span class="s">"true"</span> <span class="na">singular=</span><span class="s">"_"</span><span class="nt">/&gt;</span> <span class="nt">&lt;/transfer&gt;</span> <span class="nt">&lt;/transfers&gt;</span> </code></pre></div></div> <p><code>SaleTaxMetadata</code> and <code>ItemTaxMetadata</code> are designed to be equal to the Vertex Tax Calculation API request body. You can extend them as you need, following the Vertex API structure.</p> <ul> <li> <p><code>SaleTaxMetadata</code> equals the Invoicing/Quotation request payload, excluding LineItems.</p> </li> <li> <p><code>ItemTaxMetadata</code> equals the Line Item API payload.</p> </li> </ul> <h2 id="implement-vertex-specific-metadata-extender-plugins">2. Implement Vertex-specific metadata extender plugins</h2> <p>You need to introduce several types of expander plugins. As a starting point, you use the examples provided the module. The plugins in this module are for development purposes. The data in the <code>TaxMetaData</code> fields needs to be collected from the project database or other sources, like an external ERP.</p> <h3 id="configure-the-customer-class-code-expander-plugins">Configure the Customer Class Code Expander plugins</h3> <ol> <li>Introduce <code>Pyz/Zed/{YourDesiredModule}/Communication/Plugin/Order/OrderCustomerWithVertexCodeExpanderPlugin.php</code> using the following example:</li> </ol> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Zed</span><span class="err">\</span><span class="p">{</span><span class="nc">YourDesiredModule</span><span class="p">}</span><span class="err">\</span><span class="nc">Communication\Plugin\Order</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Generated\Shared\Transfer\OrderTransfer</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\Kernel\Communication\AbstractPlugin</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">SprykerEco\Zed\Vertex\Dependency\Plugin\OrderVertexExpanderPluginInterface</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">OrderCustomerWithVertexCodeExpanderPlugin</span> <span class="kd">extends</span> <span class="nc">AbstractPlugin</span> <span class="kd">implements</span> <span class="nc">OrderVertexExpanderPluginInterface</span> <span class="p">{</span> <span class="cd">/** * @param \Generated\Shared\Transfer\OrderTransfer $orderTransfer * * @return \Generated\Shared\Transfer\OrderTransfer */</span> <span class="k">public</span> <span class="k">function</span> <span class="n">expand</span><span class="p">(</span><span class="kt">OrderTransfer</span> <span class="nv">$orderTransfer</span><span class="p">):</span> <span class="kt">OrderTransfer</span> <span class="p">{</span> <span class="nv">$orderTransfer</span><span class="o">-&gt;</span><span class="nf">getTaxMetadata</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">setCustomer</span><span class="p">([</span><span class="s1">'customerCode'</span> <span class="o">=&gt;</span> <span class="p">[</span><span class="s1">'classCode'</span> <span class="o">=&gt;</span> <span class="s1">'vertex-customer-code'</span><span class="p">]]);</span> <span class="k">return</span> <span class="nv">$orderTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <ol start="2"> <li>Introduce <code>Pyz/Zed/{YourDesiredModule}/Communication/Plugin/Quote/CalculableObjectCustomerWithVertexCodeExpanderPlugin.php</code> using the following example:</li> </ol> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?php</span> <span class="kn">namespace</span> <span class="nn">Spryker\Zed</span><span class="err">\</span><span class="p">{</span><span class="nc">YourDesiredModule</span><span class="p">}</span><span class="err">\</span><span class="nc">Communication\Plugin\Quote</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Generated\Shared\Transfer\CalculableObjectTransfer</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\Kernel\Communication\AbstractPlugin</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">SprykerEco\Zed\Vertex\Dependency\Plugin\CalculableObjectVertexExpanderPluginInterface</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">CalculableObjectCustomerWithVertexCodeExpanderPlugin</span> <span class="kd">extends</span> <span class="nc">AbstractPlugin</span> <span class="kd">implements</span> <span class="nc">CalculableObjectVertexExpanderPluginInterface</span> <span class="p">{</span> <span class="cd">/** * @param \Generated\Shared\Transfer\CalculableObjectTransfer $calculableObjectTransfer * * @return \Generated\Shared\Transfer\CalculableObjectTransfer */</span> <span class="k">public</span> <span class="k">function</span> <span class="n">expand</span><span class="p">(</span><span class="kt">CalculableObjectTransfer</span> <span class="nv">$calculableObjectTransfer</span><span class="p">):</span> <span class="kt">CalculableObjectTransfer</span> <span class="p">{</span> <span class="nv">$calculableObjectTransfer</span><span class="o">-&gt;</span><span class="nf">getTaxMetadata</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">setCustomer</span><span class="p">([</span><span class="s1">'customerCode'</span> <span class="o">=&gt;</span> <span class="p">[</span><span class="s1">'classCode'</span> <span class="o">=&gt;</span> <span class="s1">'vertex-customer-code'</span><span class="p">]]);</span> <span class="k">return</span> <span class="nv">$calculableObjectTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <h3 id="configure-the-customer-exemption-certificate-expander-plugins">Configure the Customer Exemption Certificate Expander plugins</h3> <p>Configure the following plugins using the provided example.</p> <table> <thead> <tr> <th>PLUGIN</th> <th>NAMESPACE</th> </tr> </thead> <tbody> <tr> <td>Customer Exemption Certificate Expander plugin for order</td> <td>Pyz/Zed/{YourDesiredModule}/Communication/Plugin/Order/OrderCustomerWithVertexExemptionCertificateExpanderPlugin.php</td> </tr> <tr> <td>Customer Exemption Certificate Expander plugin for quote</td> <td>Pyz/Zed/{YourDesiredModule}/Communication/Plugin/Quote/CalculableObjectCustomerWithVertexExemptionCertificateExpanderPlugin.php</td> </tr> </tbody> </table> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// ...</span> <span class="kd">class</span> <span class="nc">OrderCustomerWithVertexExemptionCertificateExpanderPlugin</span> <span class="kd">extends</span> <span class="nc">AbstractPlugin</span> <span class="kd">implements</span> <span class="nc">CalculableObjectVertexExpanderPluginInterface</span> <span class="p">{</span> <span class="cd">/** * @param \Generated\Shared\Transfer\CalculableObjectTransfer $calculableObjectTransfer * * @return \Generated\Shared\Transfer\CalculableObjectTransfer */</span> <span class="k">public</span> <span class="k">function</span> <span class="n">expand</span><span class="p">(</span><span class="kt">CalculableObjectTransfer</span> <span class="nv">$calculableObjectTransfer</span><span class="p">):</span> <span class="kt">CalculableObjectTransfer</span> <span class="p">{</span> <span class="nv">$calculableObjectTransfer</span><span class="o">-&gt;</span><span class="nf">getTaxMetadata</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">setCustomer</span><span class="p">([</span><span class="s1">'exemptionCertificate'</span> <span class="o">=&gt;</span> <span class="p">[</span><span class="s1">'exemptionCertificateNumber'</span> <span class="o">=&gt;</span> <span class="s1">'vertex-exemption-certificate-number'</span><span class="p">]]);</span> <span class="k">return</span> <span class="nv">$calculableObjectTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <h3 id="configure-the-product-class-code-expander-plugins">Configure the Product Class Code Expander plugins</h3> <p>Configure the following plugins using the provided example.</p> <table> <thead> <tr> <th>PLUGIN</th> <th>NAMESPACE</th> </tr> </thead> <tbody> <tr> <td>Product Class Code Expander plugin for order items</td> <td>Pyz/Zed/{YourDesiredModule}/Communication/Plugin/Order/OrderItemVertexProductClassCodeExpanderPlugin.php`</td> </tr> <tr> <td>Product Class Code Expander plugin for quote items</td> <td>Pyz/Zed/{YourDesiredModule}/Communication/Plugin/Quote/CalculableObjectItemWithVertexProductClassCodeExpanderPlugin.php</td> </tr> </tbody> </table> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// ...</span> <span class="kd">class</span> <span class="nc">ItemWithVertexClassCodeExpanderPlugin</span> <span class="kd">extends</span> <span class="nc">AbstractPlugin</span> <span class="kd">implements</span> <span class="nc">CalculableObjectVertexExpanderPluginInterface</span> <span class="p">{</span> <span class="cd">/** * @param \Generated\Shared\Transfer\CalculableObjectTransfer $calculableObjectTransfer * * @return \Generated\Shared\Transfer\CalculableObjectTransfer */</span> <span class="k">public</span> <span class="k">function</span> <span class="n">expand</span><span class="p">(</span><span class="kt">CalculableObjectTransfer</span> <span class="nv">$calculableObjectTransfer</span><span class="p">):</span> <span class="kt">CalculableObjectTransfer</span> <span class="p">{</span> <span class="k">foreach</span> <span class="p">(</span><span class="nv">$calculableObjectTransfer</span><span class="o">-&gt;</span><span class="nf">getItems</span><span class="p">()</span> <span class="k">as</span> <span class="nv">$itemTransfer</span><span class="p">)</span> <span class="p">{</span> <span class="nv">$itemTransfer</span><span class="o">-&gt;</span><span class="nf">getTaxMetadata</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">setProduct</span><span class="p">([</span><span class="s1">'productClass'</span> <span class="o">=&gt;</span> <span class="s1">'vertex-product-class-code'</span><span class="p">]);</span> <span class="p">}</span> <span class="k">return</span> <span class="nv">$calculableObjectTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <section class='info-block '><i class='info-block__icon icon-info'></i><div class='info-block__content'><div class="info-block__title">Use the same Product Class Code</div> <p>You must use the same Product Class Code extension for all product options and other order expenses. Vertex considers each of them as a separate item for tax calculation. For guidance on where to place them, see the definition of transfers in <a href="#configure-vertex-specific-metadata-transfers">Configure Vertex-specific Metadata Transfers</a>.</p> </div></section> <h3 id="configure-the-flexible-fields-extension">Configure the flexible fields extension</h3> <p>Configure the flexible files extension using the following example:</p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <span class="kd">class</span> <span class="nc">ItemWithFlexibleFieldsExpanderPlugin</span> <span class="kd">extends</span> <span class="nc">AbstractPlugin</span> <span class="kd">implements</span> <span class="nc">CalculableObjectVertexExpanderPluginInterface</span> <span class="p">{</span> <span class="c1">// ...</span> <span class="cd">/** * @param \CalculableObjectTransfer $calculableObjectTransfer * * @return \CalculableObjectTransfer */</span> <span class="k">public</span> <span class="k">function</span> <span class="n">expand</span><span class="p">(</span><span class="kt">CalculableObjectTransfer</span> <span class="nv">$calculableObjectTransfer</span><span class="p">):</span> <span class="kt">CalculableObjectTransfer</span> <span class="p">{</span> <span class="k">foreach</span> <span class="p">(</span><span class="nv">$calculableObjectTransfer</span><span class="o">-&gt;</span><span class="nf">getItems</span><span class="p">()</span> <span class="k">as</span> <span class="nv">$itemTransfer</span><span class="p">)</span> <span class="p">{</span> <span class="nv">$itemTransfer</span> <span class="o">-&gt;</span><span class="nf">getTaxMetadata</span><span class="p">()</span> <span class="o">-&gt;</span><span class="nf">setFlexibleFields</span><span class="p">(</span> <span class="p">[</span> <span class="s1">'flexibleCodeFields'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="p">[</span> <span class="s1">'fieldId'</span> <span class="o">=&gt;</span> <span class="mi">1</span><span class="p">,</span> <span class="s1">'value'</span> <span class="o">=&gt;</span> <span class="s1">'vertex-flexible-code-value'</span><span class="p">,</span> <span class="p">],</span> <span class="p">],</span> <span class="p">],</span> <span class="p">);</span> <span class="p">}</span> <span class="k">return</span> <span class="nv">$calculableObjectTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <h2 id="configure-the-vertex-dependency-provider">3. Configure the Vertex dependency provider</h2> <p>After the Vertex dependency provider configuration, the plugin stack should look similar to the following:</p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <span class="kn">namespace</span> <span class="nn">Pyz\Zed\Vertex</span><span class="p">;</span> <span class="c1">// The following plugins are for Marketplace only.</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\MerchantProfile\Communication\Plugin\TaxApp\MerchantProfileAddressCalculableObjectTaxAppExpanderPlugin</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\MerchantProfile\Communication\Plugin\TaxApp\MerchantProfileAddressOrderTaxAppExpanderPlugin</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\ProductOfferAvailability\Communication\Plugin\TaxApp\ProductOfferAvailabilityCalculableObjectTaxAppExpanderPlugin</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\ProductOfferAvailability\Communication\Plugin\TaxApp\ProductOfferAvailabilityOrderTaxAppExpanderPlugin</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">VertexDependencyProvider</span> <span class="kd">extends</span> <span class="nc">SprykerTaxAppDependencyProvider</span> <span class="p">{</span> <span class="cd">/** * @return array&lt;\SprykerEco\Zed\Vertex\Dependency\Plugin\CalculableObjectVertexExpanderPluginInterface|\Spryker\Zed\TaxAppExtension\Dependency\Plugin\CalculableObjectTaxAppExpanderPluginInterface&gt; */</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">getCalculableObjectVertexExpanderPlugins</span><span class="p">():</span> <span class="kt">array</span> <span class="p">{</span> <span class="k">return</span> <span class="p">[</span> <span class="c1"># This plugin stack is responsible for expansion of CalculableObjectTransfer based on present fields. Add your custom implemented expander plugins here following the example in `spryker-eco/vertex` module.</span> <span class="c1">// The following plugins are for Marketplace only.</span> <span class="c1"># This plugin is expanding CalculableObjectTransfer object with merchant address information.</span> <span class="k">new</span> <span class="nc">MerchantProfileAddressCalculableObjectTaxAppExpanderPlugin</span><span class="p">(),</span> <span class="c1"># This plugin is expanding CalculableObjectTransfer object with product offer availability information.</span> <span class="k">new</span> <span class="nc">ProductOfferAvailabilityCalculableObjectTaxAppExpanderPlugin</span><span class="p">(),</span> <span class="p">];</span> <span class="p">}</span> <span class="cd">/** * @return array&lt;\SprykerEco\Zed\Vertex\Dependency\Plugin\OrderVertexExpanderPluginInterface|\Spryker\Zed\TaxAppExtension\Dependency\Plugin\OrderTaxAppExpanderPluginInterface&gt; */</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">getOrderVertexExpanderPlugins</span><span class="p">():</span> <span class="kt">array</span> <span class="p">{</span> <span class="k">return</span> <span class="p">[</span> <span class="c1"># This plugin stack is responsible for expansion of OrderTransfer based on present fields. Add your custom implemented expander plugins here following the example in `spryker-eco/vertex` module.</span> <span class="c1">// The following plugins are for Marketplace only.</span> <span class="c1"># This plugin is expanding OrderTransfer object with merchant address information.</span> <span class="k">new</span> <span class="nc">MerchantProfileAddressOrderTaxAppExpanderPlugin</span><span class="p">(),</span> <span class="c1"># This plugin is expanding OrderTransfer object with product offer availability information.</span> <span class="k">new</span> <span class="nc">ProductOfferAvailabilityOrderTaxAppExpanderPlugin</span><span class="p">(),</span> <span class="p">];</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <h2 id="marketplace-only-configure-product-offer-stock-dependency-provider">4. Marketplace only: Configure Product Offer Stock dependency provider</h2> <p>After you have configured the Product Offer Stock dependency provider for Marketplace, the plugin stack should look similar to the following:</p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <span class="kn">namespace</span> <span class="nn">Pyz\Zed\ProductOfferStock</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\ProductOfferStock\ProductOfferStockDependencyProvider</span> <span class="k">as</span> <span class="nc">SprykerProductOfferStockDependencyProvider</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\StockAddress\Communication\Plugin\Stock\StockAddressStockTransferProductOfferStockExpanderPlugin</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">ProductOfferStockDependencyProvider</span> <span class="kd">extends</span> <span class="nc">SprykerProductOfferStockDependencyProvider</span> <span class="p">{</span> <span class="cd">/** * @return array&lt;\Spryker\Zed\ProductOfferStockExtension\Dependency\Plugin\StockTransferProductOfferStockExpanderPluginInterface&gt; */</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">getStockTransferExpanderPluginCollection</span><span class="p">():</span> <span class="kt">array</span> <span class="p">{</span> <span class="k">return</span> <span class="p">[</span> <span class="c1"># This plugin is providing warehouse address to StockTransfer objects which is used during tax calculation.</span> <span class="k">new</span> <span class="nc">StockAddressStockTransferProductOfferStockExpanderPlugin</span><span class="p">(),</span> <span class="p">];</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <h2 id="optional-configure-custom-seller-and-buyer-countries">5. Optional: Configure custom seller and buyer countries</h2> <p>If a user doesn’t choose a country during the checkout Address step, the system automatically uses the first country listed in the selected Spryker store. The same rule applies to sellers, except that the country is taken from the first warehouse address of a product stock.</p> <p>To change this default behavior, you can configure the country for both sellers and buyers. These configured countries will be the default values for tax calculations. You can use the following configuration methods to do this:</p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <span class="kn">namespace</span> <span class="nn">Pyz\Zed\Vertex</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">SprykerEco\Zed\Vertex\VertexConfig</span> <span class="k">as</span> <span class="nc">SprykerVertexConfig</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">VertexConfig</span> <span class="kd">extends</span> <span class="nc">SprykerVertexConfig</span> <span class="p">{</span> <span class="k">public</span> <span class="k">function</span> <span class="n">getSellerCountryCode</span><span class="p">():</span> <span class="kt">string</span> <span class="p">{</span> <span class="k">return</span> <span class="s1">'FR'</span><span class="p">;</span> <span class="p">}</span> <span class="k">public</span> <span class="k">function</span> <span class="n">getCustomerCountryCode</span><span class="p">():</span> <span class="kt">string</span> <span class="p">{</span> <span class="k">return</span> <span class="s1">'DE'</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <h2 id="add-translations">6. Add translations</h2> <ol> <li>Append the glossary according to your configuration:</li> </ol> <p><strong>src/data/import/glossary.csv</strong></p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="s">cart.total.tax_total.calculated_at_checkout,an der Kasse berechnet,de_DE</span> <span class="s">cart.total.tax_total.calculated_at_checkout,calculated at checkout,en_US</span> </code></pre></div></div> <ol start="2"> <li>Import the updated glossary:</li> </ol> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="s">console data:import glossary</span> </code></pre></div></div> <hr /> <h2 id="reference-mapping-of-quote-and-order-objects-to-vertex-api">Reference: Mapping of Quote and Order objects to Vertex API</h2> <p>The following table reflects the mapping of the Spryker Quote and Order transfer object to the Vertex API request format. This information is useful for developing custom plugins for a deeper integration with your project.</p> <table> <thead> <tr> <th>QuoteTransfer/OrderTransfer object properties</th> <th>Vertex API field</th> <th>Comment</th> </tr> </thead> <tbody> <tr> <td>Current date (Y-m-d)</td> <td>documentDate</td> <td></td> </tr> <tr> <td>QuoteTransfer.uuid / OrderTransfer.orderReference / new Uuid4 (if quote.uuid is not present)</td> <td>documentNumber</td> <td></td> </tr> <tr> <td>QuoteTransfer.uuid / OrderTransfer.orderReference / new Uuid4 (if quote.uuid is not present)</td> <td>transactionId</td> <td></td> </tr> <tr> <td>-</td> <td>transactionType</td> <td>Always <code>SALE</code>.</td> </tr> <tr> <td>-</td> <td>saleMessageType</td> <td>Depending on the type of operation, <code>INVOICE</code> or <code>QUOTATION</code>.</td> </tr> <tr> <td>taxMetadata</td> <td>Mapped over the final request 1:1.</td> <td>Metadata needs to follow the structure of the Vertex API request.</td> </tr> <tr> <td>taxMetadata.seller.company</td> <td>seller.company</td> <td>Required by Vertex from the legal standpoint.</td> </tr> <tr> <td>items[].sku</td> <td>lineItems[].lineItemId; lineItems[].product.value; lineItems[].vendorSku</td> <td><code>lineItems[].lineItemId</code> can be changed if there are multiple items with the same SKU in the request.</td> </tr> <tr> <td>items[].shipment.shippingAddress</td> <td>lineItems[].customer.destination</td> <td></td> </tr> <tr> <td>billingAddress</td> <td>lineItems[].customer.administrativeDestination</td> <td></td> </tr> <tr> <td>items[].merchantStockAddresses</td> <td>lineItems[].seller.physicalOrigin</td> <td>Multiple addresses are mapped to multiple items in the Vertex PBC and Vertex API <code>lineItems[]</code>.</td> </tr> <tr> <td>items[].merchantProfileAddress</td> <td>lineItems[].seller.administrativeOrigin</td> <td></td> </tr> <tr> <td>items[].unitDiscountAmountFullAggregation</td> <td>lineItems[].discount.discountValue</td> <td>Prices are converted from the Spryker’s cent-based format to the Vertex decimal format.</td> </tr> <tr> <td>-</td> <td>lineItems[].discount.discountType</td> <td>Always <code>DiscountAmount</code>. Spryker stores discounts based on amount, so there is no need for percentage-based discounts.</td> </tr> <tr> <td>items[].unitPrice (either GROSS or NET depending on the selected mode)</td> <td>lineItems[].unitPrice</td> <td>Prices are converted from Spryker’s cent-based format to Vertex decimal format.</td> </tr> <tr> <td>items[].merchantStockAddresses.quantityToShip</td> <td>lineItems[].quantity.value</td> <td>If <code>quantityToShip</code> is less than the quantity requested in cart, the item is mapped to multiple items in the Vertex API.</td> </tr> <tr> <td>-</td> <td>lineItems[].quantity.unitOfMeasure</td> <td>Always <code>EA</code> (“each”). Other units of measure are not supported.</td> </tr> <tr> <td>items[].taxMetadata</td> <td>Mapped over specific <code>lineItem</code> one to one.</td> <td>Metadata needs to follow the structure of the Vertex API request. For <code>lineItems</code>, it’s mapped over each corresponding item based on <code>lineItemId</code>.</td> </tr> <tr> <td>items[].taxMetadata.seller.company</td> <td>lineItems[].seller.company</td> <td>Required by Vertex from the legal standpoint.</td> </tr> <tr> <td>expenses (only for expenses with the <code>SHIPMENT_EXPENSE_TYPE</code> type)</td> <td>lineItems</td> <td>Shipments are treated like products in Vertex - like a line item.</td> </tr> <tr> <td>expenses.hash</td> <td>lineItems[].lineItemId</td> <td></td> </tr> <tr> <td>expenses.shipment.shipmentAddress</td> <td>lineItems[].customer.destination</td> <td></td> </tr> <tr> <td>expenses.shipment.method.shipmentMethodKey</td> <td>lineItems[].product.value</td> <td>Depends on the selected shipment method.</td> </tr> <tr> <td>billingAddress</td> <td>lineItems[].customer.administrativeDestination</td> <td></td> </tr> <tr> <td>expenses.sumPrice (either GROSS or NET depending on the selected mode)</td> <td>lineItems[].extendedPrice</td> <td></td> </tr> <tr> <td>expenses.sumDiscountAmountAggregation</td> <td>lineItems[].discount.discountValue</td> <td>Prices are converted from the Spryker’s cent-based format to the Vertex decimal format.</td> </tr> <tr> <td>lineItems[].discount.discountType</td> <td>Always <code>DiscountAmount</code>. Spryker stores discounts based on amount, so there is no need to use percentage-based discounts.</td> <td>priceMode</td> </tr> <tr> <td>lineItems[].taxIncludedIndicator</td> <td></td> <td>NET mode: false; GROSS mode: true.</td> </tr> </tbody> </table> <h3 id="location-mapping">Location mapping</h3> <table> <thead> <tr> <th>Spryker</th> <th>Vertex</th> <th>Comment</th> </tr> </thead> <tbody> <tr> <td>address1</td> <td>streetAddress1</td> <td></td> </tr> <tr> <td>address2</td> <td>streetAddress2</td> <td>Should be either not empty or <code>null</code>.</td> </tr> <tr> <td>city</td> <td>city</td> <td></td> </tr> <tr> <td>state</td> <td>mainDivision</td> <td>Should be either not empty or <code>null</code>.</td> </tr> <tr> <td>zipCode</td> <td>postalCode</td> <td></td> </tr> <tr> <td>country.iso2Code</td> <td>country</td> <td></td> </tr> </tbody> </table> <h2 id="next-step">Next step</h2> <p><a href="/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/verify-vertex-connection.html">Verify Vertex connection</a></p> Mon, 16 Mar 2026 08:55:32 +0000 https://docs.spryker.com/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/configure-vertex-specific-metadata.html https://docs.spryker.com/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/configure-vertex-specific-metadata.html This document describes how to install Amazon QuickSight. ## Install feature core Follow the steps below to install the Amazon QuickSight core. ### Prerequisites Install the required features: | NAME | VERSION | INSTALLATION GUIDE | |--------------------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Analytics | {{page.release_tag}} | [Install the Analytics feature](/docs/pbc/all/business-intelligence/latest/install-the-analytics-feature.html) | | Spryker Core Back Office | {{page.release_tag}} | [Install the Spryker Core Back Office feature](/docs/pbc/all/identity-access-management/latest/install-and-upgrade/install-the-spryker-core-back-office-feature.html) | ### 1) Install the required modules Install the required modules using Composer: ```bash composer require spryker-eco/amazon-quicksight:"^2.0.0" --update-with-dependencies ``` {% info_block warningBox "Verification" %} Make sure the following modules have been installed: | MODULE | EXPECTED DIRECTORY | |------------------|--------------------------------------| | AmazonQuicksight | vendor/spryker-eco/amazon-quicksight | {% endinfo_block %} ### 2) Set up the configuration 1. Add one of the following QuickSight asset bundles to the project level, for example–to `src/Pyz/Zed/AmazonQuicksight/data/asset-bundle.zip`. Preconfigured asset bundles per demo shop: - [B2B Marketplace](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/business-intelligence/amazon-quicksight-third-party-integration/install-amazon-quicksight.md/b2b-mp-asset-bundle.zip) - [B2B](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/business-intelligence/amazon-quicksight-third-party-integration/install-amazon-quicksight.md/b2b-asset-bundle.zip) - [B2C Marketplace](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/business-intelligence/amazon-quicksight-third-party-integration/install-amazon-quicksight.md/b2c-mp-asset-bundle.zip) - [B2C](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/business-intelligence/amazon-quicksight-third-party-integration/install-amazon-quicksight.md/b2c-asset-bundle.zip) {% info_block infoBox "SELECT statements in custom SQL queries" %} In custom SQL queries, avoid using `*` in `SELECT` statements. Instead, explicitly specify the required columns. This reduces the risk of exposing sensitive data when modifying asset bundles or creating custom datasets. {% endinfo_block %} 2. Define the path to the asset bundle: **src/Pyz/Zed/AmazonQuicksight/AmazonQuicksightConfig.php** ```php <?php namespace Pyz\Zed\AmazonQuicksight; use SprykerEco\Zed\AmazonQuicksight\AmazonQuicksightConfig as SprykerEcoAmazonQuicksightConfig; class AmazonQuicksightConfig extends SprykerEcoAmazonQuicksightConfig { /** * @var string */ protected const ASSET_BUNDLE_IMPORT_FILE_PATH = '%s/src/Pyz/Zed/AmazonQuicksight/data/asset-bundle.zip'; /** * @return string */ public function getAssetBundleImportFilePath(): string { return sprintf(static::ASSET_BUNDLE_IMPORT_FILE_PATH, APPLICATION_ROOT_DIR); } } ``` 3. To enable the asset bundle import, configure the data sets and data source IDs from one of the asset bundles: **src/Pyz/Zed/AmazonQuicksight/AmazonQuicksightConfig.php** <details> <summary>B2B Marketplace</summary> ```php <?php namespace Pyz\Zed\AmazonQuicksight; use SprykerEco\Zed\AmazonQuicksight\AmazonQuicksightConfig as SprykerEcoAmazonQuicksightConfig; class AmazonQuicksightConfig extends SprykerEcoAmazonQuicksightConfig { /** * @var list<string> */ protected const ASSET_BUNDLE_IMPORT_DELETE_DATA_SET_IDS = [ 'SprykerB2BMPDefaultDatasetCategoryLocalizedProductAbstract', 'SprykerB2BMPDefaultDatasetCompany', 'SprykerB2BMPDefaultDatasetCustomer', 'SprykerB2BMPDefaultDatasetCustomerAddress', 'SprykerB2BMPDefaultDatasetMerchantCommission', 'SprykerB2BMPDefaultDatasetMerchantOrder', 'SprykerB2BMPDefaultDatasetMerchantOrderCategory', 'SprykerB2BMPDefaultDatasetMerchantOrderItems', 'SprykerB2BMPDefaultDatasetMerchantProductOffer', 'SprykerB2BMPDefaultDatasetMerchantProductProductAbstract', 'SprykerB2BMPDefaultDatasetMerchantStore', 'SprykerB2BMPDefaultDatasetOrderDiscounts', 'SprykerB2BMPDefaultDatasetOrderItemCategoryProductBrand', 'SprykerB2BMPDefaultDatasetOrderItemLocalizedProductConcrete', 'SprykerB2BMPDefaultDatasetOrderItemProductCategory', 'SprykerB2BMPDefaultDatasetOrderItemsReturnDate', 'SprykerB2BMPDefaultDatasetOrderItemState', 'SprykerB2BMPDefaultDatasetOrderItemStateCustomers', 'SprykerB2BMPDefaultDatasetOrderItemStateHistory', 'SprykerB2BMPDefaultDatasetOrderPaymentMethods', 'SprykerB2BMPDefaultDatasetOrderReturns', 'SprykerB2BMPDefaultDatasetOrderReturnsProductConcrete', 'SprykerB2BMPDefaultDatasetOrderShipmentMethods', 'SprykerB2BMPDefaultDatasetOrderTotalsCustomerCompany', 'SprykerB2BMPDefaultDatasetOrderTotalsCustomSQL', 'SprykerB2BMPDefaultDatasetProductConcreteAvailability', 'SprykerB2BMPDefaultDatasetProductConcreteStore', 'SprykerB2BMPDefaultDatasetQuoteProducts', 'SprykerB2BMPDefaultDatasetShoppingListProducts', ]; /** * @var string */ protected const DEFAULT_DATA_SOURCE_ID = 'SprykerB2BMPDefaultDataSource'; } ``` </details> <details> <summary>B2B</summary> ```php <?php namespace Pyz\Zed\AmazonQuicksight; use SprykerEco\Zed\AmazonQuicksight\AmazonQuicksightConfig as SprykerEcoAmazonQuicksightConfig; class AmazonQuicksightConfig extends SprykerEcoAmazonQuicksightConfig { /** * @var list<string> */ protected const ASSET_BUNDLE_IMPORT_DELETE_DATA_SET_IDS = [ 'SprykerB2BDefaultDatasetOrderShipmentMethods', 'SprykerB2BDefaultDatasetOrderReturnsProductConcrete', 'SprykerB2BDefaultDatasetOrderReturns', 'SprykerB2BDefaultDatasetOrderItemCategoryProductBrand', 'SprykerB2BDefaultDatasetOrderItemLocalizedProductConcrete', 'SprykerB2BDefaultDatasetOrderItemProductCategory', 'SprykerB2BDefaultDatasetOrderItemsReturnDate', 'SprykerB2BDefaultDatasetOrderItemState', 'SprykerB2BDefaultDatasetOrderItemStateHistory', 'SprykerB2BDefaultDatasetOrderDiscounts', 'SprykerB2BDefaultDatasetOrderPaymentMethods', 'SprykerB2BDefaultDatasetOrderItemStateCustomers', 'SprykerB2BDefaultDatasetOrderTotalsCustomerCompany', 'SprykerB2BDefaultDatasetOrderTotalsCustomSQL', 'SprykerB2BDefaultDatasetCategoryLocalizedProductAbstract', 'SprykerB2BDefaultDatasetProductConcreteStore', 'SprykerB2BDefaultDatasetMerchantStore', 'SprykerB2BDefaultDatasetQuoteProducts', 'SprykerB2BDefaultDatasetProductConcreteAvailability', 'SprykerB2BDefaultDatasetCompany', 'SprykerB2BDefaultDatasetCustomer', 'SprykerB2BDefaultDatasetCustomerAddress', ]; /** * @var string */ protected const DEFAULT_DATA_SOURCE_ID = 'SprykerB2BDefaultDataSource'; } ``` </details> <details> <summary>B2C Marketplace</summary> ```php <?php namespace Pyz\Zed\AmazonQuicksight; use SprykerEco\Zed\AmazonQuicksight\AmazonQuicksightConfig as SprykerEcoAmazonQuicksightConfig; class AmazonQuicksightConfig extends SprykerEcoAmazonQuicksightConfig { /** * @var list<string> */ protected const ASSET_BUNDLE_IMPORT_DELETE_DATA_SET_IDS = [ 'SprykerB2CMPDefaultDatasetCategoryLocalizedProductAbstract', 'SprykerB2CMPDefaultDatasetCustomer', 'SprykerB2CMPDefaultDatasetCustomerAddress', 'SprykerB2CMPDefaultDatasetMerchantCommission', 'SprykerB2CMPDefaultDatasetMerchantOrder', 'SprykerB2CMPDefaultDatasetMerchantOrderCategory', 'SprykerB2CMPDefaultDatasetMerchantOrderItems', 'SprykerB2CMPDefaultDatasetMerchantProductOffer', 'SprykerB2CMPDefaultDatasetMerchantProductProductAbstract', 'SprykerB2CMPDefaultDatasetMerchantStore', 'SprykerB2CMPDefaultDatasetOrderDiscounts', 'SprykerB2CMPDefaultDatasetOrderItemCategoryProductBrand', 'SprykerB2CMPDefaultDatasetOrderItemLocalizedProductConcrete', 'SprykerB2CMPDefaultDatasetOrderItemProductCategory', 'SprykerB2CMPDefaultDatasetOrderItemsReturnDate', 'SprykerB2CMPDefaultDatasetOrderItemState', 'SprykerB2CMPDefaultDatasetOrderItemStateHistory', 'SprykerB2CMPDefaultDatasetOrderPaymentMethods', 'SprykerB2CMPDefaultDatasetOrderReturns', 'SprykerB2CMPDefaultDatasetOrderReturnsProductConcrete', 'SprykerB2CMPDefaultDatasetOrderShipmentMethods', 'SprykerB2CMPDefaultDatasetOrderTotalsCustomSQL', 'SprykerB2CMPDefaultDatasetProductConcreteAvailability', 'SprykerB2CMPDefaultDatasetProductConcreteStore', 'SprykerB2CMPDefaultDatasetQuoteProducts', ]; /** * @var string */ protected const DEFAULT_DATA_SOURCE_ID = 'SprykerB2CMPDefaultDataSource'; } ``` </details> <details> <summary>B2C</summary> ```php <?php namespace Pyz\Zed\AmazonQuicksight; use SprykerEco\Zed\AmazonQuicksight\AmazonQuicksightConfig as SprykerEcoAmazonQuicksightConfig; class AmazonQuicksightConfig extends SprykerEcoAmazonQuicksightConfig { /** * @var list<string> */ protected const ASSET_BUNDLE_IMPORT_DELETE_DATA_SET_IDS = [ 'SprykerB2CDefaultDatasetCategoryLocalizedProductAbstract', 'SprykerB2CDefaultDatasetCustomer', 'SprykerB2CDefaultDatasetCustomerAddress', 'SprykerB2CDefaultDatasetOrderDiscounts', 'SprykerB2CDefaultDatasetOrderItemCategoryProductBrand', 'SprykerB2CDefaultDatasetOrderItemLocalizedProductConcrete', 'SprykerB2CDefaultDatasetOrderItemProductCategory', 'SprykerB2CDefaultDatasetOrderItemsReturnDate', 'SprykerB2CDefaultDatasetOrderItemState', 'SprykerB2CDefaultDatasetOrderItemStateHistory', 'SprykerB2CDefaultDatasetOrderPaymentMethods', 'SprykerB2CDefaultDatasetOrderReturns', 'SprykerB2CDefaultDatasetOrderReturnsProductConcrete', 'SprykerB2CDefaultDatasetOrderShipmentMethods', 'SprykerB2CDefaultDatasetOrderTotalsCustomSQL', 'SprykerB2CDefaultDatasetProductConcreteAvailability', 'SprykerB2CDefaultDatasetProductConcreteStore', 'SprykerB2CDefaultDatasetQuoteProducts', ]; /** * @var string */ protected const DEFAULT_DATA_SOURCE_ID = 'SprykerB2CDefaultDataSource'; } ``` </details> {% info_block warningBox "Verification" %} These changes are verified in a later step. {% endinfo_block %} 4. Add the following environment configuration: | CONFIGURATION | SPECIFICATION | NAMESPACE | |-------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|------------------------------------| | AmazonQuicksightConstants::AWS_ACCOUNT_ID | ID of the AWS account holding your Amazon QuickSight account. | SprykerEco\Shared\AmazonQuicksight | | AmazonQuicksightConstants::AWS_REGION | AWS region of your Amazon QuickSight account. | SprykerEco\Shared\AmazonQuicksight | | AmazonQuicksightConstants::AWS_QUICKSIGHT_NAMESPACE | Name of the QuickSight namespace. | SprykerEco\Shared\AmazonQuicksight | | AmazonQuicksightConstants::DEFAULT_DATA_SOURCE_USERNAME | Username of the default data source. | SprykerEco\Shared\AmazonQuicksight | | AmazonQuicksightConstants::DEFAULT_DATA_SOURCE_PASSWORD | Default data source password. | SprykerEco\Shared\AmazonQuicksight | | AmazonQuicksightConstants::DEFAULT_DATA_SOURCE_DATABASE_NAME | Default data source database name. | SprykerEco\Shared\AmazonQuicksight | | AmazonQuicksightConstants::DEFAULT_DATA_SOURCE_DATABASE_HOST | Default data source database host. | SprykerEco\Shared\AmazonQuicksight | | AmazonQuicksightConstants::DEFAULT_DATA_SOURCE_DATABASE_PORT | Default data source database port. | SprykerEco\Shared\AmazonQuicksight | | AmazonQuicksightConstants::DEFAULT_DATA_SOURCE_VPC_CONNECTION_ARN | Default data source VPC connection ARN. | SprykerEco\Shared\AmazonQuicksight | | AmazonQuicksightConstants::GENERATE_EMBED_URL_ALLOWED_DOMAINS | List of domains allowed for generating embed URLs. | SprykerEco\Shared\AmazonQuicksight | | AmazonQuicksightConstants::QUICKSIGHT_ASSUMED_ROLE_ARN | The role ARN used by `Aws\Sts\StsClient` to assume a role used for all API calls to Quicksight. | SprykerEco\Shared\AmazonQuicksight | **config/Shared/config_default.php** ```php <?php use SprykerEco\Shared\AmazonQuicksight\AmazonQuicksightConstants; // -------------------------------- AWS QUICKSIGHT ------------------------------- $config[AmazonQuicksightConstants::AWS_ACCOUNT_ID] = getenv('AWS_ACCOUNT_ID'); $config[AmazonQuicksightConstants::AWS_REGION] = getenv('AWS_REGION'); $config[AmazonQuicksightConstants::AWS_QUICKSIGHT_NAMESPACE] = getenv('QUICKSIGHT_NAMESPACE'); $config[AmazonQuicksightConstants::DEFAULT_DATA_SOURCE_USERNAME] = getenv('SPRYKER_BI_DB_USER'); $config[AmazonQuicksightConstants::DEFAULT_DATA_SOURCE_PASSWORD] = getenv('SPRYKER_BI_DB_PASSWORD'); $config[AmazonQuicksightConstants::DEFAULT_DATA_SOURCE_DATABASE_NAME] = getenv('SPRYKER_DB_DATABASE'); $config[AmazonQuicksightConstants::DEFAULT_DATA_SOURCE_DATABASE_HOST] = getenv('SPRYKER_DB_RO_REPLICA_HOST'); $config[AmazonQuicksightConstants::DEFAULT_DATA_SOURCE_DATABASE_PORT] = getenv('SPRYKER_DB_PORT'); $config[AmazonQuicksightConstants::DEFAULT_DATA_SOURCE_VPC_CONNECTION_ARN] = getenv('QUICKSIGHT_VPC_CONNECTION_ARN'); $config[AmazonQuicksightConstants::GENERATE_EMBED_URL_ALLOWED_DOMAINS] = [ sprintf('https://%s', getenv('SPRYKER_BE_HOST')), ]; $config[AmazonQuicksightConstants::QUICKSIGHT_ASSUMED_ROLE_ARN] = getenv('QUICKSIGHT_ASSUMED_ROLE_ARN'); ``` {% info_block infoBox "Credentials" %} We recommended not defining the AWS credentials and let the SDK attempt to load them from the environment. If you need to specify the credentials,for example–for local development, you can do it as follows: | CONFIGURATION | SPECIFICATION | NAMESPACE | |---------------------------------------------------|------------------------|------------------------------------| | AmazonQuicksightConstants::AWS_CREDENTIALS_KEY | AWS access key ID. | SprykerEco\Shared\AmazonQuicksight | | AmazonQuicksightConstants::AWS_CREDENTIALS_SECRET | AWS access key secret. | SprykerEco\Shared\AmazonQuicksight | | AmazonQuicksightConstants::AWS_CREDENTIALS_TOKEN | AWS security token. | SprykerEco\Shared\AmazonQuicksight | ```php <?php use SprykerEco\Shared\AmazonQuicksight\AmazonQuicksightConstants; // -------------------------------- AWS QUICKSIGHT ------------------------------- $config[AmazonQuicksightConstants::AWS_CREDENTIALS_KEY] = getenv('AWS_ACCESS_KEY_ID'); $config[AmazonQuicksightConstants::AWS_CREDENTIALS_SECRET] = getenv('AWS_SECRET_ACCESS_KEY'); $config[AmazonQuicksightConstants::AWS_CREDENTIALS_TOKEN] = getenv('AWS_SESSION_TOKEN'); ``` {% endinfo_block %} ### 3) Set up database schema and transfer objects Apply database changes and generate entity and transfer changes: ```bash console propel:install console transfer:generate ``` {% info_block warningBox "Verification" %} Make sure the following changes have been applied in the database: | DATABASE ENTITY | TYPE | EVENT | |----------------------------------------|-------|---------| | spy_quicksight_user | table | created | | spy_quicksight_asset_bundle_import_job | table | created | Make sure the following changes have been triggered in transfer objects: | TRANSFER | TYPE | EVENT | PATH | |---------------------------------------------------------------|--------|---------|--------------------------------------------------------------------------------------------| | QuicksightUser | class | created | src/Generated/Shared/Transfer/QuicksightUserTransfer | | QuicksightUserCriteria | class | created | src/Generated/Shared/Transfer/QuicksightUserCriteriaTransfer | | QuicksightUserConditions | class | created | src/Generated/Shared/Transfer/QuicksightUserConditionsTransfer | | QuicksightUserCollection | class | created | src/Generated/Shared/Transfer/QuicksightUserCollectionTransfer | | QuicksightUserCollectionResponse | class | created | src/Generated/Shared/Transfer/QuicksightUserCollectionResponseTransfer | | QuicksightDeleteUserResponse | class | created | src/Generated/Shared/Transfer/QuicksightDeleteUserResponseTransfer | | QuicksightDeleteUserRequest | class | created | src/Generated/Shared/Transfer/QuicksightDeleteUserRequestTransfer | | QuicksightListUsersRequest | class | created | src/Generated/Shared/Transfer/QuicksightListUsersRequestTransfer | | QuicksightListUsersResponse | class | created | src/Generated/Shared/Transfer/QuicksightListUsersResponseTransfer | | QuicksightGenerateEmbedUrlRequest | class | created | src/Generated/Shared/Transfer/QuicksightGenerateEmbedUrlRequestTransfer | | QuicksightExperienceConfiguration | class | created | src/Generated/Shared/Transfer/QuicksightExperienceConfigurationTransfer | | QuicksightConsole | class | created | src/Generated/Shared/Transfer/QuicksightConsoleTransfer | | QuicksightGenerateEmbedUrlResponse | class | created | src/Generated/Shared/Transfer/QuicksightGenerateEmbedUrlResponseTransfer | | QuicksightEmbedUrl | class | created | src/Generated/Shared/Transfer/QuicksightEmbedUrlTransfer | | QuicksightAssetBundleImportJob | class | created | src/Generated/Shared/Transfer/QuicksightAssetBundleImportJobTransfer | | QuicksightAssetBundleImportJobCollection | class | created | src/Generated/Shared/Transfer/QuicksightAssetBundleImportJobCollectionTransfer | | QuicksightAssetBundleImportJobCriteria | class | created | src/Generated/Shared/Transfer/QuicksightAssetBundleImportJobCriteriaTransfer | | QuicksightAssetBundleImportJobConditions | class | created | src/Generated/Shared/Transfer/QuicksightAssetBundleImportJobConditionsTransfer | | QuicksightStartAssetBundleImportJobRequest | class | created | src/Generated/Shared/Transfer/QuicksightStartAssetBundleImportJobRequestTransfer | | QuicksightAssetBundleImportSource | class | created | src/Generated/Shared/Transfer/QuicksightAssetBundleImportSourceTransfer | | QuicksightOverrideParameters | class | created | src/Generated/Shared/Transfer/QuicksightOverrideParametersTransfer | | QuicksightOverrideParametersDataSource | class | created | src/Generated/Shared/Transfer/QuicksightOverrideParametersDataSourceTransfer | | QuicksightOverrideParametersDataSourceCredentials | class | created | src/Generated/Shared/Transfer/QuicksightOverrideParametersDataSourceCredentialsTransfer | | QuicksightOverrideParametersDataSourceCredentialPair | class | created | src/Generated/Shared/Transfer/QuicksightOverrideParametersDataSourceCredentialPairTransfer | | QuicksightOverrideParametersDataSourceParameters | class | created | src/Generated/Shared/Transfer/QuicksightOverrideParametersDataSourceCredentialPairTransfer | | QuicksightOverrideParametersDataSourceMariaDbParameters | class | created | src/Generated/Shared/Transfer/QuicksightOverrideParametersDataSourceCredentialPairTransfer | | QuicksightOverrideParametersDataSourceVpcConnectionProperties | class | created | src/Generated/Shared/Transfer/QuicksightOverrideParametersDataSourceCredentialPairTransfer | | QuicksightOverridePermissions | class | created | src/Generated/Shared/Transfer/QuicksightOverridePermissionsTransfer | | QuicksightOverridePermissionsAnalysis | class | created | src/Generated/Shared/Transfer/QuicksightOverridePermissionsAnalysisTransfer | | QuicksightOverridePermissionsDashboard | class | created | src/Generated/Shared/Transfer/QuicksightOverridePermissionsDashboardTransfer | | QuicksightOverridePermissionsDataSet | class | created | src/Generated/Shared/Transfer/QuicksightOverridePermissionsDataSetTransfer | | QuicksightOverridePermissionsDataSource | class | created | src/Generated/Shared/Transfer/QuicksightOverridePermissionsDataSourceTransfer | | QuicksightPermissions | class | created | src/Generated/Shared/Transfer/QuicksightPermissionsTransfer | | QuicksightStartAssetBundleImportJobResponse | class | created | src/Generated/Shared/Transfer/QuicksightStartAssetBundleImportJobResponseTransfer | | QuicksightDescribeAssetBundleImportJobRequest | class | created | src/Generated/Shared/Transfer/QuicksightDescribeAssetBundleImportJobRequestTransfer | | QuicksightDescribeAssetBundleImportJobResponse | class | created | src/Generated/Shared/Transfer/QuicksightDescribeAssetBundleImportJobResponseTransfer | | EnableQuicksightAnalyticsRequest | class | created | src/Generated/Shared/Transfer/EnableQuicksightAnalyticsRequestTransfer | | EnableQuicksightAnalyticsResponse | class | created | src/Generated/Shared/Transfer/EnableQuicksightAnalyticsResponseTransfer | | ResetQuicksightAnalyticsRequest | class | created | src/Generated/Shared/Transfer/ResetQuicksightAnalyticsRequestTransfer | | ResetQuicksightAnalyticsResponse | class | created | src/Generated/Shared/Transfer/ResetQuicksightAnalyticsResponseTransfer | {% endinfo_block %} ### 4) Add translations Generate a new translation cache for Zed: ```bash console translator:generate-cache ``` ### 5) Set up behavior 1. Enable the following behaviors by registering the plugins: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | |---------------------------------------------|----------------------------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------------------| | QuicksightAnalyticsCollectionExpanderPlugin | Expands the provided `AnalyticsCollectionTransfer` with QuickSight analytics. | | SprykerEco\Zed\AmazonQuicksight\Communication\Plugin\AnalyticsGui | | QuicksightUserExpanderPlugin | Populates `UserTransfer.quicksightUser` in the collection with existing QuickSight users. | | SprykerEco\Zed\AmazonQuicksight\Communication\Plugin\User | | DeleteQuicksightUserPostUpdatePlugin | Deletes a QuickSight user when the QuickSight role is deselected for the user or when the user is deactivated or deleted. | | SprykerEco\Zed\AmazonQuicksight\Communication\Plugin\User | **src/Pyz/Zed/AnalyticsGui/AnalyticsGuiDependencyProvider.php** ```php <?php namespace Pyz\Zed\AnalyticsGui; use Spryker\Zed\AnalyticsGui\AnalyticsGuiDependencyProvider as SprykerAnalyticsGuiDependencyProvider; use SprykerEco\Zed\AmazonQuicksight\Communication\Plugin\AnalyticsGui\QuicksightAnalyticsCollectionExpanderPlugin; class AnalyticsGuiDependencyProvider extends SprykerAnalyticsGuiDependencyProvider { /** * @return list<\Spryker\Zed\AnalyticsGuiExtension\Dependency\Plugin\AnalyticsCollectionExpanderPluginInterface> */ protected function getAnalyticsCollectionExpanderPlugins(): array { return [ new QuicksightAnalyticsCollectionExpanderPlugin(), ]; } } ``` **src/Pyz/Zed/User/UserDependencyProvider.php** ```php <?php namespace Pyz\Zed\User; use Spryker\Zed\User\UserDependencyProvider as SprykerUserDependencyProvider; use SprykerEco\Zed\AmazonQuicksight\Communication\Plugin\User\DeleteQuicksightUserPostUpdatePlugin; use SprykerEco\Zed\AmazonQuicksight\Communication\Plugin\User\QuicksightUserExpanderPlugin; class UserDependencyProvider extends SprykerUserDependencyProvider { /** * @return list<\Spryker\Zed\UserExtension\Dependency\Plugin\UserExpanderPluginInterface> */ protected function getUserExpanderPlugins(): array { return [ new QuicksightUserExpanderPlugin(), ]; } /** * @return list<\Spryker\Zed\UserExtension\Dependency\Plugin\UserPostUpdatePluginInterface> */ protected function getUserPostUpdatePlugins(): array { return [ new DeleteQuicksightUserPostUpdatePlugin(), ]; } } ``` {% info_block warningBox "Verification" %} | PLUGIN | VERIFICATION | | - | - | | Verify `QuicksightAnalyticsCollectionExpanderPlugin`| Go to `https://mysprykershop.com/analytics-gui/analytics` and make sure QuickSight analytics is displayed. By default, you should see the `No Analytics permission has been granted to the current user` message. | | Verify `QuicksightUserExpanderPlugin`| Create a new QuickSight user in the `spy_quicksight_user` DB table and call `UserFacade::getUserCollection()` for a user used for the newly created QuickSight user. Make sure the `UserCollection.user.quicksightUser` is expanded. | | Verify `DeleteQuicksightUserPostUpdatePlugin`| In the Back Office, go to **Users**>**Users**. For a newly created QuickSight user, deactivate deactive the respective Back Office user. Make sure the corresponding row is deleted in the `spy_quicksight_user` DB table. | {% endinfo_block %} 2. Enable behaviors by registering the console commands: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | |---------------------------------|----------------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------| | QuicksightUserSyncCreateConsole | In the `spy_quicksight_user` DB table, persists the users registered in QuickSight by persisted user emails. | | SprykerEco\Zed\AmazonQuicksight\Communication\Console | **src/Pyz/Zed/Console/ConsoleDependencyProvider.php** ```php <?php namespace Pyz\Zed\Console; use Spryker\Zed\Console\ConsoleDependencyProvider as SprykerConsoleDependencyProvider; use Spryker\Zed\Kernel\Container; use SprykerEco\Zed\AmazonQuicksight\Communication\Console\QuicksightUserSyncCreateConsole; class ConsoleDependencyProvider extends SprykerConsoleDependencyProvider { /** * @param \Spryker\Zed\Kernel\Container $container * * @return list<\Symfony\Component\Console\Command\Command> */ protected function getConsoleCommands(Container $container): array { return [ new QuicksightUserSyncCreateConsole(), ]; } } ``` {% info_block warningBox "Verification" %} 1. Create a QuickSight user in QuickSight. 2. Sync QuickSight to Back Office users: ```bash console quicksight-user:sync:create ``` In the `spy_quicksight_user` table, make sure that the corresponding QuickSight user has been added. {% endinfo_block %} 3. Optional: To sync users automatically during deployment, configure the installation stage of a pipeline, for example–destructive pipeline. Add the following command to the end of the `demodata` section: **config/install/destructive.yml** ```yaml sections: demodata: # ...other commands create-quicksight-users: command: 'vendor/bin/console quicksight-user:sync:create' ``` 4. Clear router cache: ```bash console router:cache:warm-up:backoffice ``` {% info_block warningBox "Verification" %} In the Back Office, make sure you can access the Analytics page: `https://backoffice.mysprykershop.com/amazon-quicksight/analytics/enable`. {% endinfo_block %} ## Install feature frontend Follow the steps below to install the Amazon QuickSight frontend. ### Prerequisites Install the required features: | NAME | VERSION | INSTALLATION GUIDE | |--------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| | Spryker Core | {{page.release_tag}} | [Install the Spryker Core feature](/docs/pbc/all/miscellaneous/latest/install-and-upgrade/install-features/install-the-spryker-core-feature.html) | ### 1) Install npm dependencies and enable Javascript and CSS changes 1. In `package.json`, add the `amazon-quicksight-embedding-sdk` npm package to `dependencies` and add the vendor workspace: **package.json** ```json { "dependencies": { "amazon-quicksight-embedding-sdk": "2.10.0" }, "workspaces": [ "vendor/spryker-eco/*/assets/Zed" ] } ``` 2. Install dependencies and build the Back Office frontend: ```bash npm install console frontend:zed:build ``` {% info_block warningBox "Verification" %} Make sure the Back Office frontend build completes without errors. The output must not contain `Module not found` messages. Verify that the following assets are generated: - `public/Zed/assets/css/spryker-zed-gui-commons.css` - `public/Zed/assets/css/spryker-zed-productmanagement-main.css` If assets are missing after deployment, verify that `amazon-quicksight-embedding-sdk` is present in `package.json` and rerun the build. {% endinfo_block %} Fri, 13 Mar 2026 16:03:41 +0000 https://docs.spryker.com/docs/pbc/all/business-intelligence/latest/amazon-quicksight-third-party-integration/install-amazon-quicksight.html https://docs.spryker.com/docs/pbc/all/business-intelligence/latest/amazon-quicksight-third-party-integration/install-amazon-quicksight.html <h2 id="overview">Overview</h2> <p>The Configuration feature ships with two built-in scopes: <code>global</code> and <code>store</code>. The scope system is extensible – you can add custom scopes like <code>locale</code>, <code>merchant</code>, or <code>customer_group</code> at the project level.</p> <p>Custom scopes integrate into the existing hierarchy. Values resolve from the most specific scope upward until a value is found, falling back to <code>default_value</code> from the YAML schema.</p> <div class="language-text highlighter-rouge"><div class="highlight"><pre class="highlight"><code>customer_group (most specific) -&gt; store -&gt; global (least specific) -&gt; default_value (from schema) </code></pre></div></div> <h2 id="what-you-need">What You Need</h2> <p>Adding a custom scope requires changes in three areas:</p> <table> <thead> <tr> <th>Area</th> <th>What</th> <th>Why</th> </tr> </thead> <tbody> <tr> <td>Shared Config</td> <td>Register scope in hierarchy</td> <td>Value resolution knows the parent chain</td> </tr> <tr> <td>Zed Plugin</td> <td>Provide scope identifiers</td> <td>Backoffice scope switcher lists available identifiers</td> </tr> <tr> <td>Optional: Zed + Client Plugin</td> <td>Expand read requests with scope context</td> <td><code>getModuleConfig()</code> calls automatically include scope</td> </tr> </tbody> </table> <h2 id="step-by-step-guide">Step-by-Step Guide</h2> <p>This guide uses <code>locale</code> as an example custom scope that inherits from <code>store</code>.</p> <h3 id="step-1-override-shared-configuration">Step 1: Override Shared Configuration</h3> <p>Create a project-level Shared Config that extends the core one:</p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// src/Pyz/Shared/Configuration/ConfigurationConfig.php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Shared\Configuration</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Shared\Configuration\ConfigurationConfig</span> <span class="k">as</span> <span class="nc">SprykerConfigurationConfig</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Shared\Store\StoreConstants</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">ConfigurationConfig</span> <span class="kd">extends</span> <span class="nc">SprykerConfigurationConfig</span> <span class="p">{</span> <span class="k">public</span> <span class="k">const</span> <span class="no">string</span> <span class="no">SCOPE_LOCALE</span> <span class="o">=</span> <span class="s1">'locale'</span><span class="p">;</span> <span class="k">public</span> <span class="k">function</span> <span class="n">getAvailableScopes</span><span class="p">():</span> <span class="kt">array</span> <span class="p">{</span> <span class="k">return</span> <span class="nb">array_merge</span><span class="p">(</span><span class="k">parent</span><span class="o">::</span><span class="nf">getAvailableScopes</span><span class="p">(),</span> <span class="p">[</span> <span class="k">static</span><span class="o">::</span><span class="no">SCOPE_LOCALE</span><span class="p">,</span> <span class="p">]);</span> <span class="p">}</span> <span class="k">public</span> <span class="k">function</span> <span class="n">getScopeHierarchy</span><span class="p">():</span> <span class="kt">array</span> <span class="p">{</span> <span class="k">return</span> <span class="nb">array_merge</span><span class="p">(</span><span class="k">parent</span><span class="o">::</span><span class="nf">getScopeHierarchy</span><span class="p">(),</span> <span class="p">[</span> <span class="k">static</span><span class="o">::</span><span class="no">SCOPE_LOCALE</span> <span class="o">=&gt;</span> <span class="nc">StoreConstants</span><span class="o">::</span><span class="no">SCOPE_STORE</span><span class="p">,</span> <span class="p">]);</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <p><strong>Important:</strong> The hierarchy map is <code>[scopeKey =&gt; parentScopeKey]</code>. A scope with parent <code>null</code> is the root.</p> <p>Built-in hierarchy:</p> <div class="language-text highlighter-rouge"><div class="highlight"><pre class="highlight"><code>global (parent: null) -- root, no identifier needed store (parent: global) -- requires identifier, e.g. "DE" </code></pre></div></div> <p>After adding <code>locale</code>:</p> <div class="language-text highlighter-rouge"><div class="highlight"><pre class="highlight"><code>global (parent: null) store (parent: global) locale (parent: store) -- requires identifier, e.g. "de_DE" </code></pre></div></div> <h3 id="step-2-create-a-scope-identifier-provider-plugin">Step 2: Create a Scope Identifier Provider Plugin</h3> <p>The Back Office uses this plugin to list available identifiers in the scope switcher dropdown.</p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// src/Pyz/Zed/Locale/Communication/Plugin/Configuration/LocaleConfigurationScopeIdentifierProviderPlugin.php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Zed\Locale\Communication\Plugin\Configuration</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\ConfigurationExtension\Dependency\Plugin\ConfigurationScopeIdentifierProviderPluginInterface</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\Kernel\Communication\AbstractPlugin</span><span class="p">;</span> <span class="cd">/** * @method \Spryker\Zed\Locale\Business\LocaleFacadeInterface getFacade() */</span> <span class="kd">class</span> <span class="nc">LocaleConfigurationScopeIdentifierProviderPlugin</span> <span class="kd">extends</span> <span class="nc">AbstractPlugin</span> <span class="kd">implements</span> <span class="nc">ConfigurationScopeIdentifierProviderPluginInterface</span> <span class="p">{</span> <span class="k">public</span> <span class="k">function</span> <span class="n">getScope</span><span class="p">():</span> <span class="kt">string</span> <span class="p">{</span> <span class="k">return</span> <span class="s1">'locale'</span><span class="p">;</span> <span class="p">}</span> <span class="cd">/** * @return array&lt;string&gt; */</span> <span class="k">public</span> <span class="k">function</span> <span class="n">getIdentifiers</span><span class="p">():</span> <span class="kt">array</span> <span class="p">{</span> <span class="nv">$localeTransfers</span> <span class="o">=</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">getFacade</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">getLocaleCollection</span><span class="p">();</span> <span class="k">return</span> <span class="nb">array_map</span><span class="p">(</span> <span class="k">fn</span> <span class="p">(</span><span class="nv">$localeTransfer</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nv">$localeTransfer</span><span class="o">-&gt;</span><span class="nf">getLocaleNameOrFail</span><span class="p">(),</span> <span class="nv">$localeTransfers</span><span class="p">,</span> <span class="p">);</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <h3 id="step-3-register-the-identifier-provider-plugin">Step 3: Register the Identifier Provider Plugin</h3> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// src/Pyz/Zed/Configuration/ConfigurationDependencyProvider.php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Zed\Configuration</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Pyz\Zed\Locale\Communication\Plugin\Configuration\LocaleConfigurationScopeIdentifierProviderPlugin</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\Configuration\ConfigurationDependencyProvider</span> <span class="k">as</span> <span class="nc">SprykerConfigurationDependencyProvider</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\Store\Communication\Plugin\Configuration\StoreConfigurationScopeIdentifierProviderPlugin</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">ConfigurationDependencyProvider</span> <span class="kd">extends</span> <span class="nc">SprykerConfigurationDependencyProvider</span> <span class="p">{</span> <span class="cd">/** * @return array&lt;\Spryker\Zed\ConfigurationExtension\Dependency\Plugin\ConfigurationScopeIdentifierProviderPluginInterface&gt; */</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">getScopeIdentifierProviderPlugins</span><span class="p">():</span> <span class="kt">array</span> <span class="p">{</span> <span class="k">return</span> <span class="p">[</span> <span class="k">new</span> <span class="nc">StoreConfigurationScopeIdentifierProviderPlugin</span><span class="p">(),</span> <span class="k">new</span> <span class="nc">LocaleConfigurationScopeIdentifierProviderPlugin</span><span class="p">(),</span> <span class="p">];</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <h3 id="step-4-use-the-new-scope-in-yaml-schemas">Step 4: Use the New Scope in YAML Schemas</h3> <p>Add the scope to your setting and group declarations:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">features</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">key</span><span class="pi">:</span> <span class="s">catalog</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Catalog</span> <span class="na">tabs</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">key</span><span class="pi">:</span> <span class="s">display</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Display</span> <span class="na">groups</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">key</span><span class="pi">:</span> <span class="s">labels</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Labels</span> <span class="na">scopes</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">global</span><span class="pi">,</span> <span class="nv">store</span><span class="pi">,</span> <span class="nv">locale</span><span class="pi">]</span> <span class="c1"># Group visible at all three scopes</span> <span class="na">settings</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">key</span><span class="pi">:</span> <span class="s">currency_symbol</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Currency Symbol</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">default_value</span><span class="pi">:</span> <span class="s2">"</span><span class="s">$"</span> <span class="na">scopes</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">global</span><span class="pi">,</span> <span class="nv">store</span><span class="pi">,</span> <span class="nv">locale</span><span class="pi">]</span> <span class="c1"># Setting configurable at all three scopes</span> <span class="na">storefront</span><span class="pi">:</span> <span class="no">true</span> </code></pre></div></div> <p>Run <code>docker/sdk cli console configuration:sync</code> after changes.</p> <h3 id="optional-step-5-create-request-expander-plugins">Optional Step 5: Create Request Expander Plugins</h3> <p>Without an expander, callers must explicitly pass scope context as <code>ConfigurationScopeTransfer</code> objects:</p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kn">use</span> <span class="nc">Generated\Shared\Transfer\ConfigurationScopeTransfer</span><span class="p">;</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">getModuleConfig</span><span class="p">(</span><span class="s1">'catalog:display:labels:currency_symbol'</span><span class="p">,</span> <span class="s1">'$'</span><span class="p">,</span> <span class="p">[</span> <span class="p">(</span><span class="k">new</span> <span class="nc">ConfigurationScopeTransfer</span><span class="p">())</span><span class="o">-&gt;</span><span class="nf">setKey</span><span class="p">(</span><span class="s1">'locale'</span><span class="p">)</span><span class="o">-&gt;</span><span class="nf">setIdentifier</span><span class="p">(</span><span class="s1">'de_DE'</span><span class="p">),</span> <span class="p">]);</span> </code></pre></div></div> <p>With an expander, the current locale is injected automatically into every <code>getModuleConfig()</code> call:</p> <p><strong>Zed expander:</strong></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// src/Pyz/Zed/Locale/Communication/Plugin/Configuration/LocaleConfigurationValueRequestExpanderPlugin.php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Zed\Locale\Communication\Plugin\Configuration</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Generated\Shared\Transfer\ConfigurationScopeTransfer</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Generated\Shared\Transfer\ConfigurationValueRequestTransfer</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\ConfigurationExtension\Dependency\Plugin\ConfigurationValueRequestExpanderPluginInterface</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\Kernel\Communication\AbstractPlugin</span><span class="p">;</span> <span class="cd">/** * @method \Spryker\Zed\Locale\Business\LocaleFacadeInterface getFacade() */</span> <span class="kd">class</span> <span class="nc">LocaleConfigurationValueRequestExpanderPlugin</span> <span class="kd">extends</span> <span class="nc">AbstractPlugin</span> <span class="kd">implements</span> <span class="nc">ConfigurationValueRequestExpanderPluginInterface</span> <span class="p">{</span> <span class="k">public</span> <span class="k">function</span> <span class="n">expand</span><span class="p">(</span> <span class="kt">ConfigurationValueRequestTransfer</span> <span class="nv">$configurationValueRequestTransfer</span><span class="p">,</span> <span class="p">):</span> <span class="kt">ConfigurationValueRequestTransfer</span> <span class="p">{</span> <span class="k">foreach</span> <span class="p">(</span><span class="nv">$configurationValueRequestTransfer</span><span class="o">-&gt;</span><span class="nf">getScopes</span><span class="p">()</span> <span class="k">as</span> <span class="nv">$scope</span><span class="p">)</span> <span class="p">{</span> <span class="k">if</span> <span class="p">(</span><span class="nv">$scope</span><span class="o">-&gt;</span><span class="nf">getKey</span><span class="p">()</span> <span class="o">===</span> <span class="s1">'locale'</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="nv">$configurationValueRequestTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> <span class="nv">$configurationValueRequestTransfer</span><span class="o">-&gt;</span><span class="nf">addScope</span><span class="p">(</span> <span class="p">(</span><span class="k">new</span> <span class="nc">ConfigurationScopeTransfer</span><span class="p">())</span> <span class="o">-&gt;</span><span class="nf">setKey</span><span class="p">(</span><span class="s1">'locale'</span><span class="p">)</span> <span class="o">-&gt;</span><span class="nf">setIdentifier</span><span class="p">(</span><span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">getFacade</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">getCurrentLocale</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">getLocaleNameOrFail</span><span class="p">()),</span> <span class="p">);</span> <span class="k">return</span> <span class="nv">$configurationValueRequestTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <p><strong>Client expander</strong> (same logic, different layer namespace and plugin interface):</p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// src/Pyz/Client/Locale/Plugin/Configuration/LocaleConfigurationValueRequestExpanderPlugin.php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Client\Locale\Plugin\Configuration</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Generated\Shared\Transfer\ConfigurationScopeTransfer</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Generated\Shared\Transfer\ConfigurationValueRequestTransfer</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Client\ConfigurationExtension\Dependency\Plugin\ConfigurationValueRequestExpanderPluginInterface</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Client\Kernel\AbstractPlugin</span><span class="p">;</span> <span class="cd">/** * @method \Spryker\Client\Locale\LocaleClientInterface getClient() */</span> <span class="kd">class</span> <span class="nc">LocaleConfigurationValueRequestExpanderPlugin</span> <span class="kd">extends</span> <span class="nc">AbstractPlugin</span> <span class="kd">implements</span> <span class="nc">ConfigurationValueRequestExpanderPluginInterface</span> <span class="p">{</span> <span class="k">public</span> <span class="k">function</span> <span class="n">expand</span><span class="p">(</span> <span class="kt">ConfigurationValueRequestTransfer</span> <span class="nv">$configurationValueRequestTransfer</span><span class="p">,</span> <span class="p">):</span> <span class="kt">ConfigurationValueRequestTransfer</span> <span class="p">{</span> <span class="k">foreach</span> <span class="p">(</span><span class="nv">$configurationValueRequestTransfer</span><span class="o">-&gt;</span><span class="nf">getScopes</span><span class="p">()</span> <span class="k">as</span> <span class="nv">$scope</span><span class="p">)</span> <span class="p">{</span> <span class="k">if</span> <span class="p">(</span><span class="nv">$scope</span><span class="o">-&gt;</span><span class="nf">getKey</span><span class="p">()</span> <span class="o">===</span> <span class="s1">'locale'</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="nv">$configurationValueRequestTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> <span class="nv">$configurationValueRequestTransfer</span><span class="o">-&gt;</span><span class="nf">addScope</span><span class="p">(</span> <span class="p">(</span><span class="k">new</span> <span class="nc">ConfigurationScopeTransfer</span><span class="p">())</span> <span class="o">-&gt;</span><span class="nf">setKey</span><span class="p">(</span><span class="s1">'locale'</span><span class="p">)</span> <span class="o">-&gt;</span><span class="nf">setIdentifier</span><span class="p">(</span><span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">getClient</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">getCurrentLocale</span><span class="p">()),</span> <span class="p">);</span> <span class="k">return</span> <span class="nv">$configurationValueRequestTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <h3 id="optional-step-51-register-request-expander-plugins">Optional Step 5.1: Register Request Expander Plugins</h3> <p><strong>Zed:</strong></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// src/Pyz/Zed/Configuration/ConfigurationDependencyProvider.php</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">getConfigurationValueRequestExpanderPlugins</span><span class="p">():</span> <span class="kt">array</span> <span class="p">{</span> <span class="k">return</span> <span class="p">[</span> <span class="k">new</span> <span class="nc">StoreConfigurationValueRequestExpanderPlugin</span><span class="p">(),</span> <span class="k">new</span> <span class="nc">LocaleConfigurationValueRequestExpanderPlugin</span><span class="p">(),</span> <span class="p">];</span> <span class="p">}</span> </code></pre></div></div> <p><strong>Client:</strong></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// src/Pyz/Client/Configuration/ConfigurationDependencyProvider.php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Client\Configuration</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Pyz\Client\Locale\Plugin\Configuration\LocaleConfigurationValueRequestExpanderPlugin</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Client\Configuration\ConfigurationDependencyProvider</span> <span class="k">as</span> <span class="nc">SprykerConfigurationDependencyProvider</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">ConfigurationDependencyProvider</span> <span class="kd">extends</span> <span class="nc">SprykerConfigurationDependencyProvider</span> <span class="p">{</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">getConfigurationValueRequestExpanderPlugins</span><span class="p">():</span> <span class="kt">array</span> <span class="p">{</span> <span class="k">return</span> <span class="p">[</span> <span class="k">new</span> <span class="nc">StoreConfigurationValueRequestExpanderPlugin</span><span class="p">(),</span> <span class="k">new</span> <span class="nc">LocaleConfigurationValueRequestExpanderPlugin</span><span class="p">(),</span> <span class="p">];</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <h2 id="how-value-resolution-works">How Value Resolution Works</h2> <p>When <code>getModuleConfig('catalog:display:labels:currency_symbol', '$')</code> is called with expander plugins providing <code>locale=de_DE</code> and <code>store=DE</code>:</p> <ol> <li>Check <code>locale:de_DE</code> – value saved specifically for German locale?</li> <li>Not found -&gt; check parent <code>store:DE</code> – value saved for DE store?</li> <li>Not found -&gt; check parent <code>global</code> – value saved globally?</li> <li>Not found -&gt; return <code>default_value</code> from YAML schema (<code>&quot;$&quot;</code>)</li> <li>Schema has no such key -&gt; return <code>$default</code> argument (<code>'$'</code>)</li> </ol> <p>The first non-null value wins.</p> <h2 id="advanced-use-cases">Advanced Use Cases</h2> <p>Custom scopes enable dynamic configuration scenarios beyond static identifiers like <code>store</code> or <code>locale</code>. This section covers two common advanced patterns: calculated scopes and A/B testing.</p> <h3 id="calculated-scopes">Calculated Scopes</h3> <p>Calculated scopes determine their identifier at runtime based on request context. Unlike static scopes where identifiers are predefined (such as store codes), calculated scopes derive their value from dynamic data like user attributes, request headers, or external services.</p> <h4 id="example-region-based-configuration-by-ip-address">Example: Region-Based Configuration by IP Address</h4> <p>You can create a <code>region</code> scope that determines the user’s geographic region from their IP address. This enables region-specific configurations without requiring users to explicitly select their region.</p> <p><strong>Step 1: Define the region scope in Shared Configuration:</strong></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// src/Pyz/Shared/Configuration/ConfigurationConfig.php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Shared\Configuration</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Shared\Configuration\ConfigurationConfig</span> <span class="k">as</span> <span class="nc">SprykerConfigurationConfig</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">ConfigurationConfig</span> <span class="kd">extends</span> <span class="nc">SprykerConfigurationConfig</span> <span class="p">{</span> <span class="k">public</span> <span class="k">const</span> <span class="no">string</span> <span class="no">SCOPE_REGION</span> <span class="o">=</span> <span class="s1">'region'</span><span class="p">;</span> <span class="k">public</span> <span class="k">function</span> <span class="n">getAvailableScopes</span><span class="p">():</span> <span class="kt">array</span> <span class="p">{</span> <span class="k">return</span> <span class="nb">array_merge</span><span class="p">(</span><span class="k">parent</span><span class="o">::</span><span class="nf">getAvailableScopes</span><span class="p">(),</span> <span class="p">[</span> <span class="k">static</span><span class="o">::</span><span class="no">SCOPE_REGION</span><span class="p">,</span> <span class="p">]);</span> <span class="p">}</span> <span class="k">public</span> <span class="k">function</span> <span class="n">getScopeHierarchy</span><span class="p">():</span> <span class="kt">array</span> <span class="p">{</span> <span class="k">return</span> <span class="nb">array_merge</span><span class="p">(</span><span class="k">parent</span><span class="o">::</span><span class="nf">getScopeHierarchy</span><span class="p">(),</span> <span class="p">[</span> <span class="k">static</span><span class="o">::</span><span class="no">SCOPE_REGION</span> <span class="o">=&gt;</span> <span class="k">static</span><span class="o">::</span><span class="no">SCOPE_STORE</span><span class="p">,</span> <span class="c1">// Region inherits from global</span> <span class="p">]);</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <p><strong>Step 2: Create an identifier provider with region definitions:</strong></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// src/Pyz/Zed/Region/Communication/Plugin/Configuration/RegionConfigurationScopeIdentifierProviderPlugin.php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Zed\Region\Communication\Plugin\Configuration</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\ConfigurationExtension\Dependency\Plugin\ConfigurationScopeIdentifierProviderPluginInterface</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\Kernel\Communication\AbstractPlugin</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">RegionConfigurationScopeIdentifierProviderPlugin</span> <span class="kd">extends</span> <span class="nc">AbstractPlugin</span> <span class="kd">implements</span> <span class="nc">ConfigurationScopeIdentifierProviderPluginInterface</span> <span class="p">{</span> <span class="k">public</span> <span class="k">function</span> <span class="n">getScope</span><span class="p">():</span> <span class="kt">string</span> <span class="p">{</span> <span class="k">return</span> <span class="s1">'region'</span><span class="p">;</span> <span class="p">}</span> <span class="cd">/** * @return array&lt;string&gt; */</span> <span class="k">public</span> <span class="k">function</span> <span class="n">getIdentifiers</span><span class="p">():</span> <span class="kt">array</span> <span class="p">{</span> <span class="c1">// Define available regions for the backoffice scope switcher</span> <span class="k">return</span> <span class="p">[</span> <span class="s1">'eu-west'</span><span class="p">,</span> <span class="s1">'eu-east'</span><span class="p">,</span> <span class="s1">'us-west'</span><span class="p">,</span> <span class="s1">'us-east'</span><span class="p">,</span> <span class="s1">'apac'</span><span class="p">,</span> <span class="p">];</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <p><strong>Step 3: Create a request expander that calculates the region from IP:</strong></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// src/Pyz/Client/Region/Plugin/Configuration/RegionConfigurationValueRequestExpanderPlugin.php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Client\Region\Plugin\Configuration</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Generated\Shared\Transfer\ConfigurationScopeTransfer</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Generated\Shared\Transfer\ConfigurationValueRequestTransfer</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Client\ConfigurationExtension\Dependency\Plugin\ConfigurationValueRequestExpanderPluginInterface</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Client\Kernel\AbstractPlugin</span><span class="p">;</span> <span class="cd">/** * @method \Pyz\Client\Region\RegionClientInterface getClient() */</span> <span class="kd">class</span> <span class="nc">RegionConfigurationValueRequestExpanderPlugin</span> <span class="kd">extends</span> <span class="nc">AbstractPlugin</span> <span class="kd">implements</span> <span class="nc">ConfigurationValueRequestExpanderPluginInterface</span> <span class="p">{</span> <span class="k">public</span> <span class="k">function</span> <span class="n">expand</span><span class="p">(</span> <span class="kt">ConfigurationValueRequestTransfer</span> <span class="nv">$configurationValueRequestTransfer</span><span class="p">,</span> <span class="p">):</span> <span class="kt">ConfigurationValueRequestTransfer</span> <span class="p">{</span> <span class="k">foreach</span> <span class="p">(</span><span class="nv">$configurationValueRequestTransfer</span><span class="o">-&gt;</span><span class="nf">getScopes</span><span class="p">()</span> <span class="k">as</span> <span class="nv">$scope</span><span class="p">)</span> <span class="p">{</span> <span class="k">if</span> <span class="p">(</span><span class="nv">$scope</span><span class="o">-&gt;</span><span class="nf">getKey</span><span class="p">()</span> <span class="o">===</span> <span class="s1">'region'</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="nv">$configurationValueRequestTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> <span class="c1">// Calculate region from the current request's IP address</span> <span class="nv">$regionIdentifier</span> <span class="o">=</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">getClient</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">getRegionByCurrentIp</span><span class="p">();</span> <span class="nv">$configurationValueRequestTransfer</span><span class="o">-&gt;</span><span class="nf">addScope</span><span class="p">(</span> <span class="p">(</span><span class="k">new</span> <span class="nc">ConfigurationScopeTransfer</span><span class="p">())</span> <span class="o">-&gt;</span><span class="nf">setKey</span><span class="p">(</span><span class="s1">'region'</span><span class="p">)</span> <span class="o">-&gt;</span><span class="nf">setIdentifier</span><span class="p">(</span><span class="nv">$regionIdentifier</span><span class="p">),</span> <span class="p">);</span> <span class="k">return</span> <span class="nv">$configurationValueRequestTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <p><strong>Step 4: Implement the region detection logic in the client:</strong></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// src/Pyz/Client/Region/RegionClient.php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Client\Region</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Client\Kernel\AbstractClient</span><span class="p">;</span> <span class="cd">/** * @method \Pyz\Client\Region\RegionFactory getFactory() */</span> <span class="kd">class</span> <span class="nc">RegionClient</span> <span class="kd">extends</span> <span class="nc">AbstractClient</span> <span class="kd">implements</span> <span class="nc">RegionClientInterface</span> <span class="p">{</span> <span class="k">public</span> <span class="k">function</span> <span class="n">getRegionByCurrentIp</span><span class="p">():</span> <span class="kt">string</span> <span class="p">{</span> <span class="k">return</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">getFactory</span><span class="p">()</span> <span class="o">-&gt;</span><span class="nf">createRegionResolver</span><span class="p">()</span> <span class="o">-&gt;</span><span class="nf">resolveRegionByIp</span><span class="p">(</span><span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">getFactory</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">getRequestStack</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">getCurrentRequest</span><span class="p">()</span><span class="o">?-&gt;</span><span class="nf">getClientIp</span><span class="p">());</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <p>With this setup, configuration values automatically resolve based on the user’s geographic region. For example, you can configure different shipping options, payment methods, or promotional content for users in different regions.</p> <h3 id="ab-testing-with-custom-scopes">A/B Testing with Custom Scopes</h3> <p>Custom scopes provide a mechanism for A/B testing by assigning users to experiment variants. This approach enables you to test different configuration values and measure their impact on user behavior.</p> <h4 id="example-experiment-scope-for-ab-testing">Example: Experiment Scope for A/B Testing</h4> <p><strong>Step 1: Define the experiment scope:</strong></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// src/Pyz/Shared/Configuration/ConfigurationConfig.php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Shared\Configuration</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Shared\Configuration\ConfigurationConfig</span> <span class="k">as</span> <span class="nc">SprykerConfigurationConfig</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">ConfigurationConfig</span> <span class="kd">extends</span> <span class="nc">SprykerConfigurationConfig</span> <span class="p">{</span> <span class="k">public</span> <span class="k">const</span> <span class="no">string</span> <span class="no">SCOPE_EXPERIMENT</span> <span class="o">=</span> <span class="s1">'experiment'</span><span class="p">;</span> <span class="k">public</span> <span class="k">function</span> <span class="n">getAvailableScopes</span><span class="p">():</span> <span class="kt">array</span> <span class="p">{</span> <span class="k">return</span> <span class="nb">array_merge</span><span class="p">(</span><span class="k">parent</span><span class="o">::</span><span class="nf">getAvailableScopes</span><span class="p">(),</span> <span class="p">[</span> <span class="k">static</span><span class="o">::</span><span class="no">SCOPE_EXPERIMENT</span><span class="p">,</span> <span class="p">]);</span> <span class="p">}</span> <span class="k">public</span> <span class="k">function</span> <span class="n">getScopeHierarchy</span><span class="p">():</span> <span class="kt">array</span> <span class="p">{</span> <span class="k">return</span> <span class="nb">array_merge</span><span class="p">(</span><span class="k">parent</span><span class="o">::</span><span class="nf">getScopeHierarchy</span><span class="p">(),</span> <span class="p">[</span> <span class="c1">// Experiment is the most specific scope, inheriting from store</span> <span class="k">static</span><span class="o">::</span><span class="no">SCOPE_EXPERIMENT</span> <span class="o">=&gt;</span> <span class="k">static</span><span class="o">::</span><span class="no">SCOPE_STORE</span><span class="p">,</span> <span class="p">]);</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <p><strong>Step 2: Create an identifier provider for experiment variants:</strong></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// src/Pyz/Zed/Experiment/Communication/Plugin/Configuration/ExperimentConfigurationScopeIdentifierProviderPlugin.php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Zed\Experiment\Communication\Plugin\Configuration</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\ConfigurationExtension\Dependency\Plugin\ConfigurationScopeIdentifierProviderPluginInterface</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\Kernel\Communication\AbstractPlugin</span><span class="p">;</span> <span class="cd">/** * @method \Pyz\Zed\Experiment\Business\ExperimentFacadeInterface getFacade() */</span> <span class="kd">class</span> <span class="nc">ExperimentConfigurationScopeIdentifierProviderPlugin</span> <span class="kd">extends</span> <span class="nc">AbstractPlugin</span> <span class="kd">implements</span> <span class="nc">ConfigurationScopeIdentifierProviderPluginInterface</span> <span class="p">{</span> <span class="k">public</span> <span class="k">function</span> <span class="n">getScope</span><span class="p">():</span> <span class="kt">string</span> <span class="p">{</span> <span class="k">return</span> <span class="s1">'experiment'</span><span class="p">;</span> <span class="p">}</span> <span class="cd">/** * @return array&lt;string&gt; */</span> <span class="k">public</span> <span class="k">function</span> <span class="n">getIdentifiers</span><span class="p">():</span> <span class="kt">array</span> <span class="p">{</span> <span class="c1">// Return all active experiment variants from the database</span> <span class="c1">// This allows configuring values for each variant in the backoffice</span> <span class="k">return</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">getFacade</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">getActiveExperimentVariantIdentifiers</span><span class="p">();</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <p><strong>Step 3: Create a request expander that assigns users to variants:</strong></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// src/Pyz/Client/Experiment/Plugin/Configuration/ExperimentConfigurationValueRequestExpanderPlugin.php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Client\Experiment\Plugin\Configuration</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Generated\Shared\Transfer\ConfigurationScopeTransfer</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Generated\Shared\Transfer\ConfigurationValueRequestTransfer</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Client\ConfigurationExtension\Dependency\Plugin\ConfigurationValueRequestExpanderPluginInterface</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Client\Kernel\AbstractPlugin</span><span class="p">;</span> <span class="cd">/** * @method \Pyz\Client\Experiment\ExperimentClientInterface getClient() */</span> <span class="kd">class</span> <span class="nc">ExperimentConfigurationValueRequestExpanderPlugin</span> <span class="kd">extends</span> <span class="nc">AbstractPlugin</span> <span class="kd">implements</span> <span class="nc">ConfigurationValueRequestExpanderPluginInterface</span> <span class="p">{</span> <span class="k">public</span> <span class="k">function</span> <span class="n">expand</span><span class="p">(</span> <span class="kt">ConfigurationValueRequestTransfer</span> <span class="nv">$configurationValueRequestTransfer</span><span class="p">,</span> <span class="p">):</span> <span class="kt">ConfigurationValueRequestTransfer</span> <span class="p">{</span> <span class="k">foreach</span> <span class="p">(</span><span class="nv">$configurationValueRequestTransfer</span><span class="o">-&gt;</span><span class="nf">getScopes</span><span class="p">()</span> <span class="k">as</span> <span class="nv">$scope</span><span class="p">)</span> <span class="p">{</span> <span class="k">if</span> <span class="p">(</span><span class="nv">$scope</span><span class="o">-&gt;</span><span class="nf">getKey</span><span class="p">()</span> <span class="o">===</span> <span class="s1">'experiment'</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="nv">$configurationValueRequestTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> <span class="c1">// Get the experiment variant for the current user</span> <span class="c1">// This can be based on session, customer ID, or random assignment</span> <span class="nv">$experimentVariant</span> <span class="o">=</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">getClient</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">getCurrentUserExperimentVariant</span><span class="p">(</span> <span class="nv">$configurationValueRequestTransfer</span><span class="o">-&gt;</span><span class="nf">getKey</span><span class="p">(),</span> <span class="p">);</span> <span class="k">if</span> <span class="p">(</span><span class="nv">$experimentVariant</span> <span class="o">===</span> <span class="kc">null</span><span class="p">)</span> <span class="p">{</span> <span class="c1">// User is not part of any experiment, skip adding the scope</span> <span class="c1">// Value resolution falls back to the parent scope (store)</span> <span class="k">return</span> <span class="nv">$configurationValueRequestTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="nv">$configurationValueRequestTransfer</span><span class="o">-&gt;</span><span class="nf">addScope</span><span class="p">(</span> <span class="p">(</span><span class="k">new</span> <span class="nc">ConfigurationScopeTransfer</span><span class="p">())</span> <span class="o">-&gt;</span><span class="nf">setKey</span><span class="p">(</span><span class="s1">'experiment'</span><span class="p">)</span> <span class="o">-&gt;</span><span class="nf">setIdentifier</span><span class="p">(</span><span class="nv">$experimentVariant</span><span class="p">),</span> <span class="p">);</span> <span class="k">return</span> <span class="nv">$configurationValueRequestTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <p><strong>Step 4: Implement the experiment assignment logic:</strong></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// src/Pyz/Client/Experiment/ExperimentClient.php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Client\Experiment</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Client\Kernel\AbstractClient</span><span class="p">;</span> <span class="cd">/** * @method \Pyz\Client\Experiment\ExperimentFactory getFactory() */</span> <span class="kd">class</span> <span class="nc">ExperimentClient</span> <span class="kd">extends</span> <span class="nc">AbstractClient</span> <span class="kd">implements</span> <span class="nc">ExperimentClientInterface</span> <span class="p">{</span> <span class="cd">/** * Returns the experiment variant identifier for the current user. * Returns null if the user is not enrolled in any experiment. */</span> <span class="k">public</span> <span class="k">function</span> <span class="n">getCurrentUserExperimentVariant</span><span class="p">(</span><span class="kt">string</span> <span class="nv">$settingKey</span><span class="p">):</span> <span class="kt">?string</span> <span class="p">{</span> <span class="k">return</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">getFactory</span><span class="p">()</span> <span class="o">-&gt;</span><span class="nf">createExperimentAssigner</span><span class="p">()</span> <span class="o">-&gt;</span><span class="nf">getVariantForUser</span><span class="p">(</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">getFactory</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">getSessionClient</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">getId</span><span class="p">(),</span> <span class="nv">$settingKey</span><span class="p">,</span> <span class="p">);</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <h4 id="using-ab-testing-in-yaml-schemas">Using A/B Testing in YAML Schemas</h4> <p>Define settings that support experiment variants:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">features</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">key</span><span class="pi">:</span> <span class="s">checkout</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Checkout</span> <span class="na">tabs</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">key</span><span class="pi">:</span> <span class="s">layout</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Layout</span> <span class="na">groups</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">key</span><span class="pi">:</span> <span class="s">buttons</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Buttons</span> <span class="na">scopes</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">global</span><span class="pi">,</span> <span class="nv">store</span><span class="pi">,</span> <span class="nv">experiment</span><span class="pi">]</span> <span class="na">settings</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">key</span><span class="pi">:</span> <span class="s">checkout_button_color</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Checkout Button Color</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">default_value</span><span class="pi">:</span> <span class="s2">"</span><span class="s">blue"</span> <span class="na">scopes</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">global</span><span class="pi">,</span> <span class="nv">store</span><span class="pi">,</span> <span class="nv">experiment</span><span class="pi">]</span> <span class="na">storefront</span><span class="pi">:</span> <span class="no">true</span> <span class="pi">-</span> <span class="na">key</span><span class="pi">:</span> <span class="s">checkout_button_text</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Checkout Button Text</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">default_value</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Complete</span><span class="nv"> </span><span class="s">Purchase"</span> <span class="na">scopes</span><span class="pi">:</span> <span class="pi">[</span><span class="nv">global</span><span class="pi">,</span> <span class="nv">store</span><span class="pi">,</span> <span class="nv">experiment</span><span class="pi">]</span> <span class="na">storefront</span><span class="pi">:</span> <span class="no">true</span> </code></pre></div></div> <p>In the Back Office, you can then configure different values for each experiment variant:</p> <ul> <li><code>experiment:control</code> — <code>checkout_button_color: blue</code>, <code>checkout_button_text: Complete Purchase</code></li> <li><code>experiment:variant_a</code> — <code>checkout_button_color: green</code>, <code>checkout_button_text: Buy Now</code></li> <li><code>experiment:variant_b</code> — <code>checkout_button_color: orange</code>, <code>checkout_button_text: Place Order</code></li> </ul> <h4 id="best-practices-for-ab-testing-scopes">Best Practices for A/B Testing Scopes</h4> <table> <thead> <tr> <th>Practice</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>Consistent assignment</td> <td>Ensure users see the same variant throughout their session by persisting the assignment in session or database.</td> </tr> <tr> <td>Graceful fallback</td> <td>When a user is not part of an experiment, the value resolution automatically falls back to the parent scope.</td> </tr> <tr> <td>Setting-level experiments</td> <td>Pass the setting key to the assigner to run different experiments on different settings.</td> </tr> <tr> <td>Analytics integration</td> <td>Track which variant each user sees to measure the impact of configuration changes.</td> </tr> </tbody> </table> <h3 id="combining-multiple-custom-scopes">Combining Multiple Custom Scopes</h3> <p>You can combine calculated scopes with static scopes to create sophisticated targeting. For example:</p> <div class="language-text highlighter-rouge"><div class="highlight"><pre class="highlight"><code>experiment (most specific) -&gt; region -&gt; store -&gt; global (least specific) </code></pre></div></div> <p>This hierarchy enables scenarios like:</p> <ul> <li>Default value for all users (global)</li> <li>Store-specific override (store)</li> <li>Region-specific customization based on IP (region)</li> <li>A/B test variant for users in the experiment (experiment)</li> </ul> <p>When a user in the <code>us-west</code> region is assigned to <code>variant_a</code> of an experiment in the <code>US</code> store, the resolution order is:</p> <ol> <li><code>experiment:variant_a</code> — check experiment-specific value</li> <li><code>region:us-west</code> — check region-specific value</li> <li><code>store:US</code> — check store-specific value</li> <li><code>global</code> — check global value</li> <li><code>default_value</code> — use schema default</li> </ol> Fri, 13 Mar 2026 15:59:05 +0000 https://docs.spryker.com/docs/dg/dev/backend-development/configuration-management/custom-scopes.html https://docs.spryker.com/docs/dg/dev/backend-development/configuration-management/custom-scopes.html